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

Catch up on events you missed

Returns the events sent to your webhooks, in the order we received them, each exactly as it was delivered. An event that arrived late comes after the ones before it, even if its createdAt is earlier, so after never skips it. Events show up here a few seconds after they arrive. Pass the id of the last event you processed as after to get everything since; leave it out to start from the first event. Keep calling with nextAfter until it is absent, then resume later from the id of the last item. Collection events and payment request events need the collections.read permission, payout and utility purchase events need disbursements.read, settlement events need settlements.read, transfer events need wallettransfer.read hold events need holds.read, wallet freeze events need wallets.read and subscription events need mandates.read; you only see the types your key holds. Events only arrive once your business has a webhook endpoint, and utility purchase, settlement, transfer hold, wallet freeze and subscription events start after an endpoint is created or edited in the console. Events are kept for 90 days. An after older than that is refused with 400; start again without it.

GET/v1/events
Authorization
AuthorizationBearer token (JWT) · headerrequired

A token from POST /v1/oauth/token on the iSmartPay identity service, obtained with an API credential's client id and secret.

Query parameters
afterstring

The id of the last event you processed. An id that is not one of your events, or one older than 90 days, is refused.

max length 128
limitinteger

How many events to return, 1 to 200. Defaults to 50.

min 1 · max 200 · default: 50
Responses
200

A page of events.

itemsCollectionAcceptedEvent | CollectionStatusChangedEvent | PayoutAcceptedEvent | PayoutStatusChangedEvent | UtilityPurchaseAcceptedEvent | UtilityPurchaseStatusChangedEvent | SettlementStatusChangedEvent | TransferStatusChangedEvent | TransferReceivedEvent | PaymentRequestReceivedEvent | CheckoutPaidEvent | CheckoutPaymentFailedEvent | CheckoutExpiredEvent | CheckoutCancelledEvent | HoldStatusChangedEvent | WalletFrozenEvent | WalletUnfrozenEvent | SubscriptionCreatedEvent | SubscriptionStatusChangedEvent | SubscriptionChargeUpcomingEvent | SubscriptionChargeSucceededEvent | SubscriptionChargeFailedEvent[]required
Show properties
Array of CollectionAcceptedEvent | CollectionStatusChangedEvent | PayoutAcceptedEvent | PayoutStatusChangedEvent | UtilityPurchaseAcceptedEvent | UtilityPurchaseStatusChangedEvent | SettlementStatusChangedEvent | TransferStatusChangedEvent | TransferReceivedEvent | PaymentRequestReceivedEvent | CheckoutPaidEvent | CheckoutPaymentFailedEvent | CheckoutExpiredEvent | CheckoutCancelledEvent | HoldStatusChangedEvent | WalletFrozenEvent | WalletUnfrozenEvent | SubscriptionCreatedEvent | SubscriptionStatusChangedEvent | SubscriptionChargeUpcomingEvent | SubscriptionChargeSucceededEvent | SubscriptionChargeFailedEvent
One of:
CollectionAcceptedEvent
idstringrequired

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

typestringrequired
createdAtstring<date-time>required

When the change happened.

dataCollectionrequired

The collection as it stood when the event was sent. Fields the event did not carry are left out, so fetch the collection by reference when you need the full record.

Show properties
referencestringrequired

The reference you chose.

amountstring

The requested amount. A decimal string in major units.

currencystring

Three-letter currency code.

matches ^[A-Z]{3}$
statusstringrequired

Where the request stands, reported as it is: accepted, dispatched, in_review, held, settled, failed or expired. Others can appear, so do not treat this list as closed. A payment request ends failed when the payer declines or you cancel it, and expired when nobody answers in time.

providerstring

The provider used.

feestring

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

feeBearerstring

Who pays the fee. initiator: the party who starts the request pays the amount plus the fee, and the recipient gets the full amount. non_initiator: the fee comes out of what the recipient gets.

Allowed:initiatornon_initiator
payerAmountstring

What the payer is charged. Left out when the fee bearer is not known. A decimal string in major units.

recipientAmountstring

