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.

Base URL · https://api.pincode.africa/api/v1REST · JSON

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.held webhook — fulfil now.
  • 3. They confirm delivery (or the window lapses); you receive payment.released and 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 header
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.

POST /payments
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
  }'
response
// 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:

StateWhat it meansWhat you do
awaiting_fundingCreated; the buyer hasn’t paid yet.Do nothing. Never fulfil.
heldFunded; money secured at a licensed partner bank.Fulfil the order — you’re guaranteed.
releasedBuyer confirmed delivery, or the window lapsed.Recognise revenue. Payout settles.
refundedReturned to the buyer (refund or lost dispute).Reverse fulfilment if needed.
disputedBuyer raised an issue; under resolution.Respond with evidence in the dashboard.
expiredNever 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.

FieldTypeRequiredDescription
customerIdstringYesThe buyer’s Pincode user id.
amountMinorstringYesAmount in integer minor units (kobo). A string — never a float. Set it server-side.
referencestringYesYour order id. You reconcile by joining on this.
windowHoursnumberYesResolution window (hours). Clamped to your merchant maximum.
escrowbooleanNoHold in escrow. Defaults to your policy; escrow-off requires KYB.
Idempotency-KeyheaderYesSafe retries: the same key returns the same payment, never a duplicate.
request
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
// 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.

GET /payments/:id
curl https://api.pincode.africa/api/v1/payments/pay_01HZX9AB… \
  -H "Authorization: Bearer sk_live_…"

// → the payment, with its current status

Webhooks

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

EventFires whenYou should
payment.heldBuyer funded; money is secured.Fulfil the order.
payment.releasedBuyer confirmed, or window lapsed.Recognise revenue.
payment.refundedMoney returned to the buyer.Reverse fulfilment if shipped.
payment.disputedBuyer opened a dispute.Respond in the dashboard.
payment.expiredNever funded in time.Cancel the order.
event payload
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.
verify + handle (Node)
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 escrow off.
  • → Set your webhook URL, maximum resolution window (caps the buyer’s window), and escrow default.
  • → Swap your sk_test_… key for sk_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.

error shape
// 4xx / 5xx share one envelope
{
  "error": {
    "code":      "validation_error",
    "message":   "windowHours exceeds your merchant maximum of 168.",
    "requestId": "req_01HZ…"          // quote this to support
  }
}
CodeHTTPMeaning
unauthorized401Missing or invalid API key.
forbidden403Key lacks the scope, or KYB not complete for this action.
validation_error422A field is missing or out of range (e.g. windowHours over your cap).
not_found404No payment with that id under your account.
rate_limited429Too many requests — back off and retry.
internal_error500Something 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.