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 need the collections.read permission, payout and utility purchase events need disbursements.read, settlement events need settlements.read and transfer events need wallettransfer.read; you only see the types your key holds. Events only arrive once your business has a webhook endpoint, and utility purchase, settlement and transfer 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.

Show properties

Array of

CollectionAcceptedEvent | CollectionStatusChangedEvent | PayoutAcceptedEvent | PayoutStatusChangedEvent | UtilityPurchaseAcceptedEvent | UtilityPurchaseStatusChangedEvent | SettlementStatusChangedEvent | TransferStatusChangedEvent | TransferReceivedEvent

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.

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

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.

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.

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

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.

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.

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.

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

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>

UtilityPurchaseStatusChangedEvent

idstringrequired

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

typestringrequired

createdAtstring<date-time>required

When the change happened.

dataUtilityPurchaserequired

Show properties

referencestringrequired

The reference you chose.

statusstringrequired

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>

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>

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>

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, 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

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); 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

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

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

messagestringrequired

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

Request

curl -X GET 'https://api.example.com/v1/events' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch("https://api.example.com/v1/events", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN"
  }
});

import requests

response = requests.get(
    "https://api.example.com/v1/events",
    headers={
        "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",
        "channel": "api",
        "settlementStatus": "not_eligible",
        "reconciliation": {
          "status": "unchecked",
          "checkedAt": "2019-08-24T14:15:22Z"
        },
        "parent": {
          "type": "collection",
          "reference": "string"
        },
        "compensation": {
          "type": "collection",
          "reference": "string"
        }
      }
    }
  ],
  "nextAfter": "string"
}

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string"
  }
}