What the recipient receives. Left out when the fee bearer is not known. A decimal string in major units.

notestring

The note you sent.

failureReasonstring

Why it failed. For a payment request: declined, cancelled or expired. For other providers, the provider's own reason when there is one. Left out otherwise.

createdAtstring<date-time>
completedAtstring<date-time>

When it reached its final status. Left out while it is still moving, and on older movements where the time was not recorded.

expiresAtstring<date-time>

Payment requests only. When an open request ends expired. Left out on other collections.

channelstring

How it was started. api is the only value today.

Allowed:api
settlementStatusstring

Where the money stands with settlement: not_eligible, eligible, claimed or settled.

Allowed:not_eligibleeligibleclaimedsettled
reconciliationReconciliation

What the platform's check against the provider concluded.

Show properties
statusstringrequired

unchecked (not checked yet), matched (the provider agrees) or mismatched (the provider disagrees; the platform is looking into it).

Allowed:uncheckedmatchedmismatched
checkedAtstring<date-time>

When it was last checked. Left out until it has been.

parentLineageLink

The movement this one undoes, when it is a reversal. Left out otherwise.

Show properties
typestringrequired

What kind of movement it is.

Allowed:collectionpayoutwallet_transfer
referencestringrequired

Its reference.

compensationLineageLink

The reversal recorded against this movement. Left out when there is none.

walletIdstring<uuid>

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

CollectionStatusChangedEvent
idstringrequired

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

typestringrequired
createdAtstring<date-time>required

When the change happened.

dataCollectionrequired

The collection as it stood when the event was sent. Fields the event did not carry are left out, so fetch the collection by reference when you need the full record.

Show properties
referencestringrequired

The reference you chose.

amountstring

The requested amount. A decimal string in major units.

currencystring

Three-letter currency code.

matches ^[A-Z]{3}$
statusstringrequired

Where the request stands, reported as it is: accepted, dispatched, in_review, held, settled, failed or expired. Others can appear, so do not treat this list as closed. A payment request ends failed when the payer declines or you cancel it, and expired when nobody answers in time.

providerstring

The provider used.

feestring

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

feeBearerstring

Who pays the fee. initiator: the party who starts the request pays the amount plus the fee, and the recipient gets the full amount. non_initiator: the fee comes out of what the recipient gets.

Allowed:initiatornon_initiator
payerAmountstring

What the payer is charged. Left out when the fee bearer is not known. A decimal string in major units.

recipientAmountstring

What the recipient receives. Left out when the fee bearer is not known. A decimal string in major units.

notestring

The note you sent.

failureReasonstring

Why it failed. For a payment request: declined, cancelled or expired. For other providers, the provider's own reason when there is one. Left out otherwise.

createdAtstring<date-time>
completedAtstring<date-time>

When it reached its final status. Left out while it is still moving, and on older movements where the time was not recorded.

expiresAtstring<date-time>

Payment requests only. When an open request ends expired. Left out on other collections.

channelstring

How it was started. api is the only value today.

Allowed:api
settlementStatusstring

Where the money stands with settlement: not_eligible, eligible, claimed or settled.

Allowed:not_eligibleeligibleclaimedsettled
reconciliationReconciliation

What the platform's check against the provider concluded.

parentLineageLink

The movement this one undoes, when it is a reversal. Left out otherwise.

compensationLineageLink

The reversal recorded against this movement. Left out when there is none.

walletIdstring<uuid>

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

PayoutAcceptedEvent
idstringrequired

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

typestringrequired
createdAtstring<date-time>required

When the change happened.

dataPayoutrequired

The payout as it stood when the event was sent. Fields the event did not carry are left out, so fetch the payout by reference when you need the full record.

Show properties
referencestringrequired

The reference you chose.

amountstring

The requested amount. A decimal string in major units.

currencystring

Three-letter currency code.

matches ^[A-Z]{3}$
statusstringrequired

Where the request stands, reported as it is: accepted, dispatching, in_review, held, delivered, failed or refunded. Others can appear, so do not treat this list as closed.

providerstring

The provider used.

feestring

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

feeBearerstring

