Developer docs
Integrate protected payments.
Create a payment, redirect the buyer to checkout, and fulfil on a single signed webhook. Most teams are live in an afternoon.
Introduction
Pincode holds a buyer’s payment safely at a licensed partner bank until they confirm delivery. You create a payment, send the buyer to checkout, and fulfil the order the moment the money is held. It’s non-custodial — the money never sits with Pincode, or with you, until it’s released.
Every integration is the same three moves:
- 1. You create a payment for the order and redirect the buyer to its
checkoutUrl. - 2. The buyer pays; you receive a
payment.heldwebhook — fulfil now. - 3. They confirm delivery (or the window lapses); you receive
payment.releasedand the payout settles.
Authentication
Authenticate every request with a secret API key as a bearer token. Keys are server-side only — never ship one to a browser or mobile app, and always call over HTTPS.
Authorization: Bearer sk_live_…Sandbox keys are sk_test_…; live keys are sk_live_…. Your first keys are issued when your business is approved (KYB); after that you rotate them yourself from the dashboard. Never trust a client-supplied amount — always set amountMinor on your server.
Quickstart
Create a payment for an order. The response gives you a checkoutUrl — redirect the buyer there to pay.
curl https://api.pincode.africa/api/v1/payments \
-H "Authorization: Bearer sk_live_…" \
-H "Idempotency-Key: order-2026-0001" \
-H "Content-Type: application/json" \
-d '{
"customerId": "usr_ada",
"amountMinor": "4500000", // ₦45,000 in kobo — integer, set server-side
"reference": "order-2026-0001", // your order id; reconcile by joining on this
"windowHours": 72
}'// 201 Created
{
"id": "pay_01HZX9AB…",
"status": "awaiting_funding",
"reference": "order-2026-0001",
"amountMinor": "4500000",
"currency": "NGN",
"escrow": true,
"windowHours": 72,
"checkoutUrl": "https://checkout.pincode.com/pay/8F2A19",
"createdAt": "2026-08-06T12:00:00.000Z"
}Then verify and handle the payment.held webhook to fulfil the order. That’s the whole loop — see Webhooks for the signature check.
Payment lifecycle
You integrate against a payment’s state, not a maze of endpoints. Every payment moves through these:
| State | What it means | What you do |
|---|---|---|
awaiting_funding | Created; the buyer hasn’t paid yet. | Do nothing. Never fulfil. |
held | Funded; money secured at a licensed partner bank. | Fulfil the order — you’re guaranteed. |
released | Buyer confirmed delivery, or the window lapsed. | Recognise revenue. Payout settles. |
refunded | Returned to the buyer (refund or lost dispute). | Reverse fulfilment if needed. |
disputed | Buyer raised an issue; under resolution. | Respond with evidence in the dashboard. |
expired | Never funded within its window. | Cancel the order. |
The golden rule
Fulfil on held. Recognise revenue on released. Never fulfil on awaiting_funding.
Create a payment
POST https://api.pincode.africa/api/v1/payments — one call per order. Send an Idempotency-Key so a retry can never create a duplicate payment.
| Field | Type | Required | Description |
|---|---|---|---|
customerId | string | Yes | The buyer’s Pincode user id. |
amountMinor | string | Yes | Amount in integer minor units (kobo). A string — never a float. Set it server-side. |
reference | string | Yes | Your order id. You reconcile by joining on this. |
windowHours | number | Yes | Resolution window (hours). Clamped to your merchant maximum. |
escrow | boolean | No | Hold in escrow. Defaults to your policy; escrow-off requires KYB. |
Idempotency-Key | header | Yes | Safe retries: the same key returns the same payment, never a duplicate. |
curl https://api.pincode.africa/api/v1/payments \
-H "Authorization: Bearer sk_live_…" \
-H "Idempotency-Key: order-2026-0001" \
-H "Content-Type: application/json" \
-d '{
"customerId": "usr_ada",
"amountMinor": "4500000", // ₦45,000 in kobo — integer, set server-side
"reference": "order-2026-0001", // your order id; reconcile by joining on this
"windowHours": 72
}'// 201 Created
{
"id": "pay_01HZX9AB…",
"status": "awaiting_funding",
"reference": "order-2026-0001",
"amountMinor": "4500000",
"currency": "NGN",
"escrow": true,
"windowHours": 72,
"checkoutUrl": "https://checkout.pincode.com/pay/8F2A19",
"createdAt": "2026-08-06T12:00:00.000Z"
}Money is always an integer minor-unit string (kobo) — "4500000" is ₦45,000. Never a float, never a client value.
Retrieve payments
Fetch a single payment by id, or list your payments for backfill and reconciliation. Use these for bookkeeping — don’t poll for status changes; let webhooks push them to you.
curl https://api.pincode.africa/api/v1/payments/pay_01HZX9AB… \
-H "Authorization: Bearer sk_live_…"
// → the payment, with its current statusWebhooks
State changes are delivered to your endpoint as signed events. Configure the URL in your dashboard (or PUT https://api.pincode.africa/api/v1/merchant/webhook).
| Event | Fires when | You should |
|---|---|---|
payment.held | Buyer funded; money is secured. | Fulfil the order. |
payment.released | Buyer confirmed, or window lapsed. | Recognise revenue. |
payment.refunded | Money returned to the buyer. | Reverse fulfilment if shipped. |
payment.disputed | Buyer opened a dispute. | Respond in the dashboard. |
payment.expired | Never funded in time. | Cancel the order. |
POST https://yourstore.com/hooks/pincode
Pincode-Signature: t=1723458000,v1=6b8a1f2c…
{
"id": "evt_01HZXB…", // de-dupe on this
"event": "payment.held", // → fulfil the order
"created": "2026-08-06T12:01:03Z",
"data": {
"id": "pay_01HZX9AB…",
"reference": "order-2026-0001",
"status": "held",
"amountMinor": "4500000",
"currency": "NGN"
}
}Three rules keep webhooks safe:
- Verify the signature in constant time and reject anything unsigned or mismatched.
- De-dupe by
id— delivery is at-least-once, so the same event can arrive twice. - Ack fast with a 2xx. Any non-2xx (or a timeout) is retried with backoff.
import crypto from 'node:crypto';
// Verify Pincode-Signature before trusting any webhook.
function verify(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
const expected = crypto
.createHmac('sha256', secret)
.update(`${parts.t}.${rawBody}`)
.digest('hex');
// constant-time compare — never a plain ===
return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
}
app.post('/hooks/pincode', express.raw({ type: '*/*' }), (req, res) => {
const raw = req.body.toString('utf8');
if (!verify(raw, req.headers['pincode-signature'], process.env.PINCODE_WEBHOOK_SECRET)) {
return res.sendStatus(400); // reject unsigned / tampered
}
const evt = JSON.parse(raw);
if (seen(evt.id)) return res.sendStatus(200); // idempotent: de-dupe by event id
if (evt.event === 'payment.held') fulfilOrder(evt.data.reference);
res.sendStatus(200); // ack fast; non-2xx = we retry with backoff
});Going live
Build and test entirely in sandbox against the full lifecycle. To flip to live:
- → Complete KYB verification — required to go live, and to toggle
escrowoff. - → Set your webhook URL, maximum resolution window (caps the buyer’s window), and escrow default.
- → Swap your
sk_test_…key forsk_live_…. Same code, real money.
Reconciliation
Every payment carries your reference. Reconcile by joining on it against your orders. The dashboard segments transactions into pending / resolved / failed with payout reports.
On our side the ledger is append-only and a daily reconciliation compares the partner bank’s balance against open escrow — any drift pages our ops team. Corrections are always explicit reversing entries, never edits.
Errors & idempotency
Errors share one envelope. Quote the requestId to support.
// 4xx / 5xx share one envelope
{
"error": {
"code": "validation_error",
"message": "windowHours exceeds your merchant maximum of 168.",
"requestId": "req_01HZ…" // quote this to support
}
}| Code | HTTP | Meaning |
|---|---|---|
unauthorized | 401 | Missing or invalid API key. |
forbidden | 403 | Key lacks the scope, or KYB not complete for this action. |
validation_error | 422 | A field is missing or out of range (e.g. windowHours over your cap). |
not_found | 404 | No payment with that id under your account. |
rate_limited | 429 | Too many requests — back off and retry. |
internal_error | 500 | Something went wrong on our side. Safe to retry with the same Idempotency-Key. |
Send an Idempotency-Key on writes. Retrying with the same key returns the original result — never a duplicate payment. On a 500, it’s safe to retry with the same key.