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

subscription.status_changed

Sent whenever a subscription changes status: the customer agrees and it becomes active or trialing, they decline or never answer, you or iSmartPay pause or cancel it, a cycle goes past due, or it completes. It is also sent, with the status unchanged, when you set a subscription to end at its period end; cancelAtPeriodEnd is then true. A past_due event is sent for a subscription with pastDueBehavior keep_charging too; read the subscription to see it as unpaid. 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.status_changedWebhook
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.

dataSubscriptionEventDatarequired

A subscription as it stood when the event happened. It carries the fields that changed with it; read the subscription for the rest, such as fee and totalAmount.

Show properties
idstringrequired
matches ^sub_[0-9a-f]{32}$
referencestringrequired
statusstringrequired
Allowed:incompleteincomplete_expiredtrialingactivepast_duepausedcanceledcompleted
previousStatusstring

Absent on subscription.created.

Allowed:incompleteincomplete_expiredactivepast_duepausedcanceledcompleted
paymentMethodstringrequired
Allowed:mobile_moneywallet
customerobjectrequired
Show properties
networkstring
Allowed:mtntelecel
amountstringrequired

A decimal string in major units, before the fee.

currencystringrequired
nextChargeAtstring<date-time> | nullrequired
cyclesChargedintegerrequired
cancelAtPeriodEndbooleanrequired
cancelAtstring<date-time>
cancelReasonstring
Allowed:businessnetworkplatform
declineReasonstring
Allowed:declinedno_response
pausedBystring
Allowed:businessplatform
Responses
2XX

Received. Any 2xx stops retries.

Payload
{
  "id": "string",
  "type": "subscription.status_changed",
  "createdAt": "2019-08-24T14:15:22Z",
  "data": {
    "id": "string",
    "reference": "string",
    "status": "incomplete",
    "previousStatus": "incomplete",
    "paymentMethod": "mobile_money",
    "customer": {
      "network": "mtn"
    },
    "amount": "150.00",
    "currency": "GHS",
    "nextChargeAt": "2019-08-24T14:15:22Z",
    "cyclesCharged": 0,
    "cancelAtPeriodEnd": true,
    "cancelAt": "2019-08-24T14:15:22Z",
    "cancelReason": "business",
    "declineReason": "declined",
    "pausedBy": "business"
  }
}
Response
Received. Any 2xx stops retries.