API Version 4 Release Notes

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:

account_name
name

{
      "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.

​Overview

​Breaking Changes

​Standardized Amount Handling

​Callback Enhancements

​Payment Methods Standardization

​New Features and API Improvements

​NGN Payouts and Payins

​GHS Payouts and Payins

​Wave Senegal Updates

​Updated Supported Countries

​Updated Test Phone Numbers

​Improved Error Pages for Troubleshooting