Release Date: [12/03/2025]
Overview
This release introduces significant updates and improvements to the API, enhancing transaction processing, standardizing data formats, and expanding support for payouts and pay-ins across multiple currencies.
Breaking Changes
The API has been upgraded to Version 4 (V4) to improve stability, security, and performance. This version includes some changes that should be considered when migrating from the previous version.
Standardized Amount Handling
- Updated both collection and disbursement APIs to use absolute amounts.
Previously: Payout amounts were multiplied by 100.
Sample V3 API Payout Request for 50 XOF:
{
"client_id": "client_id",
"params": {
"amount": "5000",
"city": "CustomerCity",
"client_callback_url": "https://webhook.site/url",
"country_id": "2",
"currency": "XOF",
"email": "john.doe@example.com",
"first_name": "John",
"last_name": "Doe",
"line1": "CustomerStreet",
"mobile": "22991600649",
"mtn": [
{
"phone_number": "22991600649"
}
],
"payment_method_type": "mtn",
"payment_reference": "",
"postal_code": "192.0.0.1",
"third_party_reference_1": ""
},
"salt": "mySalt123",
"sender": "Integration name",
"timestamp": "Timestamp value",
"signature":"XxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxX"
}
Now: All amounts are passed in their absolute form to maintain consistency across all transactions.
Sample V4 API Payout Request for 50 XOF:
{
"client_id": "client_id",
"params": {
"amount": "50",
"city": "CustomerCity",
"client_callback_url": "https://webhook.site/url",
"country_id": "2",
"currency": "XOF",
"email": "john.doe@example.com",
"first_name": "John",
"last_name": "Doe",
"line1": "CustomerStreet",
"mobile": "22991600649",
"mtn": [
{
"phone_number": "22991600649"
}
],
"payment_method_type": "mtn",
"payment_reference": "",
"postal_code": "192.0.0.1",
"third_party_reference_1": ""
},
"salt": "mySalt123",
"sender": "Integration name",
"timestamp": "Timestamp value",
"signature":"XxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxX"
}
Callback Enhancements
- Removed
invoice_no
and niobi_ref
fields from callback responses for payouts.
- Added a
currency
field for complete payment details.
Sample V3 Callback Response for Payouts:
{
"client_id": "Your client id",
"sender": "Integration title",
"salt": "Random salt value",
"timestamp": "Timestamp",
"params": {
"account": "The account number of the account the payment was made from",
"account_number" : "Account number for paybill payment method",
"amount": "Amount paid out",
"fee": "Fees incurred for the payment",
"invoice_no": "Payout invoice number",
"niobi_ref":"Unique reference Niobi specific to Niobi",
"message": "Message describing the transaction status",
"mobile": "Mobile number of the recipient",
"payee": "Full name of the recipient",
"payment_channel": "Payment channel",
"payment_reference": "Unique information passed by user to identify transaction",
"payoutId": "Unique transaction id of the payment",
"ref": "Transaction reference shared by provider",
"statusCode": "Status code of the transaction",
"third_party_reference_1": "External reference",
"third_party_reference_2": "External reference",
"transaction_date": "Date payment was made",
"transaction_detail": "Message with details of the transaction",
"type": "Transaction type"
},
"signature": "Request signature"
}
Sample V4 Callback Response for Payouts:
{
"client_id": "Your client id",
"sender": "Integration title",
"salt": "Random salt value",
"timestamp": "Timestamp",
"params": {
"account": "The account number of the account the payment was made from",
"account_number" : "Account number for paybill payment method",
"amount": "Amount paid out",
"currency":"Currency of the payment",
"fee": "Fees incurred for the payment",
"message": "Message describing the transaction status",
"mobile": "Mobile number of the recipient",
"payee": "Full name of the recipient",
"payment_channel": "Payment channel",
"payment_reference": "Unique information passed by user to identify transaction",
"payoutId": "Unique transaction id of the payment",
"ref": "Transaction reference shared by provider",
"statusCode": "Status code of the transaction",
"third_party_reference_1": "External reference",
"third_party_reference_2": "External reference",
"transaction_date": "Date payment was made",
"transaction_detail": "Message with details of the transaction",
"type": "Transaction type"
},
"signature": "Request signature"
}
Sample V4 Callback Response for Payins:
{
"client_id": "Your client id",
"sender": "Integration title",
"salt": "Random salt value",
"timestamp": "Timestamp",
"params": {
"amount": "Amount deposited",
"currency":"Transaction currency",
"depositId": "Transaction id of the deposit",
"email": "Your email address",
"failureReason": {
"failureCode": "Failure Code from MNO in case of failure",
"failureMessage": "Descriptive message on the failure reason in case of failure"
},
"mobile": "Mobile that made the deposit",
"message": "Message describing deposit success or failure",
"name": "Account username",
"payment_link_id": null,
"payment_link_payment_id": null,
"reference" : " Transaction id",
"status": "Status of the deposit",
"statusCode": "Status code of the transaction"
"third_party_reference_1": "TRANS1",
"third_party_reference_2": null,
},
"signature": "Request signature"
}
Payment Methods Standardization
- Removed case sensitivity for payment methods (e.g.,
MTN
, TNM
, Moov
).
Sample Ways to Pass the Payment Methods:
"payment_method_type": "moov"
"payment_method_type": "Moov"
"payment_method_type": "MOOV"
New Features and API Improvements
NGN Payouts and Payins
- Added support for Nigerian transactions.
- NGN deposits now require two fields:
{
"client_id": "client_id",
"params": {
"account_name": "BTC Bank",
"amount": "5500",
"callback_url": "https://webhook.site/",
"country_id": 17,
"currency": "NGN",
"mobile": "2347xxxxxx00",
"name": "Joseph Mike",
"payment_method_type": "bank",
"third_party_reference_1": null,
"third_party_reference_2": null
},
"salt": "salt value",
"sender": "Integration name",
"timestamp": xxxxxxx,
"signature": "1xxxxxxxxxxxxxxxx8"
}
- Users can now send and receive payments in Nigeria via bank transfers. See more under collection methods.
GHS Payouts and Payins
- Added support for Ghanaian Cedi (GHS) transactions.
- Users can now send and receive payments in GHS via mobile money through MTN, Vodafone, and Tigo. See more under collection methods.
Wave Senegal Updates
- Added support for Wave Senegal.
- Now includes:
- Successful URL for completed transactions
- Failure URL for failed transactions
Find the full reference under collection methods.
Updated Supported Countries
- Discontinued DRC and Malawi temporarily due to settlement inefficiencies and FX volatility. Please find the full list of supported countries here
Updated Test Phone Numbers
- Updated test phone numbers to simulate real-world cases.
- Added a test account number for KES Paybill transactions. Refer to the full list of test phone numbers here.
Improved Error Pages for Troubleshooting
- Updated error pages under the Troubleshooting section to make debugging easier for developers.
- Clearer error descriptions and recommended resolutions are now included. Please refer to the Troubleshooting Section for more details.