Skip to content
iSmartPayDevelopers
Esc
↑↓navigate↵open⌘Jpreview

checkout.payment_failed

Sent when a payment on a hosted checkout fails. payment.failureReason says why. When payment.moneyReceived is true the money reached your wallet but did not pay the checkout: late_payment (a single-use checkout that was already paid), amount_mismatch (a wallet transfer for the wrong amount) or checkout_not_open (a wallet transfer to an expired or cancelled checkout). Refund the customer or contact them; iSmartPay does not refund it for you. Subscribe to it on a webhook endpoint; it is also in GET /v1/events for keys with collections.read. Answer with any 2xx within 10 seconds. Anything else, a timeout or a redirect is retried up to 6 times over about a day.

POSTcheckout.payment_failedWebhook
Header parameters
Webhook-Idstringrequired

The event id. The same event can arrive more than once; use this to ignore repeats.

Webhook-Timestampstringrequired

Unix seconds when this attempt was signed. Reject a delivery older than 5 minutes.

Webhook-Signaturestringrequired

v1, then a comma, then the base64 HMAC-SHA256 of "{Webhook-Id}.{Webhook-Timestamp}.{raw body}" keyed with your endpoint's signing secret. Compare in constant time.

Request body
requiredapplication/json
idstringrequired

The event id, the same as the Webhook-Id header.

typestringrequired
createdAtstring<date-time>required

When the change happened.

dataCheckoutEventDatarequired

The checkout after the change.

Show properties
idstringrequired

The checkout's id.

referencestringrequired

The reference you gave the checkout.

statusstringrequired

The checkout's status after the change.

Allowed:openpaidexpiredcancelled
usagestringrequired
Allowed:singlereusable
metadataobjectrequired

The metadata you set on the checkout, or {}.

paymentCheckoutEventPayment

The payment, on checkout.paid and checkout.payment_failed only.

Show properties
collectionReferencestringrequired

The payment's reference, the same as on the checkout's attempts and, for mobile money, on its collection.

statusstringrequired
Allowed:succeededfailed
amountstringrequired

What the customer paid or tried to pay. A decimal string in major units.

currencystringrequired
providerstringrequired

mtn, telecel, ismartpay for an iSmartPay request, or ismart_wallet for a wallet transfer.

payerstring

The payer's number with all but the last four digits masked, or @handle for an iSmartPay request. Absent for a wallet transfer.

failureReasonstring

Why the payment failed. Present only when status is failed.

moneyReceivedbooleanrequired

Whether the money reached your wallet. true on a failed payment means you hold money that did not pay the checkout and should be refunded.

walletIdstring<uuid>

The wallet the money went into or came out of, when one was named.

Responses
2XX

Received. Any 2xx stops retries.

Payload
{
  "id": "string",
  "type": "checkout.payment_failed",
  "createdAt": "2019-08-24T14:15:22Z",
  "data": {
    "id": "6f1c2a9e-3b4d-4e5f-8a7b-1c2d3e4f5a6b",
    "reference": "order-1042",
    "status": "paid",
    "usage": "single",
    "metadata": {
      "orderId": "1042"
    },
    "payment": {
      "collectionReference": "chk_0a1b2c3d4e5f40718293a4b5c6d7e8f9",
      "status": "succeeded",
      "amount": "25.00",
      "currency": "GHS",
      "provider": "mtn",
      "payer": "********3456",
      "moneyReceived": true
    }
  }
}
Response
Received. Any 2xx stops retries.