> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pocketsflow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Developer setup

> Set up a local environment to build against the Pocketsflow API — keys, test vs. live mode, checkout sessions, and testing webhooks locally.

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.

<Info>
  **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.
</Info>

## 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
```

<Warning>
  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.
</Warning>

## 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](/api-reference/introduction).

## 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:

<CodeGroup>
  ```bash cURL theme={null}
  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" }
    }'
  ```

  ```js Node.js theme={null}
  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`
  ```
</CodeGroup>

The response is `{ "id": "cs_…", "url": "https://<yourstore>.pocketsflow.com/checkout?…" }`.
Open `url` in a browser to complete a test purchase. See
[Custom platforms](/integrations/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:

<Steps>
  <Step title="Run your handler locally">
    Start your webhook endpoint (for example on `http://localhost:3000/webhooks/pocketsflow`).
  </Step>

  <Step title="Open a public tunnel">
    Use a tunneling tool to get a public HTTPS URL that forwards to your local
    port:

    ```bash theme={null}
    # examples — use whichever you have installed
    ngrok http 3000
    # or
    cloudflared tunnel --url http://localhost:3000
    ```
  </Step>

  <Step title="Register the tunnel URL as a webhook">
    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.
  </Step>

  <Step title="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](/api-webhooks/consuming-webhooks).
  </Step>

  <Step title="Send a test event">
    Use **Developers → Webhooks → ⋯ → Send test** to exercise your handler
    without placing an order.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

## 6. Build faster with an AI agent

Point an MCP-capable editor at the [Pocketsflow MCP server](/api-reference/mcp-server)
to call the API as your account while you develop, and load these docs as
context:

* [MCP setup guide](/ai-tools/mcp) — Claude Desktop, Cursor, ChatGPT copy-paste
* [Claude Code + Pocketsflow](/ai-tools/claude-code)
* [Cursor + Pocketsflow](/ai-tools/cursor)
* [Windsurf + Pocketsflow](/ai-tools/windsurf)

## 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.

## Related topics

* [Integrations overview](/integrations/overview)
* [Custom platforms](/integrations/custom-platforms)
* [WooCommerce](/integrations/woocommerce)
* [API reference](/api-reference/introduction)
* [Consuming webhooks](/api-webhooks/consuming-webhooks)
* [Authentication & security](/api-webhooks/authentication-and-security)