Send a payment

curl --request POST \
  --url https://api-partner.onecluster.co/api/v1/payments/transfer \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: <x-idempotency-key>' \
  --header 'X-Signature: <x-signature>' \
  --data '
{
  "sourceAccount": "0123456789",
  "destinationAccount": "0987654321",
  "destinationBankCode": "058",
  "amount": 50000,
  "currency": "NGN",
  "narration": "Payment for invoice INV-2026-001",
  "senderBvn": "22211111111",
  "beneficiaryBvn": "22299999999",
  "senderKycLevel": "3",
  "beneficiaryKycLevel": "2",
  "nameEnquirySessionId": "NES-20260325-ABC123",
  "ftSessionId": "FT-20260325-XYZ789",
  "transactionLocation": "6.5244,3.3792",
  "channelCode": "API",
  "feeEntryMode": "LUMP_FEE_VAT"
}
'

import requests

url = "https://api-partner.onecluster.co/api/v1/payments/transfer"

payload = {
    "sourceAccount": "0123456789",
    "destinationAccount": "0987654321",
    "destinationBankCode": "058",
    "amount": 50000,
    "currency": "NGN",
    "narration": "Payment for invoice INV-2026-001",
    "senderBvn": "22211111111",
    "beneficiaryBvn": "22299999999",
    "senderKycLevel": "3",
    "beneficiaryKycLevel": "2",
    "nameEnquirySessionId": "NES-20260325-ABC123",
    "ftSessionId": "FT-20260325-XYZ789",
    "transactionLocation": "6.5244,3.3792",
    "channelCode": "API",
    "feeEntryMode": "LUMP_FEE_VAT"
}
headers = {
    "X-Idempotency-Key": "<x-idempotency-key>",
    "X-Signature": "<x-signature>",
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Idempotency-Key': '<x-idempotency-key>',
    'X-Signature': '<x-signature>',
    Authorization: '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    sourceAccount: '0123456789',
    destinationAccount: '0987654321',
    destinationBankCode: '058',
    amount: 50000,
    currency: 'NGN',
    narration: 'Payment for invoice INV-2026-001',
    senderBvn: '22211111111',
    beneficiaryBvn: '22299999999',
    senderKycLevel: '3',
    beneficiaryKycLevel: '2',
    nameEnquirySessionId: 'NES-20260325-ABC123',
    ftSessionId: 'FT-20260325-XYZ789',
    transactionLocation: '6.5244,3.3792',
    channelCode: 'API',
    feeEntryMode: 'LUMP_FEE_VAT'
  })
};

fetch('https://api-partner.onecluster.co/api/v1/payments/transfer', 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://api-partner.onecluster.co/api/v1/payments/transfer",
  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([
    'sourceAccount' => '0123456789',
    'destinationAccount' => '0987654321',
    'destinationBankCode' => '058',
    'amount' => 50000,
    'currency' => 'NGN',
    'narration' => 'Payment for invoice INV-2026-001',
    'senderBvn' => '22211111111',
    'beneficiaryBvn' => '22299999999',
    'senderKycLevel' => '3',
    'beneficiaryKycLevel' => '2',
    'nameEnquirySessionId' => 'NES-20260325-ABC123',
    'ftSessionId' => 'FT-20260325-XYZ789',
    'transactionLocation' => '6.5244,3.3792',
    'channelCode' => 'API',
    'feeEntryMode' => 'LUMP_FEE_VAT'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json",
    "X-Idempotency-Key: <x-idempotency-key>",
    "X-Signature: <x-signature>"
  ],
]);

