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://pay.gateway.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://pay.gateway.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.

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 5 times with exponential backoff before giving up.

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

{
  "id": "<endpoint>:<payment>:<event>",
  "type": "payment.succeeded",
  "created_at": "2026-08-01T09:12:44Z",
  "data": { … }
}

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.
• Order is not guaranteed. A retried processing can arrive after succeeded. Never move a payment backwards out of a terminal state.
• Verify the signature before trusting anything in the body.

Event reference

The complete set. There are no others.

Verifying signatures

X-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://pay.gateway.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.

Testing

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

Cards

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 7807 problem documents:

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

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