Integration guide

Integrating KulPay

One page, everything you need. Every value below is rendered from this gateway's running configuration — the rails, the currencies, the event names — so it describes what this deployment actually does rather than what it did when someone last edited a document.

Quickstart

Three calls. Create a charge, send the customer to the returned URL, handle the webhook.

# 1. Create a hosted-checkout charge
curl -X POST https://gateway.fnb.kulpay.pavulla.com/charges \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Idempotency-Key: order-1001' \
  -d '{
    "payment_id": "order-1001",
    "money":   { "amount": "1250.00", "currency": "MZN" },
    "source":  { "type": "checkout" },
    "country": "MZ",
    "description": "Order #1001",
    "callback_url": "https://your-app.example/webhooks/kulpay"
  }'

# 2. Redirect the customer to checkout_url from the response
{
  "payment_id": "order-1001",
  "provider_payment_id": "3H7f…",
  "status": "created",
  "checkout_url": "https://gateway.fnb.kulpay.pavulla.com/checkout/3H7f…"
}

# 3. Your endpoint receives a signed webhook when it settles
{
  "id": "3H7e…:3H7f…:payment.succeeded",
  "type": "payment.succeeded",
  "created_at": "2026-08-01T09:12:44Z",
  "data": { "id": "3H7f…", "status": "succeeded", "amount": "1250.00", "currency": "MZN" }
}

Authentication

Every API call needs a bearer key:

Authorization: Bearer YOUR_API_KEY

A key carries its own mode and its own scopes. The mode is the important one — see below. Scopes are least-privilege: a key that only creates charges cannot issue refunds, so a leaked publishable-side key has a bounded blast radius.

Idempotency

Send Idempotency-Key on every POST /charges. A repeat with the same key returns the original response instead of creating a second charge — which is what makes a network timeout safe to retry. Use your own order id.

Test and live

One deployment serves both. The key decides — not the URL, not a header. A test key against this same base URL reads and writes test data and cannot touch a live payment, which is how you smoke-test production without moving money.

In live mode the checkout will only offer rails backed by a real connector. A rail you see in test mode may legitimately be absent in live: a simulated rail that cannot collect must not look like one that can.

This gateway is currently in live mode.

Payment rails

What this deployment offers right now. Fetch the same list at runtime from GET /methods rather than hardcoding it — rails get enabled and disabled without a release.

Choosing how to collect

Hosted checkout ("source": {"type":"checkout"}) is the recommended path: the customer picks the rail on our page, which handles OTP, USSD prompts, QR and 3DS for you, in Portuguese, on mobile. You get a checkout_url to redirect to.

Direct — name the rail yourself when you already know it:

# mobile wallet
"source": { "type": "mobile_wallet",
            "mobile_wallet": { "network": "mpesa", "phone_number": "+258840000001" } }

# card — a tokenizer handle, never a raw PAN
"source": { "type": "card", "card": { "token": "tok_…" } }

Creating a charge

POST /charges

Payment status

GET /payments/{provider_payment_id}. Statuses match the event names without the payment. prefix.

Payments expire after 5m0s if the customer never completes them.

Lifecycle

Every status change follows this table. Any other change (a late processing after succeeded, a failed after succeeded) is refused: the payment keeps its status and the refusal is recorded as transaction.transition.rejected. When the refused report and the recorded status disagree about whether money moved, an operator works it as a payment exception. authorized means the funds are held: capture it (succeeded) or cancel it. A succeeded payment also carries settlement_status: unsettled, settled, reconciled.

Each payment also records its processing stages, in order: receive, enrich_validate, risk, route, submit, await_confirmation, post, notify, settle, reconcile. Each has its start, end, outcome, reason, the PSP's code and ours, and emits transaction.stage.<stage>.<outcome>. Read them with GET /v1/transactions/{id}/stages to see where a payment stopped and why.

Webhooks

Set callback_url on the charge, or register an endpoint on the management API. We POST a signed JSON envelope whenever the payment changes state, and retry 3 times with exponential backoff before giving up.

POST /your/endpoint
Content-Type: application/json
X-KulPay-Source: kulpay-payments
KulPay-Signature: t=1785225600,v1=2c1f4c…

{
  "id": "2mZp4T0…",
  "type": "payment.succeeded",
  "schema_version": 1,
  "aggregate_type": "payment",
  "aggregate_id": "2mZp3x…",
  "sequence": 2,
  "created_at": "2026-08-01T09:12:44Z",
  "tenant_id": "…",
  "mode": "live",
  "actor": { "type": "api_key", "id": "…" },
  "correlation_id": "req_…",
  "data": { … }
}