Who pays the fee. initiator: the party who starts the request pays the amount plus the fee, and the recipient gets the full amount. non_initiator: the fee comes out of what the recipient gets.

Allowed:initiatornon_initiator
payerAmountstring

What the payer is charged. Left out when the fee bearer is not known. A decimal string in major units.

recipientAmountstring

What the recipient receives. Left out when the fee bearer is not known. A decimal string in major units.

notestring

The note you sent.

failureReasonstring

The provider's own reason when the request failed. Left out otherwise.

createdAtstring<date-time>
completedAtstring<date-time>

When it reached its final status. Left out while it is still moving, and on older movements where the time was not recorded.

channelstring

How it was started. api is the only value today.

Allowed:api
reconciliationReconciliation

What the platform's check against the provider concluded.

parentLineageLink

The movement this one undoes, when it is a reversal. Left out otherwise.

compensationLineageLink

The reversal recorded against this movement. Left out when there is none.

walletIdstring<uuid>

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

PayoutStatusChangedEvent
idstringrequired

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

typestringrequired
createdAtstring<date-time>required

When the change happened.

dataPayoutrequired

The payout as it stood when the event was sent. Fields the event did not carry are left out, so fetch the payout by reference when you need the full record.

Show properties
referencestringrequired

The reference you chose.

amountstring

The requested amount. A decimal string in major units.

currencystring

Three-letter currency code.

matches ^[A-Z]{3}$
statusstringrequired

Where the request stands, reported as it is: accepted, dispatching, in_review, held, delivered, failed or refunded. Others can appear, so do not treat this list as closed.

providerstring

The provider used.

feestring

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

feeBearerstring

Who pays the fee. initiator: the party who starts the request pays the amount plus the fee, and the recipient gets the full amount. non_initiator: the fee comes out of what the recipient gets.

Allowed:initiatornon_initiator
payerAmountstring

What the payer is charged. Left out when the fee bearer is not known. A decimal string in major units.

recipientAmountstring

What the recipient receives. Left out when the fee bearer is not known. A decimal string in major units.

notestring

The note you sent.

failureReasonstring

The provider's own reason when the request failed. Left out otherwise.

createdAtstring<date-time>
completedAtstring<date-time>

When it reached its final status. Left out while it is still moving, and on older movements where the time was not recorded.

channelstring

How it was started. api is the only value today.

Allowed:api
reconciliationReconciliation

What the platform's check against the provider concluded.

parentLineageLink

The movement this one undoes, when it is a reversal. Left out otherwise.

compensationLineageLink

The reversal recorded against this movement. Left out when there is none.

walletIdstring<uuid>

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

UtilityPurchaseAcceptedEvent
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
accountNumberstring
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>
walletIdstring<uuid>

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

UtilityPurchaseStatusChangedEvent
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
accountNumberstring
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>
walletIdstring<uuid>

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

SettlementStatusChangedEvent
idstringrequired

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

typestringrequired
createdAtstring<date-time>required

When the change happened.

dataSettlementRunEventDatarequired

A settlement run as carried by its event. The event has no run id; list runs with GET /v1/settlements and match on reference when you need it.

Show properties
referencestringrequired
statusstringrequired

running or completed. Others can appear, so do not treat this list as closed.

outcomestring

Set once completed: settled, failed_partial or failed_all. Others can appear.

itemCountintegerrequired

How many payments the run made.

totalstringrequired

The amount settled. A decimal string in major units.

currencystringrequired
startedAtstring<date-time>required
completedAtstring<date-time>
TransferStatusChangedEvent
idstringrequired

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

typestringrequired
createdAtstring<date-time>required

When the change happened.

dataTransferrequired

The transfer as it stood when the event was sent. The recipient's handle and name are not carried; fetch the transfer by reference when you need them.

Show properties
referencestringrequired
amountstringrequired

A decimal string in major units.

currencystringrequired
statusstringrequired

Where the transfer stands: pending, held, completed, declined or failed. Others can appear, so do not treat this list as closed.

recipientHandlestring

Returned when you send.

recipientNamestring