$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://api-partner.onecluster.co/api/v1/payments/transfer"

	payload := strings.NewReader("{\n  \"sourceAccount\": \"0123456789\",\n  \"destinationAccount\": \"0987654321\",\n  \"destinationBankCode\": \"058\",\n  \"amount\": 50000,\n  \"currency\": \"NGN\",\n  \"narration\": \"Payment for invoice INV-2026-001\",\n  \"senderBvn\": \"22211111111\",\n  \"beneficiaryBvn\": \"22299999999\",\n  \"senderKycLevel\": \"3\",\n  \"beneficiaryKycLevel\": \"2\",\n  \"nameEnquirySessionId\": \"NES-20260325-ABC123\",\n  \"ftSessionId\": \"FT-20260325-XYZ789\",\n  \"transactionLocation\": \"6.5244,3.3792\",\n  \"channelCode\": \"API\",\n  \"feeEntryMode\": \"LUMP_FEE_VAT\"\n}")

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

	req.Header.Add("X-Idempotency-Key", "<x-idempotency-key>")
	req.Header.Add("X-Signature", "<x-signature>")
	req.Header.Add("Authorization", "<api-key>")
	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://api-partner.onecluster.co/api/v1/payments/transfer")
  .header("X-Idempotency-Key", "<x-idempotency-key>")
  .header("X-Signature", "<x-signature>")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"sourceAccount\": \"0123456789\",\n  \"destinationAccount\": \"0987654321\",\n  \"destinationBankCode\": \"058\",\n  \"amount\": 50000,\n  \"currency\": \"NGN\",\n  \"narration\": \"Payment for invoice INV-2026-001\",\n  \"senderBvn\": \"22211111111\",\n  \"beneficiaryBvn\": \"22299999999\",\n  \"senderKycLevel\": \"3\",\n  \"beneficiaryKycLevel\": \"2\",\n  \"nameEnquirySessionId\": \"NES-20260325-ABC123\",\n  \"ftSessionId\": \"FT-20260325-XYZ789\",\n  \"transactionLocation\": \"6.5244,3.3792\",\n  \"channelCode\": \"API\",\n  \"feeEntryMode\": \"LUMP_FEE_VAT\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-partner.onecluster.co/api/v1/payments/transfer")

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

request = Net::HTTP::Post.new(url)
request["X-Idempotency-Key"] = '<x-idempotency-key>'
request["X-Signature"] = '<x-signature>'
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"sourceAccount\": \"0123456789\",\n  \"destinationAccount\": \"0987654321\",\n  \"destinationBankCode\": \"058\",\n  \"amount\": 50000,\n  \"currency\": \"NGN\",\n  \"narration\": \"Payment for invoice INV-2026-001\",\n  \"senderBvn\": \"22211111111\",\n  \"beneficiaryBvn\": \"22299999999\",\n  \"senderKycLevel\": \"3\",\n  \"beneficiaryKycLevel\": \"2\",\n  \"nameEnquirySessionId\": \"NES-20260325-ABC123\",\n  \"ftSessionId\": \"FT-20260325-XYZ789\",\n  \"transactionLocation\": \"6.5244,3.3792\",\n  \"channelCode\": \"API\",\n  \"feeEntryMode\": \"LUMP_FEE_VAT\"\n}"

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

{
  "success": true,
  "responseCode": "00",
  "message": "Transfer accepted and queued for processing",
  "data": {
    "transactionRef": "TXN-20260325-001",
    "status": "PENDING",
    "estimatedCompletionTime": "2026-03-25T10:00:30+01:00"
  }
}

{
  "type": "https://api.onecluster.co/errors/insufficient-funds",
  "title": "Insufficient Funds",
  "status": 422,
  "detail": "The account balance is ₦0.00. You need at least ₦50,000.00 to complete this transfer.",
  "instance": "/api/v1/payments/transfer",
  "correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "code": "INSUFFICIENT_FUNDS"
}

{
  "type": "https://api.onecluster.co/errors/insufficient-funds",
  "title": "Insufficient Funds",
  "status": 422,
  "detail": "The account balance is ₦0.00. You need at least ₦50,000.00 to complete this transfer.",
  "instance": "/api/v1/payments/transfer",
  "correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "code": "INSUFFICIENT_FUNDS"
}

{
  "type": "https://api.onecluster.co/errors/insufficient-funds",
  "title": "Insufficient Funds",
  "status": 422,
  "detail": "The account balance is ₦0.00. You need at least ₦50,000.00 to complete this transfer.",
  "instance": "/api/v1/payments/transfer",
  "correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "code": "INSUFFICIENT_FUNDS"
}

{
  "type": "https://api.onecluster.co/errors/insufficient-funds",
  "title": "Insufficient Funds",
  "status": 422,
  "detail": "The account balance is ₦0.00. You need at least ₦50,000.00 to complete this transfer.",
  "instance": "/api/v1/payments/transfer",
  "correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "code": "INSUFFICIENT_FUNDS"
}

{
  "type": "https://api.onecluster.co/errors/insufficient-funds",
  "title": "Insufficient Funds",
  "status": 422,
  "detail": "The account balance is ₦0.00. You need at least ₦50,000.00 to complete this transfer.",
  "instance": "/api/v1/payments/transfer",
  "correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "code": "INSUFFICIENT_FUNDS"
}

Payments Endpoints

Initiate Transfer

