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.