The handle's display name, else the recipient's trading name, else registered name, when known.

failureReasonstring

Why a declined or failed transfer did not go through. Left out otherwise.

createdAtstring<date-time>
walletIdstring<uuid>

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

TransferReceivedEvent
idstringrequired

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

typestringrequired
createdAtstring<date-time>required

When the change happened.

dataTransferReceivedrequired

The transfer that reached your wallet.

Show properties
referencestringrequired

The reference the sending business chose.

amountstringrequired

What reached your wallet. A decimal string in major units.

currencystringrequired
senderNamestring

The sending business's trading name, else registered name, when known.

completedAtstring<date-time>
walletIdstring<uuid>

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

PaymentRequestReceivedEvent
idstringrequired

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

typestringrequired
createdAtstring<date-time>required

When the change happened.

dataPaymentRequestReceivedrequired

The request that was sent to you.

Show properties
requestIdstringrequired

iSmartPay's id for the request.

referencestringrequired

The reference the requester chose.

requesterNamestringrequired

Who is asking: a person's full name, or for a business its display name, which is its @handle when it set none.

requesterKindstringrequired

Whether the requester is a customer or a business.

Allowed:consumerbusiness
amountstringrequired

What is being asked for. A decimal string in major units.

currencystringrequired
notestring

The requester's note, when they sent one.

expiresAtstring<date-time>required

When the request expires if nobody answers.

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

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

walletIdstring<uuid>

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

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

walletIdstring<uuid>

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

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

walletIdstring<uuid>

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

HoldStatusChangedEvent
idstringrequired

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

typestringrequired
createdAtstring<date-time>required

When the change happened.

dataHoldrequired

The hold as it stood when the event was sent, as the receiving business sees it. The placing business's copy has no id, decidedAt or createdAt, and the beneficiary's has no createdAt; read the hold for them.

Show properties
idstring<uuid>

The hold's id. A beneficiary business reads and returns the hold with it.

referencestringrequired

The placing business's reference.

statusstringrequired

held until someone decides. paying_out while a payout to an external beneficiary is on the rail; if it fails, the hold is held again. paid_out and returned are final.

Allowed:heldpaying_outpaid_outreturned
amountstringrequired

A decimal string in major units.

currencystringrequired
feestring

On an external hold, the payout fee in major units, priced when the hold is placed. The beneficiary still receives the full amount.

totalHeldstring

On an external hold, amount plus fee: what left your wallet, and what a return gives back.

reasonstring
walletIdstring<uuid>

For the placing business, the wallet the money is held from. For the beneficiary, the wallet it would land in.

beneficiaryHoldParty

Shown to the placing business. A business beneficiary carries businessName, never an id.

Show properties
typestring
Allowed:sub_accountbusinessexternal
walletIdstring<uuid>
businessNamestring

The business's display name, when known.

providerstring

On an external beneficiary.

destinationobject

On an external beneficiary.

Show properties
typestringrequired
Allowed:msisdnaccount
valuestringrequired

The mobile money number or bank account number.

accountNamestring

On an external beneficiary, the account name the provider returned when the hold was placed. Absent where the rail cannot look names up, as with banks.

payoutobject

On an external hold once a pay-out has been asked for: the latest payout attempt.

Show properties
attemptinteger
min 1
statusstring
failureReasonstring
placedByHoldParty

Shown to the beneficiary business instead of beneficiary.

expiresAtstring<date-time>
onExpirystring
Allowed:returnpay_out
decidedBystring

Who decided a final hold. ismartpay is a decision by iSmartPay support.

Allowed:payerbeneficiaryexpiryismartpay
decidedAtstring<date-time>
createdAtstring<date-time>
WalletFrozenEvent
idstringrequired

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

typestringrequired
createdAtstring<date-time>required

When the change happened.

dataWalletFreezerequired

The wallet that was frozen.

Show properties
walletIdstring<uuid>required

The wallet's id.

typestringrequired

The wallet's type, as on a sub-account.

Allowed:primarysub_accountoperationalpersonal
labelstringrequired
referencestring

