> ## 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.

# Release Notes - 7.0.0 - May 2026

**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:

```json theme={null}
{
  "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

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

See: [Sub-Merchant Management](../submerchant/add-submerchant)

***

### 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

1. Search your sandbox integration for `dev.users.niobi.co`.
2. Replace it with `sandbox.users.niobi.co` in all API client code and webhook URLs.
3. Restart your sandbox environment and rerun tests.
4. 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:**

```json theme={null}
{
  "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:**

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

<Note type="info">
  Requests without these fields will be rejected.
</Note>

See: [Cameroon XAF payout sample](../making-payments-v4#sample-api-request-for-cameroon-xaf-payouts)

***

### 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:**

```json theme={null}
{
  "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:**

1. Create a success page and a failure page in your application.
2. Populate `successful_url` and `failure_url` in the request payload.
3. After the customer is redirected back to your site, query the [Transaction Status API](/api-reference/payment/niobi-get-transaction-status-v3) to confirm the final transaction outcome before displaying a result to the customer.

See: [South Africa ZAR Bank / EFT](../collect-v4#south-africa-zar-bank-eft-collections)

***

## 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:**

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

**Example response:**

```json theme={null}
{
  "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:**

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

See: [Get Transaction Status (v3)](/api-reference/payment/niobi-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:**

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

See details [here](/making-payments-v4#conditional-sms-notifications-for-external-beneficiaries-kes-payouts)

***

### 3. Portal IP Whitelisting Management

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

**Steps:**

1. Go to **Workspace > IP Whitelisting** in the portal.
2. Add new IP addresses using the **Add New** button.
3. 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](/whitelisting#portal-ip-whitelisting-guide)

***

## 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:**

```json theme={null}
{
  "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](../api-reference/payment-link/create-a-payment-linkv3)

***

### 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:**

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

See:

* [Ivory Coast Orange Flow](../collect-v4#otp-verification-ivory-coast-orange-payins)
* [Testing numbers](../testingv4#côte-d'ivoire-orange)

***

### 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:**

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

See: [Uganda transaction limits](../transaction-limitsv4#uganda)

***

## Sources

* March Release original: [2026-03 Changes](./03-2026)
* Sub-Merchant guide: [Sub-Merchant Management](../submerchant/add-submerchant)
* Transaction Status v3 API page: [Get Transaction Status (v3)](/api-reference/payment/niobi-get-transaction-status-v3)
* Portal IP Whitelisting: [Portal IP Whitelisting](../whitelisting#portal-ip-whitelisting-guide)