Status reference

Every webhook JKAPay delivers carries the transaction's final state in data.status. Branch on this field — there is no separate event field. The table below lists every status a transaction can hold and whether it triggers a webhook delivery.

Status	Final	Triggers webhook	Meaning
PENDING	No	No	The transaction has been created in JKAPay but the customer prompt has not been dispatched yet. Internal state — no webhook is fired.
PROCESSING	No	No	The customer prompt has been dispatched and we're awaiting their response. Returned from /v1/payments/initialize. No webhook is fired.
SUCCESS	Yes	Yes	The customer authorised the payment and money has moved. A webhook is fired to your callbackUrl.
FAILED	Yes	Yes	The transaction will not complete — the customer declined, the prompt timed out, there were insufficient funds, or the network rejected. A webhook is fired to your callbackUrl.

Only final states fire webhooks. PENDING and PROCESSING exist for your own polling against retrieve, not for delivery.

Sample: SUCCESS

JSON

{
  "createdAt": "2026-05-25T16:30:18.213Z",
  "data": {
    "reference": "JKA_M3A8_8F2E1B4C",
    "clientReference": "ORD-12345",
    "status": "SUCCESS",
    "amount": "1.00",
    "fee": "0.02",
    "net": "0.98",
    "currency": "GHS",
    "customer": { "msisdn": "233244000000", "network": "MTN" },
    "description": "Order #12345",
    "metadata": { "orderId": "12345" },
    "completedAt": "2026-05-25T16:30:18.213Z"
  }
}

Sample: FAILED

JSON

{
  "createdAt": "2026-05-25T16:31:02.012Z",
  "data": {
    "reference": "JKA_M3A9_7C1A2D5E",
    "clientReference": "ORD-12346",
    "status": "FAILED",
    "amount": "1.00",
    "fee": "0.00",
    "net": "0.00",
    "currency": "GHS",
    "customer": { "msisdn": "233244000000", "network": "MTN" },
    "description": "Order #12346",
    "metadata": { "orderId": "12346" },
    "completedAt": "2026-05-25T16:31:02.012Z"
  }
}

Future statuses

JKAPay will introduce REFUNDED and CANCELLED when those flows ship. They'll arrive on the same webhook channel with the same envelope — your branching on data.status will continue to work without changes.