Initiates a funds transfer from one of your virtual accounts to any Nigerian bank account.

Before calling this endpoint, you must:

Call /api/v1/payments/account-enquiry to validate the destination account and get a nameEnquirySessionId
Attach an mTLS client certificate (required for all payment operations)
Sign the request body with HMAC-SHA256 and include in X-Signature header

Transfer types:

NIP (NIP Instant Payment): Transfers to other banks. Near-instant (usually seconds). Requires BVN of both sender and recipient.
NEFT: For larger, non-time-sensitive transfers.

Fee modes control how charges appear on the statement:

LUMP_FEE_VAT (default): One entry for the principal, one for fees+VAT combined
LUMP_ALL: A single combined debit for everything
SPLIT_FEE_VAT: Three separate entries: principal, fees, and VAT

Transfers are processed asynchronously. This endpoint returns 202 Accepted - not 200 OK. Poll /api/v1/payments/{transactionRef}/status to get the final result.

Idempotency: Include a unique X-Idempotency-Key. If your network fails after sending but before receiving a response, resend with the same key, you will get the original result, not a duplicate transfer.

POST

api

payments

transfer

Send a payment

curl --request POST \
  --url https://api-partner.onecluster.co/api/v1/payments/transfer \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: <x-idempotency-key>' \
  --header 'X-Signature: <x-signature>' \
  --data '
{
  "sourceAccount": "0123456789",
  "destinationAccount": "0987654321",
  "destinationBankCode": "058",
  "amount": 50000,
  "currency": "NGN",
  "narration": "Payment for invoice INV-2026-001",
  "senderBvn": "22211111111",
  "beneficiaryBvn": "22299999999",
  "senderKycLevel": "3",
  "beneficiaryKycLevel": "2",
  "nameEnquirySessionId": "NES-20260325-ABC123",
  "ftSessionId": "FT-20260325-XYZ789",
  "transactionLocation": "6.5244,3.3792",
  "channelCode": "API",
  "feeEntryMode": "LUMP_FEE_VAT"
}
'

import requests

url = "https://api-partner.onecluster.co/api/v1/payments/transfer"

payload = {
    "sourceAccount": "0123456789",
    "destinationAccount": "0987654321",
    "destinationBankCode": "058",
    "amount": 50000,
    "currency": "NGN",
    "narration": "Payment for invoice INV-2026-001",
    "senderBvn": "22211111111",
    "beneficiaryBvn": "22299999999",
    "senderKycLevel": "3",
    "beneficiaryKycLevel": "2",
    "nameEnquirySessionId": "NES-20260325-ABC123",
    "ftSessionId": "FT-20260325-XYZ789",
    "transactionLocation": "6.5244,3.3792",
    "channelCode": "API",
    "feeEntryMode": "LUMP_FEE_VAT"
}
headers = {
    "X-Idempotency-Key": "<x-idempotency-key>",
    "X-Signature": "<x-signature>",
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Idempotency-Key': '<x-idempotency-key>',
    'X-Signature': '<x-signature>',
    Authorization: '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    sourceAccount: '0123456789',
    destinationAccount: '0987654321',
    destinationBankCode: '058',
    amount: 50000,
    currency: 'NGN',
    narration: 'Payment for invoice INV-2026-001',
    senderBvn: '22211111111',
    beneficiaryBvn: '22299999999',
    senderKycLevel: '3',
    beneficiaryKycLevel: '2',
    nameEnquirySessionId: 'NES-20260325-ABC123',
    ftSessionId: 'FT-20260325-XYZ789',
    transactionLocation: '6.5244,3.3792',
    channelCode: 'API',
    feeEntryMode: 'LUMP_FEE_VAT'
  })
};

fetch('https://api-partner.onecluster.co/api/v1/payments/transfer', 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://api-partner.onecluster.co/api/v1/payments/transfer",
  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([
    'sourceAccount' => '0123456789',
    'destinationAccount' => '0987654321',
    'destinationBankCode' => '058',
    'amount' => 50000,
    'currency' => 'NGN',
    'narration' => 'Payment for invoice INV-2026-001',
    'senderBvn' => '22211111111',
    'beneficiaryBvn' => '22299999999',
    'senderKycLevel' => '3',
    'beneficiaryKycLevel' => '2',
    'nameEnquirySessionId' => 'NES-20260325-ABC123',
    'ftSessionId' => 'FT-20260325-XYZ789',
    'transactionLocation' => '6.5244,3.3792',
    'channelCode' => 'API',
    'feeEntryMode' => 'LUMP_FEE_VAT'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json",
    "X-Idempotency-Key: <x-idempotency-key>",
    "X-Signature: <x-signature>"
  ],
]);

