Submit Niobi Unified Payments

Handles payment processing for Niobi, supporting multiple payment methods.

POST /api/v3/niobi-unified-payments

Niobi unified payment version-3

cURL

curl --request POST \
  --url https://sandbox.users.niobi.co/api/v3/niobi-unified-payments \
  --header 'Content-Type: application/json' \
  --data '
{
  "client_id": "K1PoY1WYricSpXh6Wm24twnk6ecPJOWrHGsqiKJr",
  "params": {
    "amount": 1000,
    "currency": "KES",
    "payment_reference": "TRANS-123456789",
    "first_name": "John",
    "last_name": "Doe",
    "mobile": "254123456789",
    "email": "[e-mail]",
    "country_id": "1",
    "city": "Nairobi",
    "postal_code": "001001",
    "line1": "abc, xyz",
    "client_callback_url": "https://your-domain.com/niobi/result",
    "payment_method_type": "send money",
    "customer_identifier": 1234,
    "description": "abc, xyz",
    "third_party_reference_1": "<string>",
    "third_party_reference_2": "<string>",
    "mtn": [
      {
        "phone_number": "254123456789"
      }
    ],
    "Orange": [
      {
        "phone_number": "254123456789"
      }
    ],
    "Vodacom": [
      {
        "phone_number": "254123456789"
      }
    ],
    "Airtel": [
      {
        "phone_number": "254123456789"
      }
    ],
    "at": [
      {
        "phone_number": "254123456789"
      }
    ],
    "Vodafone": [
      {
        "phone_number": "254123456789"
      }
    ],
    "tnm": [
      {
        "phone_number": "254123456789"
      }
    ],
    "Zamtel": [
      {
        "phone_number": "254123456789"
      }
    ],
    "Halotel": [
      {
        "phone_number": "254123456789"
      }
    ],
    "Tigo": [
      {
        "phone_number": "254123456789"
      }
    ],
    "Free": [
      {
        "phone_number": "254123456789"
      }
    ],
    "sendmoney": [
      {
        "phone_number": "254123456789"
      }
    ],
    "paybill": [
      {
        "paybill_number": "123456",
        "account_number": "123456789"
      }
    ],
    "tillnumber": [
      {
        "till_number": "123456"
      }
    ],
    "pesalink": [
      {
        "bank_name": "ABC",
        "bank_code": "00",
        "branch_name": "ABC",
        "account_name": "ABC",
        "account_number": "123456789"
      }
    ]
  },
  "salt": "justrandomstring",
  "sender": "John.co",
  "timestamp": 1709363033,
  "signature": "2193d01d50d4bd5da234ac0e0add5d4ccb40907a1b1ab27a12d2c1d88a5d5807"
}
'

import requests

url = "https://sandbox.users.niobi.co/api/v3/niobi-unified-payments"

