Skip to main content

Mobile money collection webhook

This event notifies you about the status of a collection (funding) transaction. Collections follow a lifecycle with different states: collection.initiated, collection.processing, collection.completed, and collection.failed.
  • Initiated: The request has been successfully sent to the provider.
  • Processing: The customer has been notified and we are awaiting authorization.
  • Completed: The funds have been successfully collected and added to the wallet.
  • Failed: The collection could not be completed.

Sample Payloads

```json collection.initiated
{
  "event": "collection.initiated",
  "data": {
    "id": "5ded2ca9-888a-4ae2-b1e6-15f6252750f5",
    "referenceNumber": "RAN3SO3TUFMJA",
    "amount": "100.00",
    "type": "FUNDING",
    "state": "INITIATED",
    "paymentMethod": "MOBILE_MONEY",
    "destination": "RW wallet",
    "source": {
      "bankName": null,
      "accountName": null,
      "accountNumber": "+250123456789",
      "provider": "MTN_MOMO_RWA"
    },
    "created": "2026-02-13T12:46:56.834795305Z",
    "processed": "2026-02-13T12:46:56.834795305Z"
  }
}
```
<!-- slide -->
```json collection.completed
{
  "event": "collection.completed",
  "data": {
    "id": "0e32ab5b-3324-45ef-b851-d5abfdf4a9c8",
    "referenceNumber": "IGTXZMCVYQJUA",
    "amount": "50.00",
    "settlementAmount": "36.00",
    "type": "FUNDING",
    "state": "COMPLETED",
    "paymentMethod": "MOBILE_MONEY",
    "destination": "RW wallet",
    "source": {
      "bankName": "MTN_MOMO_RWA",
      "accountName": "MTN_MOMO_RWA",
      "accountNumber": "250123456789",
      "provider": "MTN_MOMO_RWA"
    },
    "fee": {
      "vat": "2.00",
      "stampDuty": "2.00",
      "base": "10.00"
    },
    "created": "2026-02-13T12:46:31.789506Z",
    "processed": "2026-02-13T12:46:31.789506Z"
  }
}
```

Payload Breakdown

FieldTypeDescription
eventstringThe name of the event that occurred (e.g., “collection.completed”).
data.idstringUnique identifier for the transaction.
data.referenceNumberstringUnique reference number assigned to the transaction.
data.amountstringThe total gross amount of the transaction.
data.paymentMethodstringThe method used for payment (e.g., MOBILE_MONEY).
data.settlementAmountstringThe final amount settled after deducting all fees.
data.typestringThe type of transaction (e.g., “FUNDING”).
data.statestringThe final state of the transaction (e.g., “COMPLETED”).
data.destinationstringThe destination of the funds (e.g., “RW wallet”).
data.source.providerstringThe mobile money operator (e.g., “MTN_MOMO_RWA”).
data.source.accountNumberstringThe customer phone number or account identifier.
data.fee.vatstringThe Value Added Tax portion of the fee.
data.fee.stampDutystringThe stamp duty portion of the fee.
data.fee.basestringThe base fee for the transaction.
data.createdstringISO 8601 timestamp of when the transaction was created.
data.processedstringISO 8601 timestamp of when the transaction was processed.