Release Notes

Release Date: May 2026

TL;DR

Sub-merchant routing — attach transactions to individually managed sub-merchants
Sandbox base URL changed from dev.users.niobi.co to sandbox.users.niobi.co
Cameroon XAF payouts now require sender name and phone number
South Africa collections require successful_url and failure_url
New Transaction Status v3 endpoint for unified payin and payout status checks
Payment Link v3 supports optional currency_country_id
UGX and RWF transaction limits have been updated

Breaking Changes

The changes below require immediate integration updates.

1. Sub-merchant Management

This feature is for marketplaces, payment service providers, and enterprises that manage multiple merchants under a single Niobi account. It lets you onboard each sub-merchant in the portal, review them through a compliance workflow, and then attach each transaction to a specific sub_merchant_id.

How it works

Create a sub-merchant in the Niobi portal.
The sub-merchant enters review and moves through these statuses: Pending, Approved, or Suspended.
Only Approved sub-merchants can process live transactions.
Include sub_merchant_id in the transaction payload to route payments to the selected sub-merchant.

Who it is for

Marketplaces settling funds to individual vendors.
PSPs integrating multiple merchants.
Businesses that need separate merchant attribution for compliance, reporting, or risk controls.

API usage

Include sub_merchant_id inside params for eligible transactions:

{
  "client_id": "<YOUR_CLIENT_ID>",
  "salt": "<YOUR_SALT>",
  "timestamp": 1234567890,
  "signature": "<YOUR_SIGNATURE>",
  "params": {
    "amount": 1000,
    "currency": "KES",
    "country_id": 1,
    ...
    "sub_merchant_id": "<YOUR_SUB_MERCHANT_ID>",
    "description": "Payment for Order #1234"
  }
}

Status details

Pending: Submitted and awaiting review by the compliance team. Do not send live transactions yet.
Approved: The sub-merchant has passed review and is cleared for live processing.
Suspended: The sub-merchant is blocked due to compliance or risk issues. Contact support to resolve.

Steps

Confirm whether your integration uses sub-merchant routing.
Add sub_merchant_id to all relevant transaction requests.
Check the sub-merchant status in the portal before sending live traffic.
Review the guide for onboarding, approval, and status definitions.

See: Sub-merchant Management

2. Sandbox Base URL Change

All sandbox API calls and sandbox webhook endpoints must be updated to use the new sandbox URL. Previous sandbox base URL:

https://dev.users.niobi.co

New sandbox base URL:

https://sandbox.users.niobi.co

Steps

Search your sandbox integration for dev.users.niobi.co.
Replace it with sandbox.users.niobi.co in all API client code and webhook URLs.
Restart your sandbox environment and rerun tests.
Confirm sandbox webhook delivery to the updated callback endpoint.

Remaining traffic to dev.users.niobi.co will fail after deprecation.

3. XAF Cameroon Payouts Now Require Sender Details

XAF payouts to Cameroon now require the sender’s first name, last name, and phone number in the payout request to comply with local regulatory requirements. Required fields:

sender_firstname
sender_lastname
sender_phone_number

Example request:

{
  "client_id": "<YOUR_CLIENT_ID>",
  "salt": "<YOUR_SALT>",
  "timestamp": 1234567890,
  "signature": "<YOUR_SIGNATURE>",
  "params": {
    "country_id": 4,
    "currency": "XAF",
    "amount": 5000,
    ...
    "sender_firstname": "John",
    "sender_lastname": "Doe",
    "sender_phone_number": "2376XXXXXXXX"
  }
}

Implementation checklist:

Add sender_firstname, sender_lastname, and sender_phone_number to all XAF/Cameroon payout requests.
Format sender_phone_number as 237XXXXXXXXX — country code 237 followed by the local number, no + prefix.
Ensure your request builder includes these fields for all country_id: 4 / currency: XAF payouts, and update any payload validation logic accordingly.

Requests without these fields will be rejected.

See: Cameroon XAF payout sample

4. South Africa (ZAR) Collections Now Require Redirect URLs

South Africa EFT collections now require both successful_url and failure_url in the request payload. After the customer completes or cancels the bank transfer, they are redirected to the appropriate URL. Example request snippet:

{
  "client_id": "<YOUR_CLIENT_ID>",
  "salt": "<YOUR_SALT>",
  "timestamp": 1234567890,
  "signature": "<YOUR_SIGNATURE>",
  "params": {
    "country_id": 15,
    "currency": "ZAR",
    "amount": 250,
    ...
    "successful_url": "https://yoursite.com/payment/success",
    "failure_url": "https://yoursite.com/payment/failure"
  }
}

Implementation checklist:

Create a success page and a failure page in your application.
Populate successful_url and failure_url in the request payload.
After the customer is redirected back to your site, query the Transaction Status API to confirm the final transaction outcome before displaying a result to the customer.

See: South Africa ZAR Bank / EFT

New Features

These features are available and can be integrated now.

1. Transaction Status v3

New endpoint: POST /api/v3/get-unified-transaction-status This endpoint replaces the v2 status endpoint and returns a richer, unified response for both payins and payouts in a single call. Previously, payin and payout status responses had different structures; v3 normalises them. Purpose:

Returns unified metadata for both payins and payouts.
Simplifies transaction reconciliation across all payment channels.

Example request:

{
  "client_id": "<YOUR_CLIENT_ID>",
  "salt": "<YOUR_SALT>",
  "timestamp": 1234567890,
  "signature": "<YOUR_SIGNATURE>",
  "params": {
    "id": "<TRANSACTION_REFERENCE>",
    "type": "payin"
  }
}

