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

subscription.charge_failed

Sent when a charge attempt fails. nextAttemptAt says when it will be tried again, or is null when this cycle has no more attempts and its status is uncollectible. Needs mandates.read to appear in the events list. Answer with any 2xx within 10 seconds. Anything else, a timeout or a redirect is retried up to 6 times over about a day. Events can arrive out of order, so compare statuses and cycles rather than trusting arrival order.

POSTsubscription.charge_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.

dataSubscriptionChargeEventDatarequired

The charge attempt that failed.

Show properties
idstringrequired
matches ^rch_[0-9a-f]{32}_[0-9]+_[0-9]+$
subscriptionIdstringrequired
matches ^sub_[0-9a-f]{32}$
subscriptionReferencestringrequired
cycleintegerrequired
dueAtstring<date-time>required
amountstringrequired

What the customer is charged, fee included. A decimal string in major units.

currencystringrequired
attemptintegerrequired
statusstringrequired
Allowed:paidfaileduncollectible
failureReasonstring
nextAttemptAtstring<date-time> | nullrequired

When a failed attempt will be tried again. Null when there is no further attempt this cycle.

Responses
2XX

Received. Any 2xx stops retries.

Payload
{
  "id": "string",
  "type": "subscription.charge_failed",
  "createdAt": "2019-08-24T14:15:22Z",
  "data": {
    "id": "string",
    "subscriptionId": "string",
    "subscriptionReference": "string",
    "cycle": 0,
    "dueAt": "2019-08-24T14:15:22Z",
    "amount": "152.25",
    "currency": "GHS",
    "attempt": 0,
    "status": "paid",
    "failureReason": "string",
    "nextAttemptAt": "2019-08-24T14:15:22Z"
  }
}
Response
Received. Any 2xx stops retries.