To start collecting payments using these methods, ensure that your Niobi account is set up and verified. Refer to the ‘Setting up a Niobi Account’ section in the Getting Started section for detailed steps on account creation and setup.

​
Payment Collection Flow

Please refer to the flow chart below to understand the payment collection flow. The “Merchant Client” refers to our API Clients who are collecting payments from their customers.

payment-collection-flow

For Senegal Orange deposits, the end user receives an SMS with a shortcode after the deposit is initiated. They dial the shortcode, triggering a USSD prompt where they input their PIN to approve the transaction.

​
Using the API

The unified-collections api endpoint is used for collecting payments across the supported countries. Please find the full API reference here.

You will be required to pass in the following parameters :

ParameterTypeRequiredDescription
AmountNumberYesThe amount to be deposited to your account.
MobileStringYesThe phone number that will be making the payment.
Country IDStringYesThe ID of the country the deposit will be made from. The full list can be found here.
CurrencyStringYesThe currency in which the deposit will be made.
Payment Method TypeStringYesThe payment channel that will be used for the deposit.
Callback URLStringNoThe URL to receive the callback response on.
Third Party ReferenceStringNoInformation you’d like to use to refer to the deposit later.
NameStringOnly for NGNCustomer’s name (Only for Nigerian deposits).
Account NameStringOnly for NGNCustomer’s account name that would appear when funds are reconciled in their account (Only for Nigerian deposits).

You will then generate a signature using the parameters above and proceed to make an API request using the payload. On successful deposit, you will receive a callback response with the deposit details. Please find a detailed description of the callback response under Callback URL Section.

name and account_name fields are only applicable for Nigerian bank deposits.

​
Front End Integration

This section provides a high-level overview of how to integrate your front-end with the Collections API.

1

Initiating the unified collections API Request

To begin, integrate the unified Collections API endpoint and initiate a deposit transaction by making an API request.

​
Sample API Request

{
        "client_id": "client_id",
        "params": {
            "amount": "10000",
            "callback_url": "https:/exmaple.com",
            "country_id": 1,
            "currency": "KES",
            "mobile": "254xxxxxxxxx0",
            "payment_method_type": "send money",
            "third_party_reference_1": "",
            "third_party_reference_2": ""
        },
        "salt": "salt_value",
        "sender": "Integration_name",
        "timestamp": xxxxx,
        "signature": "0xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx5"
    }
2

Transaction Verification

After the initial request is completed, the user will be prompted to input an authentication token on their phone to verify the transaction.

3

Handling Transaction Status

Once the transaction request has been processed, you have two options for managing the transaction status:

  1. Receiving a Callback. A callback response containing the transaction details will be sent to your configured URL. You can set up an endpoint on your front end to handle this callback and update the user interface accordingly, such as displaying success or failure messages based on the transaction outcome.

  2. Constantly Querying Transaction Status. Alternatively, you can query the transaction status endpoint periodically (recommended for 2 minutes) to check for updates on the transaction status.

By following this flow, you can seamlessly integrate your front end with the API, ensuring secure and responsive transaction processing for your users.

​
Bank Collections

We supported collections through bank transfers on our unified collections API.

The Bank Transfer service is currently available only for Nigerian Naira (NGN) transactions.

​
How It Works

To collect payments through bank transfer payments, make an API call to our unified collections API with the required payment details (name and account_name). A dynamic virtual bank account will be generated for the transaction, which your customer can use to make the payment. Once the paymet is made, a callback notification will be sent to confirm the transaction details. A dynamic virtual bank account is a temporary, single-use bank account that expires after a single transaction.

Currently supported banks for dynamic virtual accounts:

  1. Wema Bank
  2. Sterling Bank
  3. Providus Bank

Additional bank options will be made available over time.

​
Sample API Request

{
        "client_id": "client_id",
        "params": {
            "account_name": "Bank name",
            "amount": "10000",
            "callback_url": "https:/exmaple.com",
            "country_id": 17,
            "currency": "NGN",
            "mobile": "234xxxxxxxxx0",
            "name": "Joseph Mike",
            "payment_method_type": "mtn",
            "third_party_reference_1": "",
            "third_party_reference_2": ""
        },
        "salt": "salt_value",
        "sender": "Integration_name",
        "timestamp": xxxxx,
        "signature": "0xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx5"
    }