Example response:

{
  "success": true,
  "message": "Transaction data fetched successfully.",
  "data": {
    "amount": "Transaction amount",
    "fee": "Transaction fee",
    "currency": "Currency code",
    "status": "Transaction status",
    "payee": "Payee name (payouts only)",
    "invoice_no": "Invoice number (payouts only)",
    "mobile": "2547xxxxxxxx",
    "account_number": "Account number (where applicable)",
    "ref": "NIO-SXXXXX",
    "balance": "Wallet balance (where applicable)",
    "transaction_detail": "Additional transaction detail",
    "payment_channel": "Payment channel used",
    "transaction_date": "Transaction date",
    "created_at": "Record creation date",
    "updated_at": "Last updated date",
    "callback_url": "https://yoursite.com/callback",
    "status_code": "Status code",
    "failureReason": { "failureCode": null, "failureMessage": null }
  }
}

Integration notes:

Send params.id with the transaction reference you want to look up.
Set params.type to payin for collections or payout for disbursements.

See: Get Transaction Status (v3)

2. Conditional SMS for KES Payouts

SMS notifications to beneficiaries can now be enabled for KES payouts. When active, the recipient receives an SMS confirming the payment after a successful disbursement. This is an account-level configuration — it does not require any changes to your API requests. Steps:

Contact support at support@niobi.co or via your Slack/WhatsApp support channel to request the feature be enabled for your account.
Once enabled, run a test KES payout and confirm the beneficiary receives the SMS notification.

See details here

3. Portal IP Whitelisting Management

You can now manage IP whitelist entries directly in the dashboard without contacting support. Steps:

Go to Workspace > IP Whitelisting in the portal.
Add new IP addresses using the Add New button.
Update an existing entry any time your server’s IP changes to avoid losing API access.

This removes the need to raise a support request for routine IP changes and speeds up environment transitions. See more details here

Updates

These improvements are available now and may require optional integration updates.

1. Payment Link v3 — Optional `currency_country_id`

The Payment Link v3 payload now supports an optional currency_country_id field. Use it when the payer’s physical location differs from the country implied by the country_id in the request — for example, when a Kenyan customer is paying via a Uganda-issued currency account. Example:

{
  "client_id": "<YOUR_CLIENT_ID>",
  "salt": "<YOUR_SALT>",
  "timestamp": 1234567890,
  "signature": "<YOUR_SIGNATURE>",
  "params": {
    "amount": 500,
    "currency": "KES",
    "currency_country_id": 1,
    "description": "Payment for Order #1234",
    "email": "customer@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "payment_reference": "ORDER1234",
    "business_name": "My Business",
    "item_name": "item name",
    "callback_url": "https://yoursite.com/callback",
    "redirection_url": "https://yoursite.com/redirect",
    "country_id": 2,
    "phone": "25471xxxxxxx"
  }
}

currency_country_id is optional. When provided, it explicitly identifies the payer’s country.
If omitted, the system infers the payer country from currency and country_id.

See: Payment Link v3 payload

2. Ivory Coast Orange Sandbox Flow

The Ivory Coast Orange (telecom operator) OTP payment flow is now supported in the sandbox environment, allowing you to simulate the full production flow before going live. Steps:

Set your sandbox base URL to https://sandbox.users.niobi.co.
Implement the OTP redirect flow as documented in the Ivory Coast Orange guide.
Use the sandbox test phone numbers from the Testing Guide to trigger the OTP flow.
Complete the full OTP verification cycle and confirm expected callbacks before going live.

See:

3. Updated UGX and RWF Transaction Limits

Transaction limits for UGX (Ugandan Shilling) and RWF (Rwandan Franc) payouts have been updated and are now in effect. Steps:

Review the new limits in the transaction limits reference and compare against any hardcoded min/max values in your integration.
Update your payload validation logic to reflect the new limits for UGX and RWF transactions.
Run test payouts at the boundary values to confirm your integration handles them correctly.

See: Uganda transaction limits

Sources

March Release original: 2026-03 Changes
Sub-merchant guide: Sub-merchant Management
Transaction Status v3 API page: Get Transaction Status (v3)
Portal IP Whitelisting: Portal IP Whitelisting

Documentation Index

​TL;DR

​Breaking Changes

​1. Sub-merchant Management

​How it works

​Who it is for

​API usage

​Status details

​Steps

​2. Sandbox Base URL Change

​Steps

​3. XAF Cameroon Payouts Now Require Sender Details

​4. South Africa (ZAR) Collections Now Require Redirect URLs

​New Features

​1. Transaction Status v3

​2. Conditional SMS for KES Payouts

​3. Portal IP Whitelisting Management

​Updates

​1. Payment Link v3 — Optional currency_country_id

​2. Ivory Coast Orange Sandbox Flow

​3. Updated UGX and RWF Transaction Limits

​Sources

TL;DR

Breaking Changes

1. Sub-merchant Management

How it works

Who it is for

API usage

Status details

Steps

2. Sandbox Base URL Change

Steps

3. XAF Cameroon Payouts Now Require Sender Details

4. South Africa (ZAR) Collections Now Require Redirect URLs

New Features

1. Transaction Status v3

2. Conditional SMS for KES Payouts

3. Portal IP Whitelisting Management

Updates

1. Payment Link v3 — Optional `currency_country_id`

2. Ivory Coast Orange Sandbox Flow

3. Updated UGX and RWF Transaction Limits

Sources