Quickstart

1. Create an app

Sign in to the BirrPay dashboard, open Apps and create your first app. Give it the domain(s) it will accept payments from (e.g. shop.example.com) — BirrPay uses this allowlist to protect your publishable key and inline checkout.

2. Get your keys

Open the app's API Keys tab. You get a pair for each mode:

• pk_test_ / pk_live_ — publishable. Safe in the browser, can only create checkout sessions.
• sk_test_ / sk_live_ — secret. Server-side only, grants full API access. Shown once: store it securely.

3. Create a checkout session (server-side)

curl -X POST https://birrpay-beta1b.pages.dev/api/v1/checkout/sessions \
  -H "Authorization: Bearer sk_test_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_8xk29f" \
  -d '{
    "amount": 15000,
    "currency": "NGN",
    "customer": { "email": "payer@example.com", "name": "Aisha Bello" },
    "reference": "order_8xk29f",
    "metadata": { "order_id": "8xk29f" }
  }'

The response contains a client_token used to open the checkout, plus an authoritative reference.

4. Take the payment

Inline (recommended, zero redirect): drop the widget into your page and open it when the user clicks Pay. The payer never leaves your site.

<script src="https://birrpay-beta1b.pages.dev/embed/birrpay.js"></script>
<script>
  BirrPay.open({
    publicKey: 'pk_test_YOUR_PUBLIC_KEY',
    clientToken: 'CLIENT_TOKEN_FROM_YOUR_SERVER',
    onSuccess: (tx) => console.log('paid', tx.reference),
    onClose: () => console.log('closed'),
  });
</script>

Hosted: redirect the payer to checkout_url from the session response.

5. Verify (server-side)

Never trust the browser alone. Verify the payment from your backend:

curl https://birrpay-beta1b.pages.dev/api/v1/transactions/order_8xk29f \
  -H "Authorization: Bearer sk_test_YOUR_SECRET"

BirrPay also sends a signed webhook to your app's endpoint on every state change — see the Webhooks guide.