Developer setup

This guide gets you from zero to a working local development environment for the Pocketsflow HTTP API: creating keys, working in test mode, calling the API, and receiving webhooks on your machine.

Prerequisites

A Pocketsflow account with at least one product.
The ability to run a small server (any language) and expose it publicly for webhook testing.

1. Create API keys

In the dashboard, go to Developers → API keys and create a key. Keys are scoped to your account and come in two flavors:

Prefix	Mode	Use
`pk_test_…`	Test	Sandbox data. No real money moves. Build here first.
`pk_live_…`	Live	Real products, customers, and payments.

Send the key as a Bearer token on every request:

Authorization: Bearer pk_test_xxxxxxxxxxxxxxxxxxxxxxxx

API keys are secrets — treat them like passwords. Keep them server-side and in environment variables, never in client code or your repo. Use a dedicated, revocable key per integration, and rotate if one leaks.

2. Base URL and the interactive reference

Base URL: https://api.pocketsflow.com
Interactive reference (Scalar): https://api.pocketsflow.com/docs
OpenAPI spec: https://api.pocketsflow.com/docs.json

The OpenAPI spec is the authoritative contract — load it into your HTTP client, codegen, or AI editor’s docs index. See API reference.

3. Test vs. live mode

Test mode gives you a full sandbox:

Everything you create with a pk_test_… key (products, checkout sessions, orders) lives in test data, separate from live data.
Test-mode checkouts don’t move real money, and you receive test-mode webhooks so you can validate the whole flow.
Switch to a pk_live_… key only once the flow works end to end.

Build and verify against test mode first; promote to live as the last step.

4. Make your first call

Create a checkout session and get a hosted URL to redirect a buyer to:

curl -X POST https://api.pocketsflow.com/checkout/sessions \
  -H "Authorization: Bearer pk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "65a1b2c3d4e5f6a7b8c9d0e1",
    "successUrl": "http://localhost:3000/thank-you",
    "cancelUrl": "http://localhost:3000/cart",
    "metadata": { "external_order_id": "LOCAL-1" }
  }'

const res = await fetch("https://api.pocketsflow.com/checkout/sessions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POCKETSFLOW_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    productId: "65a1b2c3d4e5f6a7b8c9d0e1",
    successUrl: "http://localhost:3000/thank-you",
    cancelUrl: "http://localhost:3000/cart",
    metadata: { external_order_id: "LOCAL-1" },
  }),
});
const { id, url } = await res.json(); // redirect the buyer to `url`

The response is { "id": "cs_…", "url": "https://<yourstore>.pocketsflow.com/checkout?…" }. Open url in a browser to complete a test purchase. See Custom platforms for the full field list.

5. Receive webhooks locally

Webhooks are the source of truth for payment. To receive them on your machine, expose your local server with a tunnel:

Run your handler locally

Start your webhook endpoint (for example on http://localhost:3000/webhooks/pocketsflow).

Open a public tunnel

Use a tunneling tool to get a public HTTPS URL that forwards to your local port:

# examples — use whichever you have installed
ngrok http 3000
# or
cloudflared tunnel --url http://localhost:3000

In Developers → Webhooks (or via POST /webhooks), point a webhook at https://<your-tunnel>/webhooks/pocketsflow and subscribe to events like order.completed. Save the signing secret shown once.

Verify the signature

On each delivery, compute HMAC-SHA256 over the RAW body with your signing secret and compare (timing-safe) to X-Pocketsflow-Signature. See Consuming webhooks.

Send a test event

Use Developers → Webhooks → ⋯ → Send test to exercise your handler without placing an order.

Always verify against the raw, unparsed request body. Re-serializing the JSON can reorder keys and break the signature check. Make handlers idempotent — an event may be re-sent.

6. Build faster with an AI agent

Point an MCP-capable editor at the Pocketsflow MCP server to call the API as your account while you develop, and load these docs as context:

MCP setup guide — Claude Desktop, Cursor, ChatGPT copy-paste
Claude Code + Pocketsflow
Cursor + Pocketsflow
Windsurf + Pocketsflow

Go-live checklist

Flow works end to end with a pk_test_… key.
Webhook signature verification passes on real deliveries.
Handlers are idempotent and reconcile via metadata.
Secrets are in environment variables, not in the repo.
Swapped to a pk_live_… key and a production webhook endpoint.

Integrations

Developer & AI tools

1. Create API keys

2. Base URL and the interactive reference

3. Test vs. live mode

4. Make your first call

5. Receive webhooks locally

6. Build faster with an AI agent

Go-live checklist

​1. Create API keys

​2. Base URL and the interactive reference

​3. Test vs. live mode

​4. Make your first call

​5. Receive webhooks locally

​6. Build faster with an AI agent

​Go-live checklist

​Related topics

1. Create API keys

2. Base URL and the interactive reference

3. Test vs. live mode

4. Make your first call

5. Receive webhooks locally

6. Build faster with an AI agent

Go-live checklist

Related topics