utility_purchase.status_changed

Sent when an airtime or data purchase moves to a new status, such as delivered, failed or refunded. 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 rather than trusting arrival order.

POSTutility_purchase.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.

dataUtilityPurchaserequired

The purchase as it stood when the event was sent. The beneficiary's number and the payer are not carried, and other fields the event did not carry are left out, so fetch the purchase by reference when you need the full record.

Show properties

referencestringrequired

The reference you chose.

statusstringrequired

Where the purchase stands, reported as it is: accepted, awaiting_payment, vending, delivered, failed, refunding, refunded, refund_failed or outcome_unknown. delivered, failed and refunded are final. outcome_unknown and refund_failed are resolved by iSmartPay: do not buy again with a new reference.

productobject

Show properties

idstring

categorystring

networkstring

namestring

beneficiaryobject

Show properties

msisdnstring

amountstring

The amount bought. A decimal string in major units.

currencystring

Three-letter currency code. Only GHS is sold.

matches ^[A-Z]{3}$

feestring

The fee charged. Left out when none was recorded. A decimal string in major units.

grossstring

The amount plus the fee. Left out when no fee was recorded. A decimal string in major units.

fundingobject

Show properties

typestring

Allowed:walletcollection

payerobject

Show properties

providerstring

msisdnstring

failureReasonstring

Why the purchase failed, for example vend_failed or insufficient_balance. Left out otherwise.

createdAtstring<date-time>

Responses

2XX

Received. Any 2xx stops retries.

Payload

{
  "id": "string",
  "type": "utility_purchase.status_changed",
  "createdAt": "2019-08-24T14:15:22Z",
  "data": {
    "reference": "string",
    "status": "string",
    "product": {
      "id": "string",
      "category": "string",
      "network": "string",
      "name": "string"
    },
    "beneficiary": {
      "msisdn": "string"
    },
    "amount": "10.00",
    "currency": "GHS",
    "fee": "10.00",
    "gross": "10.00",
    "funding": {
      "type": "wallet",
      "payer": {
        "provider": "string",
        "msisdn": "string"
      }
    },
    "failureReason": "string",
    "createdAt": "2019-08-24T14:15:22Z"
  }
}

Response

Received. Any 2xx stops retries.