Introduction

# Goal — ship your first JamiDev checkout end-to-end

You are integrating JamiDev (https://dev.jami.bio/docs) into my project. Take me from zero
to a working checkout: product, checkout session, payment, webhook, fulfilled order.

## My application context

<my_stack>
Stack: [framework + language, e.g. Next.js 15 + TypeScript]
Surface: [web | backend-only | mobile webview]
Use case: [one-time digital product | subscription | donation]
Database: [Postgres | MySQL | Mongo]
</my_stack>

## Steps

1. **Enable Developer Mode & create a sandbox org** — requires a KYC-verified Jami account.
   In the dashboard: Settings → Developer Mode, then switch to a sandbox organization
   (simulated payments, nothing real moves).

2. **Create a product** — Store → Products → New product. Pick a pricing model (`fixed`,
   `pwyw` or `free` — locked after creation). Publish it and copy the product id.

3. **Get an API token** — Developer → API Tokens. Save it as `JAMI_TOKEN`
   (`jamidev_test_…` in sandbox, `jamidev_live_…` in production).

4. **Install the SDK and create a checkout**

```bash
npm install jami-sdk
```

```ts
import { Jami } from 'jami-sdk';

const jami = new Jami({ token: process.env.JAMI_TOKEN! });

const checkout = await jami.createCheckout({
  productId: '<product id>',
  customer: { email: 'buyer@example.com', phone: '251900000001' }, // magic sandbox success number
  gateway: 'telebirr', // 'telebirr' | 'mpesa' | 'cbe'
});
```

Free products resolve instantly (`orderId` present). Paid products return `mode: 'redirect'`
(send the buyer to `checkoutUrl`) or `mode: 'direct'` (buyer confirms on their phone — poll next).

5. **Wait for payment**

```ts
if (!('orderId' in checkout)) {
  const status = await jami.waitForCheckout(checkout.sessionId);
  // status.status: 'completed' | 'expired', status.orderId
}
```

6. **Register a webhook and verify deliveries** — Automation → Webhooks → add your endpoint
   URL, save the returned secret as `JAMI_WEBHOOK_SECRET`. Subscribe to `order.created`,
   `order.completed`, `benefit.granted`, `checkout.session.expired`.

```ts
import { JamiSignatureError } from 'jami-sdk';

const event = await jami.webhooks.verify({
  payload: rawBody, // exactly as received, do not JSON.parse first
  signature: req.headers['x-jamidev-signature'],
  secret: process.env.JAMI_WEBHOOK_SECRET!,
});
// event.type: 'order.created' | 'order.completed' | 'benefit.granted' | 'checkout.session.expired'
```

Respond `2xx` within 10 seconds. Handle idempotently — retries and manual resends can
redeliver the same `event.id`.

7. **List orders (fallback / reconciliation)**

```ts
const { items, total } = await jami.listOrders({ status: 'paid', page: 1, limit: 20 });
```

8. **Go live** — Settings → Environment → switch to production, register production
   webhook endpoints (subscriptions are per-organization), and issue a fresh `jamidev_live_`
   token.

## Failure modes

- Missing/invalid token → `401`, with `.hint` set when the token was minted for the org's
  other environment (re-issue it).
- Validation error → `400`, message names the offending field.
- `POST /checkout` limited to 20 requests / 5 minutes / IP → `429`.
- Webhook signature mismatch, malformed header, or stale timestamp (>300s) → throws
  `JamiSignatureError`; treat the delivery as untrusted.

## Sources of truth (cross-check before shipping)

- https://dev.jami.bio/llms-full.txt — full docs in one fetch
- https://dev.jami.bio/openapi.json — machine-readable REST spec
- /docs/api — raw REST reference (checkout, orders)
- /docs/sdk — typed SDK reference and error types
- /docs/webhooks — event payloads and signature verification