The name and account name fields are required for Nigerian deposits and refer to the customer’s name and their bank account name when the amount is resolved in their account.

​
Sample API response

{   
    "success":true,
    "message":"Verification token was sent to your mobile number. Kindly verify to proceed payment.",
    "data":{
        "account_name":"BTC Bank",
        "amount":"10000",
        "callback_url":"https:\/\/example.com",
        "country_id":17,
        "currency":"NGN",
        "mobile":"234xxxxxxxxx0",
        "account_number":"76xxxx98",
        "name":"Joseph Mike",
        "payment_method_type":"mtn",
        "third_party_reference_1":"",
        "third_party_reference_2":"",
        "MerchantRequestID":"8xxxxxxxxxxxxxxxxxxx3",
        "depositId":"8xxxxxxxxxxxxxxxxxxx3",
        "status":"success",
        "bank_name": "Bank name",
        "bank_code": "000",
        "status": "success"
        },
    "status_code":"000000"
    }

Once a payment is completed, we send a webhook notification to your provided URL. You can use the reference from the payload to retrieve payment details using our transaction status API.

​
Wave Senegal Collection Flow

This section provides a high-level overview of the collections flow for Wave payment method in Senegal.

1

Initiating the unified collections API Request

To begin, integrate the unified Collections API endpoint and initiate a deposit transaction by making an API request with 2 additional fields successful_url and failure_url.

​
Sample API Request

{
        "client_id": "client_id",
        "params": {
            "amount": "10000",
            "callback_url": "https:/exmaple.com",
            "country_id": 1,
            "currency": "KES",
            "mobile": "254xxxxxxxxx0",
            "payment_method_type": "send money",
            "third_party_reference_1": "",
            "third_party_reference_2": "",
            "successful_url":"",
            "failure_url":""
        },
        "salt": "salt_value",
        "sender": "Integration_name",
        "timestamp": xxxxx,
        "signature": "0xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx5"
    }
2

Transaction Verification

A callback response containing an authoriztion url will be sent to your configured URL. Open this authorization url in your browser of choice to proceed with the payment.

3

Handling Transaction Status

Once the transaction request has been processed, you will receive a callback with the transaction details. Alternatively, you can query the transaction status endpoint periodically (recommended for 2 minutes) to check for updates on the transaction status.

​
OTP Verification (Ivory Coast Orange Payins)

For Orange payins in Côte d’Ivoire, OTP verification is required. This ensures secure authorization of deposits initiated via our Collections API.

​
How It Works

Step 1: Initiate a Deposit Request

  • Make a request to initiate a deposit using our collections api.
  • Include the otp field in the request payload.
An OTP will be sent to the customer’s mobile number.

A sample response to the deposit initiation:

{
    "success": true,
    "message": "Verification token was sent to your mobile number. Kindly verify to proceed payment.",
    "data": {
        "status": "pending",
        "created_at": "2025-04-16T07:33:06.000000Z",
        "updated_at": "2025-04-16T07:33:09.000000Z",
        "amount": "2",
        "to": "225076xxxx602",
        "ref": null,
        "currency": "XOF",
        "country_id": 3,
        "country": "Côte d’Ivoire",
        "sender": "xxxx",
        "salt": "niobi_salt",
        "first_name": null,
        "last_name": null,
        "email": "john@doe.com",
        "third_party_reference_1": "TRANS-123456789",
        "third_party_reference_2": null,
        "payment_initiator": "xxxxx",
        "failureCode": null,
        "payment_token": "7cb952a7-xxxx-xxxx-xxxx-3d88b6aa3"
    },
    "status_code": "000000"
}

Step 2: Verify the Transaction

To complete the payin, verify the transaction using the OTP and the payment_token. Endpoint: /v4/niobi-unified-process-transaction

{
    "client_id": "TLNnEXPhsFmBUbU6vwVPVAVZCLVUC7OL2Bu5HnQo",
    "params": {
        "otp": "1234",
        "payment_token": "7cb952a7-6477-4ff0-8736-3dd9488b6aa3"
    },
    "salt": "niobi_salt",
    "sender": "ApexVim",
    "timestamp": 1744788807,
    "signature": "3a3cf7f2e3ff8d4ee991d7e1323312887dfda8536b8c2e197d0d4ef764013658"
}

A successful verification will confirm that the transaction has been authorized and is being processed accordingly.