payload = {
    "client_id": "K1PoY1WYricSpXh6Wm24twnk6ecPJOWrHGsqiKJr",
    "params": {
        "amount": 1000,
        "currency": "KES",
        "payment_reference": "TRANS-123456789",
        "first_name": "John",
        "last_name": "Doe",
        "mobile": "254123456789",
        "email": "[e-mail]",
        "country_id": "1",
        "city": "Nairobi",
        "postal_code": "001001",
        "line1": "abc, xyz",
        "client_callback_url": "https://your-domain.com/niobi/result",
        "payment_method_type": "send money",
        "customer_identifier": 1234,
        "description": "abc, xyz",
        "third_party_reference_1": "<string>",
        "third_party_reference_2": "<string>",
        "mtn": [{ "phone_number": "254123456789" }],
        "Orange": [{ "phone_number": "254123456789" }],
        "Vodacom": [{ "phone_number": "254123456789" }],
        "Airtel": [{ "phone_number": "254123456789" }],
        "at": [{ "phone_number": "254123456789" }],
        "Vodafone": [{ "phone_number": "254123456789" }],
        "tnm": [{ "phone_number": "254123456789" }],
        "Zamtel": [{ "phone_number": "254123456789" }],
        "Halotel": [{ "phone_number": "254123456789" }],
        "Tigo": [{ "phone_number": "254123456789" }],
        "Free": [{ "phone_number": "254123456789" }],
        "sendmoney": [{ "phone_number": "254123456789" }],
        "paybill": [
            {
                "paybill_number": "123456",
                "account_number": "123456789"
            }
        ],
        "tillnumber": [{ "till_number": "123456" }],
        "pesalink": [
            {
                "bank_name": "ABC",
                "bank_code": "00",
                "branch_name": "ABC",
                "account_name": "ABC",
                "account_number": "123456789"
            }
        ]
    },
    "salt": "justrandomstring",
    "sender": "John.co",
    "timestamp": 1709363033,
    "signature": "2193d01d50d4bd5da234ac0e0add5d4ccb40907a1b1ab27a12d2c1d88a5d5807"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    client_id: 'K1PoY1WYricSpXh6Wm24twnk6ecPJOWrHGsqiKJr',
    params: {
      amount: 1000,
      currency: 'KES',
      payment_reference: 'TRANS-123456789',
      first_name: 'John',
      last_name: 'Doe',
      mobile: '254123456789',
      email: '[e-mail]',
      country_id: '1',
      city: 'Nairobi',
      postal_code: '001001',
      line1: 'abc, xyz',
      client_callback_url: 'https://your-domain.com/niobi/result',
      payment_method_type: 'send money',
      customer_identifier: 1234,
      description: 'abc, xyz',
      third_party_reference_1: '<string>',
      third_party_reference_2: '<string>',
      mtn: [{phone_number: '254123456789'}],
      Orange: [{phone_number: '254123456789'}],
      Vodacom: [{phone_number: '254123456789'}],
      Airtel: [{phone_number: '254123456789'}],
      at: [{phone_number: '254123456789'}],
      Vodafone: [{phone_number: '254123456789'}],
      tnm: [{phone_number: '254123456789'}],
      Zamtel: [{phone_number: '254123456789'}],
      Halotel: [{phone_number: '254123456789'}],
      Tigo: [{phone_number: '254123456789'}],
      Free: [{phone_number: '254123456789'}],
      sendmoney: [{phone_number: '254123456789'}],
      paybill: [{paybill_number: '123456', account_number: '123456789'}],
      tillnumber: [{till_number: '123456'}],
      pesalink: [
        {
          bank_name: 'ABC',
          bank_code: '00',
          branch_name: 'ABC',
          account_name: 'ABC',
          account_number: '123456789'
        }
      ]
    },
    salt: 'justrandomstring',
    sender: 'John.co',
    timestamp: 1709363033,
    signature: '2193d01d50d4bd5da234ac0e0add5d4ccb40907a1b1ab27a12d2c1d88a5d5807'
  })
};

