> ## Documentation Index > Fetch the complete documentation index at: https://docs.niobi.co/llms.txt > Use this file to discover all available pages before exploring further. # 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:** ```json theme={null} { "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:** ```json theme={null} { "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:** ```json theme={null} { "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:** ```json theme={null} { "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:** ```json theme={null} { "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:** ```json theme={null} "payment_method_type": "moov" ``` ```json theme={null} "payment_method_type": "Moov" ``` ```json theme={null} "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` ```json theme={null} { "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](/collect-v4). ### **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](/collect-v4). ### **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](/collect-v4). ### **Updated Supported Countries** * Discontinued **DRC and Malawi** temporarily due to settlement inefficiencies and FX volatility. Please find the full list of supported countries [here](/countries-v4) ### **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.](/testingv4) ### **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](/errors/overview) for more details.