The body is the event envelope; every field is described in the event catalogue. id is the event id: the same on every retry and the same as GET /v1/events/{id}.

Rules that matter

• Respond 2xx quickly. Anything else is a failure and we retry. Do the work asynchronously; acknowledge first.
• Deduplicate on id. It is stable across retries, and at-least-once delivery means you will see the same event twice.
• Delivery order is not guaranteed; sequence is. A retried processing can arrive after succeeded. Compare sequence for the same aggregate_id, and never move a payment backwards out of a terminal state.
• Verify the signature before trusting anything in the body.
• Catch up after an outage with GET /v1/events?since=<last event id> (scope events:read) instead of waiting for retries.

Event reference

The complete set delivered by webhook. There are no others. Every event the gateway records, including ones that are not webhooks, is in the event catalogue with its JSON Schema.

Verifying signatures

KulPay-Signature is t=<unix>,v1=<hex>, possibly with several v1= segments during secret rotation. The signed payload is t + "." + rawBody, HMAC-SHA256 under your endpoint's signing secret.

// Node.js
const crypto = require('crypto');

function verify(rawBody, header, secret, toleranceSeconds = 0s) {
  const parts = Object.fromEntries(
    header.split(',').map(p => p.split('=').map(s => s.trim())));
  const t = Number(parts.t);
  // Reject stale timestamps: without this, a captured delivery can be replayed.
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;

  const expected = crypto.createHmac('sha256', secret)
                         .update(t + '.' + rawBody).digest('hex');
  // Every v1 segment — during rotation more than one is valid.
  return header.split(',')
    .filter(p => p.trim().startsWith('v1='))
    .some(p => crypto.timingSafeEqual(
      Buffer.from(p.trim().slice(3)), Buffer.from(expected)));
}

# Python
import hmac, hashlib, time

def verify(raw_body: bytes, header: str, secret: str, tolerance: int = 0s) -> bool:
    parts = dict(p.strip().split("=", 1) for p in header.split(","))
    t = int(parts.get("t", 0))
    if not t or abs(time.time() - t) > tolerance:
        return False
    expected = hmac.new(secret.encode(),
                        f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(p.strip()[3:], expected)
               for p in header.split(",") if p.strip().startswith("v1="))

Use a constant-time comparison (timingSafeEqual, compare_digest). A plain == leaks the signature one byte at a time to anyone willing to measure.

Debugging a delivery

If your endpoint never acknowledged something, ask the gateway what it sent:

GET /v1/admin/webhooks/deliveries?payment_id=3H7f…
GET /v1/admin/webhooks/deliveries/{id}   # includes the exact signed bytes

Refunds

curl -X POST https://gateway.fnb.kulpay.pavulla.com/refunds \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "payment_id": "3H7f…",
        "money": { "amount": "500.00", "currency": "MZN" },
        "reason": "requested_by_customer" }'

Omit money to refund in full. Partial refunds may be repeated up to the captured amount; the gateway reserves against the remaining balance atomically, so two concurrent refunds cannot over-refund. You get refund.succeeded or refund.failed.

PSPs on KulPay

A PSP or bank applies at /onboarding, is reviewed (KYB), sets up and certifies its integration in the sandbox, runs a pilot and goes live. The partner portal follows the registration and holds the team, the API keys, the webhooks and the usage. Besides payments (above), a PSP can take cash deposits and sell bills.

Cash deposits

A partner bank or agent takes cash for a KulPay account in three calls:

POST https://gateway.fnb.kulpay.pavulla.com/name-lookups            {"method": "cash_deposit", "reference": "INV-1001"}
POST https://gateway.fnb.kulpay.pavulla.com/cash-deposits/intents   {"lookup_id": "…", "amount": "1500.00", "currency": "MZN"}
POST https://gateway.fnb.kulpay.pavulla.com/cash-deposits/intents/{id}/confirm   {"account": "…", "entry_id": "…", "value_date": "2026-10-08"}

The deposit is credited only when the receiving account's statement shows the same entry.

Selling bills and top-ups

Your channel (app, USSD, agents) lists the billers on KulPay and pays their bills, top-ups and tokens from your balance, or by collecting from the payer first. Keys need bills:read and bills:write.

GET  https://gateway.fnb.kulpay.pavulla.com/billers?category=electricity
POST https://gateway.fnb.kulpay.pavulla.com/bill-payments/lookups   {"biller": "EDM", "product": "CREDELEC", "customer_reference": "01123456781"}
POST https://gateway.fnb.kulpay.pavulla.com/bill-payments/quotes    {"biller": "EDM", "product": "CREDELEC", "lookup_id": "…", "amount": "500"}
POST https://gateway.fnb.kulpay.pavulla.com/bill-payments           {"quote_id": "…"}            # Idempotency-Key required

