PayKunda API (2026-08-06)

PayKunda is API infrastructure for emerging markets. One integration lets you send money to mobile money wallets, bank accounts and cash pickup points, and sell airtime, data bundles and prepaid electricity.

The API is organised around REST. It has predictable resource-oriented URLs, accepts and returns JSON, and uses standard HTTP response codes and verbs.

Base URL

https://api.paykunda.com/v3

Authenticate with your secret API key in the Authorization header:

curl https://api.paykunda.com/v3/balances \
  -H "Authorization: Bearer sk_live_9fL2mQz8Kx7Yw3kQ2"

• sk_test_… keys hit the sandbox — identical behaviour, simulated settlement.
• sk_live_… keys move real money.
• Keys are created and managed in the PayKunda dashboard — not via the API. There you can restrict a key by IP address / CIDR range and by scope (e.g. payouts:write), set an expiry, roll it, or revoke it instantly.
• Keep keys secret. They are shown once at creation and stored hashed.

All amounts are decimal strings in the major units of an ISO-4217 currency — {"amount": "1500.00", "currency": "NGN"} is ₦1,500.00. Amounts are strings (never JSON floats) to avoid floating-point rounding errors; include two decimal places, e.g. "100.00".

Pass an Idempotency-Key header (any unique string, e.g. a UUID) on every POST. Retrying with the same key returns the original response instead of performing the action twice — a network timeout can never double-send money.

curl https://api.paykunda.com/v3/payouts \
  -H "Authorization: Bearer sk_live_…" \
  -H "Idempotency-Key: 0b7c9d4e-1f2a-4b3c-8d5e-6f7a8b9c0d1e" \
  -d '{...}'

PayKunda returns a consistent error envelope. The code is machine-readable and stable; message is for humans; param names the offending field.

{
  "error": {
    "type": "invalid_request_error",
    "code": "amount_below_minimum",
    "message": "Amount must be at least NGN 100.00.",
    "param": "amount",
    "doc_url": "https://docs.paykunda.com/errors#amount_below_minimum",
    "request_id": "req_7Hs92kL"
  }
}

All list endpoints are cursor-paginated:

GET /v3/payouts?limit=25&starting_after=po_9Ks82mQz

Responses have the shape {"object": "list", "data": [...], "has_more": true}.

Register webhook endpoints to receive events (payout.paid, electricity_token.delivered, …). Every delivery is signed:

Webhook-Signature: t=1754901120,v1=5257a869e7…

v1 = HMAC_SHA256(signing_secret, t + "." + raw_body). Reject deliveries where |now - t| > 5 minutes. As a financial best practice, treat webhooks as notifications — confirm by fetching the resource by id.

Your available and pending balances per currency.

Send money to mobile money wallets, bank accounts, or cash pickup points. Creating a payout debits your wallet for the amount plus fee immediately.

A payout moves through a simple lifecycle:

pending → processing → paid — or failed (funds are returned to your wallet; a payout is never left in limbo).

Directory of supported providers, corridors and their limits.

Top up any supported mobile number. Providers are auto-detected from the number.

List and purchase mobile data bundles.

Validate meters and vend prepaid electricity (STS) tokens.

Immutable stream of everything that happened on your account.

Manage webhook endpoints and their signing secrets. Register a URL and the event types you care about; PayKunda then POSTs a signed JSON event to your URL whenever the state of a payout, airtime top-up, data bundle or electricity token changes.

Every delivery includes a Webhook-Signature header:

Webhook-Signature: t=1754901120,v1=5257a869e7c3…

• t — the UNIX timestamp when the event was signed.
• v1 — HMAC_SHA256(signing_secret, t + "." + raw_request_body), hex-encoded.

The signing_secret (whsec_…) is returned once when you create the endpoint. Store it securely — it is never shown again (rotate the endpoint to get a new one).

To verify a delivery on your server:

1. Read the raw request body exactly as received (do not re-serialize it).
2. Parse t and v1 from the Webhook-Signature header.
3. Compute expected = HMAC_SHA256(signing_secret, t + "." + raw_body).
4. Compare expected to v1 using a constant-time comparison.
5. Reject if |now - t| > 5 minutes (replay protection).

// Node.js (Express raw body)
const crypto = require("crypto");
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");
  const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) <= 300;
  return ok && fresh;
}

Return 2xx quickly to acknowledge receipt; PayKunda retries non-2xx deliveries with exponential backoff. As a financial best practice, treat a webhook as a notification and confirm the final state by fetching the resource by id (e.g. GET /payouts/{payout_id}) before acting on it.