$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://api-partner.onecluster.co/api/v1/payments/transfer"

	payload := strings.NewReader("{\n  \"sourceAccount\": \"0123456789\",\n  \"destinationAccount\": \"0987654321\",\n  \"destinationBankCode\": \"058\",\n  \"amount\": 50000,\n  \"currency\": \"NGN\",\n  \"narration\": \"Payment for invoice INV-2026-001\",\n  \"senderBvn\": \"22211111111\",\n  \"beneficiaryBvn\": \"22299999999\",\n  \"senderKycLevel\": \"3\",\n  \"beneficiaryKycLevel\": \"2\",\n  \"nameEnquirySessionId\": \"NES-20260325-ABC123\",\n  \"ftSessionId\": \"FT-20260325-XYZ789\",\n  \"transactionLocation\": \"6.5244,3.3792\",\n  \"channelCode\": \"API\",\n  \"feeEntryMode\": \"LUMP_FEE_VAT\"\n}")

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

	req.Header.Add("X-Idempotency-Key", "<x-idempotency-key>")
	req.Header.Add("X-Signature", "<x-signature>")
	req.Header.Add("Authorization", "<api-key>")
	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://api-partner.onecluster.co/api/v1/payments/transfer")
  .header("X-Idempotency-Key", "<x-idempotency-key>")
  .header("X-Signature", "<x-signature>")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"sourceAccount\": \"0123456789\",\n  \"destinationAccount\": \"0987654321\",\n  \"destinationBankCode\": \"058\",\n  \"amount\": 50000,\n  \"currency\": \"NGN\",\n  \"narration\": \"Payment for invoice INV-2026-001\",\n  \"senderBvn\": \"22211111111\",\n  \"beneficiaryBvn\": \"22299999999\",\n  \"senderKycLevel\": \"3\",\n  \"beneficiaryKycLevel\": \"2\",\n  \"nameEnquirySessionId\": \"NES-20260325-ABC123\",\n  \"ftSessionId\": \"FT-20260325-XYZ789\",\n  \"transactionLocation\": \"6.5244,3.3792\",\n  \"channelCode\": \"API\",\n  \"feeEntryMode\": \"LUMP_FEE_VAT\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-partner.onecluster.co/api/v1/payments/transfer")

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

request = Net::HTTP::Post.new(url)
request["X-Idempotency-Key"] = '<x-idempotency-key>'
request["X-Signature"] = '<x-signature>'
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"sourceAccount\": \"0123456789\",\n  \"destinationAccount\": \"0987654321\",\n  \"destinationBankCode\": \"058\",\n  \"amount\": 50000,\n  \"currency\": \"NGN\",\n  \"narration\": \"Payment for invoice INV-2026-001\",\n  \"senderBvn\": \"22211111111\",\n  \"beneficiaryBvn\": \"22299999999\",\n  \"senderKycLevel\": \"3\",\n  \"beneficiaryKycLevel\": \"2\",\n  \"nameEnquirySessionId\": \"NES-20260325-ABC123\",\n  \"ftSessionId\": \"FT-20260325-XYZ789\",\n  \"transactionLocation\": \"6.5244,3.3792\",\n  \"channelCode\": \"API\",\n  \"feeEntryMode\": \"LUMP_FEE_VAT\"\n}"

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

{
  "success": true,
  "responseCode": "00",
  "message": "Transfer accepted and queued for processing",
  "data": {
    "transactionRef": "TXN-20260325-001",
    "status": "PENDING",
    "estimatedCompletionTime": "2026-03-25T10:00:30+01:00"
  }
}

{
  "type": "https://api.onecluster.co/errors/insufficient-funds",
  "title": "Insufficient Funds",
  "status": 422,
  "detail": "The account balance is ₦0.00. You need at least ₦50,000.00 to complete this transfer.",
  "instance": "/api/v1/payments/transfer",
  "correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "code": "INSUFFICIENT_FUNDS"
}

{
  "type": "https://api.onecluster.co/errors/insufficient-funds",
  "title": "Insufficient Funds",
  "status": 422,
  "detail": "The account balance is ₦0.00. You need at least ₦50,000.00 to complete this transfer.",
  "instance": "/api/v1/payments/transfer",
  "correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "code": "INSUFFICIENT_FUNDS"
}