The answer is succeeded (tokens, PINs or receipt in artifacts), failed (nothing charged) or pending: KulPay then asks the supplier, never sends again, and you get bill_payment.succeeded or bill_payment.failed. Your payers can subscribe to billers' invoices (POST /payers/{id}/subscriptions, with their consent) and opt out at any time; new invoices arrive as bill_invoice.delivered and are paid by quoting with invoice_id.

Showing billers and documents. Each biller's logo_url is a transparent PNG hosted by KulPay (/logos/{id}?v=…, public, cacheable for good): draw it on your own colours. A bill's document, when the biller attached one, is at document.url in the payer's invoice list (GET /bill-invoices/{id}/document, for a channel whose payer is subscribed or that paid it). Every payment has a printable receipt, tokens and PINs included: GET /bill-payments/{id}/receipt.pdf.

Tell billers what your payers did. When a payer opens a bill, or pins (saves) it, report it: POST /bill-invoices/{id}/engagements {"type": "opened" | "pinned" | "unpinned", "payer_id": "…", "surface": "app"}. KulPay tells the biller once per payer, naming the payer only by an opaque reference. Every payment also carries participants: you as initiating_psp, the from_psp and the to_psp.

Billers (LSP) on KulPay

A biller (a Lively Service Provider: a utility, an MNO, a TV or internet operator, a school, an insurer) applies at /onboarding?kind=lsp. After the review (KYB) KulPay sets up its products with it and activates it; channels then list it and its customers pay on them. Its portal shows the payments, invoices, enrolled customers and remittances, and creates the API keys, which carry invoices:write and payers:write.

Presenting invoices

By API, one invoice or up to 1,000:

curl -X POST https://gateway.fnb.kulpay.pavulla.com/biller/invoices   -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json'   -d '{"invoices": [{"number": "F-2026-001", "account_reference": "CL-123", "amount": "1500.00",
        "currency": "MZN", "due_date": "2026-10-31"}]}'

Or by file: POST /biller/invoice-files with a CSV (invoice_number, account_reference, amount, currency, issue_date, due_date, description), also from the portal. Presenting a number again updates an unpaid invoice; PATCH /biller/invoices/{number} changes or cancels it. When a payment succeeds you receive bill_invoice.paid. Billers whose system can answer the amount due are looked up instead.

Customers and consent

Payers choose the billers whose invoices they receive, through their channel, and can opt out at any time. You can also enrol your customers, stating the lawful basis on which you share their contacts:

POST https://gateway.fnb.kulpay.pavulla.com/biller/payers  {"lawful_basis": "contract",
  "payers": [{"account_reference": "CL-123", "name": "Ana Nhantumbo", "phone": "+258841234567"}]}

Enrolments are matched to channels' payers by phone or email and subscribe them, except those who opted out of that account. DELETE /biller/payers/{account_reference} removes one.

Remittances

What KulPay collects for you, less the fee you bear, is remitted daily or weekly to your bank account, with a report of every payment: GET /biller/remittances and GET /biller/remittances/{id}/report.csv. You receive bill_remittance.created and bill_remittance.paid.

The biller contract (prepaid and real-time billers)

To sell tokens, top-ups or vouchers, or to be looked up in real time, implement KulPay's biller contract on your side: signed POST /lookup, optional POST /quote, POST /payments idempotent on request_id, GET /payments/{request_id}, and optionally GET /balance, GET /offers and GET /payments?date= for the daily reconciliation. KulPay never sends a new request_id for the same payment: an unanswered request is asked about, not repeated as a new one. The full contract, with every request, answer and test scenario, is in the biller integration guide.

Testing

This gateway is in live mode, so the values below apply to a test-mode key against this same base URL.

Cards

Test mode only. Send the test token as source.card.token (the number is accepted too and becomes that token). A live payment takes the acquirer's token only: any card number is refused with raw_card_data_not_accepted.

Mobile wallet numbers

any

mcel

movitel

vodacom

Forcing an outcome

Send X-Mock-Scenario on the charge to override the fixture:

Errors

Errors are RFC 9457 problem documents (application/problem+json). Branch on code; the detail is for people.

{
  "type":   "about:blank",
  "title":  "Card not accepted",
  "status": 400,
  "code":   "invalid_card",
  "detail": "Card number failed Luhn check."
}

Until the next release an error also carries legacy_code (the code it had before, when it changed) and the old error: {code, message} member. Switch to code.

Every code, what it means and what to do, request errors and payment failure codes alike: errors and codes.

Machine-readable reference: OpenAPI 3.1 spec. This page is generated from the gateway's running configuration.