fetch('https://sandbox.users.niobi.co/api/v3/niobi-unified-payments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sandbox.users.niobi.co/api/v3/niobi-unified-payments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'client_id' => 'K1PoY1WYricSpXh6Wm24twnk6ecPJOWrHGsqiKJr',
    'params' => [
        'amount' => 1000,
        'currency' => 'KES',
        'payment_reference' => 'TRANS-123456789',
        'first_name' => 'John',
        'last_name' => 'Doe',
        'mobile' => '254123456789',
        'email' => '[e-mail]',
        'country_id' => '1',
        'city' => 'Nairobi',
        'postal_code' => '001001',
        'line1' => 'abc, xyz',
        'client_callback_url' => 'https://your-domain.com/niobi/result',
        'payment_method_type' => 'send money',
        'customer_identifier' => 1234,
        'description' => 'abc, xyz',
        'third_party_reference_1' => '<string>',
        'third_party_reference_2' => '<string>',
        'mtn' => [
                [
                                'phone_number' => '254123456789'
                ]
        ],
        'Orange' => [
                [
                                'phone_number' => '254123456789'
                ]
        ],
        'Vodacom' => [
                [
                                'phone_number' => '254123456789'
                ]
        ],
        'Airtel' => [
                [
                                'phone_number' => '254123456789'
                ]
        ],
        'at' => [
                [
                                'phone_number' => '254123456789'
                ]
        ],
        'Vodafone' => [
                [
                                'phone_number' => '254123456789'
                ]
        ],
        'tnm' => [
                [
                                'phone_number' => '254123456789'
                ]
        ],
        'Zamtel' => [
                [
                                'phone_number' => '254123456789'
                ]
        ],
        'Halotel' => [
                [
                                'phone_number' => '254123456789'
                ]
        ],
        'Tigo' => [
                [
                                'phone_number' => '254123456789'
                ]
        ],
        'Free' => [
                [
                                'phone_number' => '254123456789'
                ]
        ],
        'sendmoney' => [
                [
                                'phone_number' => '254123456789'
                ]
        ],
        'paybill' => [
                [
                                'paybill_number' => '123456',
                                'account_number' => '123456789'
                ]
        ],
        'tillnumber' => [
                [
                                'till_number' => '123456'
                ]
        ],
        'pesalink' => [
                [
                                'bank_name' => 'ABC',
                                'bank_code' => '00',
                                'branch_name' => 'ABC',
                                'account_name' => 'ABC',
                                'account_number' => '123456789'
                ]
        ]
    ],
    'salt' => 'justrandomstring',
    'sender' => 'John.co',
    'timestamp' => 1709363033,
    'signature' => '2193d01d50d4bd5da234ac0e0add5d4ccb40907a1b1ab27a12d2c1d88a5d5807'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox.users.niobi.co/api/v3/niobi-unified-payments"

	payload := strings.NewReader("{\n  \"client_id\": \"K1PoY1WYricSpXh6Wm24twnk6ecPJOWrHGsqiKJr\",\n  \"params\": {\n    \"amount\": 1000,\n    \"currency\": \"KES\",\n    \"payment_reference\": \"TRANS-123456789\",\n    \"first_name\": \"John\",\n    \"last_name\": \"Doe\",\n    \"mobile\": \"254123456789\",\n    \"email\": \"[e-mail]\",\n    \"country_id\": \"1\",\n    \"city\": \"Nairobi\",\n    \"postal_code\": \"001001\",\n    \"line1\": \"abc, xyz\",\n    \"client_callback_url\": \"https://your-domain.com/niobi/result\",\n    \"payment_method_type\": \"send money\",\n    \"customer_identifier\": 1234,\n    \"description\": \"abc, xyz\",\n    \"third_party_reference_1\": \"<string>\",\n    \"third_party_reference_2\": \"<string>\",\n    \"mtn\": [\n      {\n        \"phone_number\": \"254123456789\"\n      }\n    ],\n    \"Orange\": [\n      {\n        \"phone_number\": \"254123456789\"\n      }\n    ],\n    \"Vodacom\": [\n      {\n        \"phone_number\": \"254123456789\"\n      }\n    ],\n    \"Airtel\": [\n      {\n        \"phone_number\": \"254123456789\"\n      }\n    ],\n    \"at\": [\n      {\n        \"phone_number\": \"254123456789\"\n      }\n    ],\n    \"Vodafone\": [\n      {\n        \"phone_number\": \"254123456789\"\n      }\n    ],\n    \"tnm\": [\n      {\n        \"phone_number\": \"254123456789\"\n      }\n    ],\n    \"Zamtel\": [\n      {\n        \"phone_number\": \"254123456789\"\n      }\n    ],\n    \"Halotel\": [\n      {\n        \"phone_number\": \"254123456789\"\n      }\n    ],\n    \"Tigo\": [\n      {\n        \"phone_number\": \"254123456789\"\n      }\n    ],\n    \"Free\": [\n      {\n        \"phone_number\": \"254123456789\"\n      }\n    ],\n    \"sendmoney\": [\n      {\n        \"phone_number\": \"254123456789\"\n      }\n    ],\n    \"paybill\": [\n      {\n        \"paybill_number\": \"123456\",\n        \"account_number\": \"123456789\"\n      }\n    ],\n    \"tillnumber\": [\n      {\n        \"till_number\": \"123456\"\n      }\n    ],\n    \"pesalink\": [\n      {\n        \"bank_name\": \"ABC\",\n        \"bank_code\": \"00\",\n        \"branch_name\": \"ABC\",\n        \"account_name\": \"ABC\",\n        \"account_number\": \"123456789\"\n      }\n    ]\n  },\n  \"salt\": \"justrandomstring\",\n  \"sender\": \"John.co\",\n  \"timestamp\": 1709363033,\n  \"signature\": \"2193d01d50d4bd5da234ac0e0add5d4ccb40907a1b1ab27a12d2c1d88a5d5807\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://sandbox.users.niobi.co/api/v3/niobi-unified-payments")
  .header("Content-Type", "application/json")
  .body("{\n  \"client_id\": \"K1PoY1WYricSpXh6Wm24twnk6ecPJOWrHGsqiKJr\",\n  \"params\": {\n    \"amount\": 1000,\n    \"currency\": \"KES\",\n    \"payment_reference\": \"TRANS-123456789\",\n    \"first_name\": \"John\",\n    \"last_name\": \"Doe\",\n    \"mobile\": \"254123456789\",\n    \"email\": \"[e-mail]\",\n    \"country_id\": \"1\",\n    \"city\": \"Nairobi\",\n    \"postal_code\": \"001001\",\n    \"line1\": \"abc, xyz\",\n    \"client_callback_url\": \"https://your-domain.com/niobi/result\",\n    \"payment_method_type\": \"send money\",\n    \"customer_identifier\": 1234,\n    \"description\": \"abc, xyz\",\n    \"third_party_reference_1\": \"<string>\",\n    \"third_party_reference_2\": \"<string>\",\n    \"mtn\": [\n      {\n        \"phone_number\": \"254123456789\"\n      }\n    ],\n    \"Orange\": [\n      {\n        \"phone_number\": \"254123456789\"\n      }\n    ],\n    \"Vodacom\": [\n      {\n        \"phone_number\": \"254123456789\"\n      }\n    ],\n    \"Airtel\": [\n      {\n        \"phone_number\": \"254123456789\"\n      }\n    ],\n    \"at\": [\n      {\n        \"phone_number\": \"254123456789\"\n      }\n    ],\n    \"Vodafone\": [\n      {\n        \"phone_number\": \"254123456789\"\n      }\n    ],\n    \"tnm\": [\n      {\n        \"phone_number\": \"254123456789\"\n      }\n    ],\n    \"Zamtel\": [\n      {\n        \"phone_number\": \"254123456789\"\n      }\n    ],\n    \"Halotel\": [\n      {\n        \"phone_number\": \"254123456789\"\n      }\n    ],\n    \"Tigo\": [\n      {\n        \"phone_number\": \"254123456789\"\n      }\n    ],\n    \"Free\": [\n      {\n        \"phone_number\": \"254123456789\"\n      }\n    ],\n    \"sendmoney\": [\n      {\n        \"phone_number\": \"254123456789\"\n      }\n    ],\n    \"paybill\": [\n      {\n        \"paybill_number\": \"123456\",\n        \"account_number\": \"123456789\"\n      }\n    ],\n    \"tillnumber\": [\n      {\n        \"till_number\": \"123456\"\n      }\n    ],\n    \"pesalink\": [\n      {\n        \"bank_name\": \"ABC\",\n        \"bank_code\": \"00\",\n        \"branch_name\": \"ABC\",\n        \"account_name\": \"ABC\",\n        \"account_number\": \"123456789\"\n      }\n    ]\n  },\n  \"salt\": \"justrandomstring\",\n  \"sender\": \"John.co\",\n  \"timestamp\": 1709363033,\n  \"signature\": \"2193d01d50d4bd5da234ac0e0add5d4ccb40907a1b1ab27a12d2c1d88a5d5807\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sandbox.users.niobi.co/api/v3/niobi-unified-payments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"client_id\": \"K1PoY1WYricSpXh6Wm24twnk6ecPJOWrHGsqiKJr\",\n  \"params\": {\n    \"amount\": 1000,\n    \"currency\": \"KES\",\n    \"payment_reference\": \"TRANS-123456789\",\n    \"first_name\": \"John\",\n    \"last_name\": \"Doe\",\n    \"mobile\": \"254123456789\",\n    \"email\": \"[e-mail]\",\n    \"country_id\": \"1\",\n    \"city\": \"Nairobi\",\n    \"postal_code\": \"001001\",\n    \"line1\": \"abc, xyz\",\n    \"client_callback_url\": \"https://your-domain.com/niobi/result\",\n    \"payment_method_type\": \"send money\",\n    \"customer_identifier\": 1234,\n    \"description\": \"abc, xyz\",\n    \"third_party_reference_1\": \"<string>\",\n    \"third_party_reference_2\": \"<string>\",\n    \"mtn\": [\n      {\n        \"phone_number\": \"254123456789\"\n      }\n    ],\n    \"Orange\": [\n      {\n        \"phone_number\": \"254123456789\"\n      }\n    ],\n    \"Vodacom\": [\n      {\n        \"phone_number\": \"254123456789\"\n      }\n    ],\n    \"Airtel\": [\n      {\n        \"phone_number\": \"254123456789\"\n      }\n    ],\n    \"at\": [\n      {\n        \"phone_number\": \"254123456789\"\n      }\n    ],\n    \"Vodafone\": [\n      {\n        \"phone_number\": \"254123456789\"\n      }\n    ],\n    \"tnm\": [\n      {\n        \"phone_number\": \"254123456789\"\n      }\n    ],\n    \"Zamtel\": [\n      {\n        \"phone_number\": \"254123456789\"\n      }\n    ],\n    \"Halotel\": [\n      {\n        \"phone_number\": \"254123456789\"\n      }\n    ],\n    \"Tigo\": [\n      {\n        \"phone_number\": \"254123456789\"\n      }\n    ],\n    \"Free\": [\n      {\n        \"phone_number\": \"254123456789\"\n      }\n    ],\n    \"sendmoney\": [\n      {\n        \"phone_number\": \"254123456789\"\n      }\n    ],\n    \"paybill\": [\n      {\n        \"paybill_number\": \"123456\",\n        \"account_number\": \"123456789\"\n      }\n    ],\n    \"tillnumber\": [\n      {\n        \"till_number\": \"123456\"\n      }\n    ],\n    \"pesalink\": [\n      {\n        \"bank_name\": \"ABC\",\n        \"bank_code\": \"00\",\n        \"branch_name\": \"ABC\",\n        \"account_name\": \"ABC\",\n        \"account_number\": \"123456789\"\n      }\n    ]\n  },\n  \"salt\": \"justrandomstring\",\n  \"sender\": \"John.co\",\n  \"timestamp\": 1709363033,\n  \"signature\": \"2193d01d50d4bd5da234ac0e0add5d4ccb40907a1b1ab27a12d2c1d88a5d5807\"\n}"

response = http.request(request)
puts response.read_body

200

{
  "success": "true",
  "message": "Payment process initiated successfully.",
  "data": "",
  "res": ""
}

{
  "success": false,
  "message": "Country was not found or Niobi user not found or Payment process initiation failed."
}

{
  "success": false,
  "message": "Entity integration record not found or Client id not matched or Request was not verified."
}

{
  "success": false,
  "message": "User not found."
}

Please make sure to generate a new signature whenever you are creating a new payment.

List of Supported Countries

Country Id	Country	Country Code	Currency	Payment Method type	Required Fields
1	Kenya	254	KES	till number, pay bill, pesalink, send money	country_id, currency
2	Benin	229	XOF	mtn, Moov	country_id, currency
3	Cote D’Ivoire	225	XOF	mtn, Orange	country_id, currency
4	Cameroon	237	XAF	mtn, Orange	country_id, currency
9	Senegal	221	XOF	Orange, Free	country_id, currency
10	Tanzania	255	TZS	Airtel, Halotel, Tigo	country_id, currency
11	Uganda	256	UGX	mtn, Airtel	country_id, currency
12	Zambia	260	ZMW	Zamtel, mtn, Airtel	country_id, currency
13	Sierra Leone	232	SLE	Orange	country_id, currency

List of Supported Kenyan Banks

id	bank_name	niobi_bank_code
1	Kenya Commercial Bank	1
2	Standard Chartered	2
3	Absa Bank Kenya	3
4	Ncba Bank Kenya	7
5	Prime Bank	10
6	Cooperative Bank	11
7	National Bank of Kenya	12
8	Citibank N.A Kenya	16
9	Middle East Bank Kenya	18
10	Bank of Africa Kenya	19
11	Credit Bank Limited	25
12	CFC Stanbic Kenya	31
13	Paramount Bank	50
14	Jamii Bora Bank	51
15	Guaranty Trust Bank	53
16	Guardian Bank	55
17	I&M Bank	57
18	Diamond Trust Bank	63
19	Sidian Bank	66
20	Equity Bank Kenya	68
21	Family Bank Limited	70
22	Gulf African Bank	72
23	First Community Bank	74
24	Kenya Women’s Finance Trust	78

Body

application/json

Payload required for initiating a Niobi payment transaction.

client_id · string · required

The Client id is your public key which is generated when you are creating a new API integration from our app.

Example:

"K1PoY1WYricSpXh6Wm24twnk6ecPJOWrHGsqiKJr"

params · object · required

Show child attributes

salt · string · required

Salt is used for security purposes. This is a random string and can be unique value for each request or always the same.

Example:

"justrandomstring"

sender · string · required

The Sender is the title of the API Integration created through our app.

Example:

"John.co"

timestamp · integer · required

Timestamp of the request.

Example:

1709363033

signature · string · required

Signature for verifying the request.

Example:

"2193d01d50d4bd5da234ac0e0add5d4ccb40907a1b1ab27a12d2c1d88a5d5807"

Response

200

application/json

Payment process initiated successfully.

success · boolean

Example:

"true"

message · string

Example:

"Payment process initiated successfully."

data · object

Example:

""

res · object

Example:

""