{
  "type": "https://api.onecluster.co/errors/insufficient-funds",
  "title": "Insufficient Funds",
  "status": 422,
  "detail": "The account balance is ₦0.00. You need at least ₦50,000.00 to complete this transfer.",
  "instance": "/api/v1/payments/transfer",
  "correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "code": "INSUFFICIENT_FUNDS"
}

{
  "type": "https://api.onecluster.co/errors/insufficient-funds",
  "title": "Insufficient Funds",
  "status": 422,
  "detail": "The account balance is ₦0.00. You need at least ₦50,000.00 to complete this transfer.",
  "instance": "/api/v1/payments/transfer",
  "correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "code": "INSUFFICIENT_FUNDS"
}

{
  "type": "https://api.onecluster.co/errors/insufficient-funds",
  "title": "Insufficient Funds",
  "status": 422,
  "detail": "The account balance is ₦0.00. You need at least ₦50,000.00 to complete this transfer.",
  "instance": "/api/v1/payments/transfer",
  "correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "code": "INSUFFICIENT_FUNDS"
}

Authorizations

Authorization

string

header

required

Your API key, formatted as: ApiKey ubn_sb_your_key_here

Sandbox keys start with ubn_sb_
Production keys start with ubn_pk_
Never use production keys during testing, they will charge real money

Headers

X-Correlation-ID

string<uuid>

A UUID v4 you generate to trace this request through our systems. If you don't provide one, we generate it for you. Always include it in support requests, it helps us find your request in logs.

Example:

"7f3a9c21-4e8b-4a12-b6d1-3c8a7f2e1b09"

X-Idempotency-Key

string<uuid>

required

A UUID you generate. If you send the same request twice with the same key (within 24 hours), we return the original response, not a duplicate action. Generate a new UUID for every new operation.

Example:

"550e8400-e29b-41d4-a716-446655440000"

X-Signature

string

required

HMAC-SHA256 signature of the request body. Format: sha256=<hex-encoded-signature> See the Authentication guide for how to compute this.

Example:

"sha256=a3f4b2c1d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2"

Body

application/json

sourceAccount

string

required

The virtual account to debit (must belong to your partner account)

destinationAccount

string

required

The destination account number (any Nigerian bank)

destinationBankCode

string

required

3-digit CBN bank sort code (e.g. 058 for GTBank, 033 for UBA)

amount

number<double>

required

Amount in Naira (NGN)

Required range: x >= 0.01

Example:

50000

currency

string

default:NGN

required

Must be NGN

narration

string

required

Description that appears on the recipient's bank statement

Maximum string length: 100

Example:

"Payment for invoice INV-2026-001"

nameEnquirySessionId

string

required

The session ID from the /account-enquiry call. Required.

ftSessionId

string

required

Funds Transfer session ID (provided by your UBN relationship manager)

transactionLocation

string

required

GPS coordinates of the transaction origin. Required for NIP transfers. Format, latitude,longitude

Example:

"6.5244,3.3792"

channelCode

string

required

The originating channel. Use API for programmatic transfers.

Example:

"API"

senderBvn

string

Sender's BVN. Required for inter-bank (NIP) transfers.

beneficiaryBvn

string

Recipient's BVN. Required for inter-bank (NIP) transfers.

senderKycLevel

string

CBN KYC level of the sender (1, 2, or 3)

beneficiaryKycLevel

string

CBN KYC level of the recipient (1, 2, or 3)

feeEntryMode

enum<string>

default:LUMP_FEE_VAT

How transfer fees appear on the statement:

LUMP_ALL: One combined debit for principal + fees + VAT
LUMP_FEE_VAT (default): Two debits, principal, then fees+VAT combined
SPLIT_FEE_VAT: Three debits, principal, fees, and VAT separately

Available options:

LUMP_ALL,

LUMP_FEE_VAT,

SPLIT_FEE_VAT

Response

Transfer accepted, poll the status endpoint to get the final result

Standard response wrapper for all successful API calls

success

boolean

required

Always true for successful responses

Example:

true

responseCode

string

required

00 means success

Example:

"00"

message

string

required

Human-readable description of the result

Example:

"Request processed successfully"

data

object

required

The actual response data (varies by endpoint)

Account Enquiry Get Payment Status

API Reference

Health & Status

Accounts Endpoints

Payments Endpoints

Collections Endpoints

Billing Endpoints

KYC Endpoints

Initiate Transfer

Authorizations

Headers

Body

Response