The reference you gave the wallet. Left out for wallets made without one.

statusstringrequired

The wallet's status after the change. After wallet.unfrozen it is frozen while another freeze is still in place.

Allowed:activefrozen
frozenBystringrequired

Who froze the wallet, or who lifted the freeze for wallet.unfrozen: your business, or iSmartPay. iSmartPay's reason is never sent.

Allowed:ownerstaff
WalletUnfrozenEvent
idstringrequired

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

typestringrequired
createdAtstring<date-time>required

When the change happened.

dataWalletFreezerequired

The wallet that was unfrozen.

Show properties
walletIdstring<uuid>required

The wallet's id.

typestringrequired

The wallet's type, as on a sub-account.

Allowed:primarysub_accountoperationalpersonal
labelstringrequired
referencestring

The reference you gave the wallet. Left out for wallets made without one.

statusstringrequired

The wallet's status after the change. After wallet.unfrozen it is frozen while another freeze is still in place.

Allowed:activefrozen
frozenBystringrequired

Who froze the wallet, or who lifted the freeze for wallet.unfrozen: your business, or iSmartPay. iSmartPay's reason is never sent.

Allowed:ownerstaff
SubscriptionCreatedEvent
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
SubscriptionStatusChangedEvent
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
SubscriptionChargeUpcomingEvent
idstringrequired

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

typestringrequired
createdAtstring<date-time>required

When the change happened.

dataSubscriptionChargeUpcomingDatarequired

The charge that is coming up.

Show properties
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
SubscriptionChargeSucceededEvent
idstringrequired

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

typestringrequired
createdAtstring<date-time>required

When the change happened.

dataSubscriptionChargeEventDatarequired

The charge that was paid.

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.

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

nextAfterstring

Pass as after to get the next page. Absent on the last page.

400

The request is not valid. message says which field.

errorobjectrequired
Show properties
codestringrequired

A stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

401

The token is missing, expired or not valid. Get a new one from the token endpoint.

errorobjectrequired
Show properties
codestringrequired

A stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

403

The request was understood and refused. Common causes: the token is not an API credential's (forbidden); the credential is for the other environment (environment_mismatch); it does not have the permission this operation needs (forbidden); a limit was reached (limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit); or iSmartPay has suspended or deactivated the business (business_suspended, business_deactivated). A suspended business's API credentials stop exchanging for tokens, so a request made with a token issued just before the suspension is refused with business_suspended.

errorobjectrequired
Show properties
codestringrequired

A stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

429

Too many requests for this credential. Wait the number of seconds in the Retry-After header, then try again.

errorobjectrequired
Show properties
codestringrequired

A stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

500

Something failed on our side. The message is fixed. If the request was a POST, retry with the same Idempotency-Key and body.

errorobjectrequired
Show properties
codestringrequired

A stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

Request
curl -X GET 'https://stgdeveloper-api.ismartghana.com/v1/events' \
  -H 'Authorization: Bearer YOUR_TOKEN'
Response
{
  "items": [
    {
      "id": "string",
      "type": "collection.accepted",
      "createdAt": "2019-08-24T14:15:22Z",
      "data": {
        "reference": "string",
        "amount": "120.00",
        "currency": "GHS",
        "status": "string",
        "provider": "string",
        "fee": "120.00",
        "feeBearer": "initiator",
        "payerAmount": "120.00",
        "recipientAmount": "120.00",
        "note": "string",
        "failureReason": "string",
        "createdAt": "2019-08-24T14:15:22Z",
        "completedAt": "2019-08-24T14:15:22Z",
        "expiresAt": "2019-08-24T14:15:22Z",
        "channel": "api",
        "settlementStatus": "not_eligible",
        "reconciliation": {
          "status": "unchecked",
          "checkedAt": "2019-08-24T14:15:22Z"
        },
        "parent": {
          "type": "collection",
          "reference": "string"
        },
        "compensation": {
          "type": "collection",
          "reference": "string"
        },
        "walletId": "0ecad4a2-3549-43fb-807e-9ff033247480"
      }
    }
  ],
  "nextAfter": "string"
}