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"
}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-enquiryto validate the destination account and get anameEnquirySessionId - Attach an mTLS client certificate (required for all payment operations)
- Sign the request body with HMAC-SHA256 and include in
X-Signatureheader
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 combinedLUMP_ALL: A single combined debit for everythingSPLIT_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.
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
Headers
HMAC-SHA256 signature of the request body.
Format: sha256=<hex-encoded-signature>
See the Authentication guide for how to compute this.
"sha256=a3f4b2c1d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2"
Body
How transfer fees appear on the statement:
LUMP_ALL: One combined debit for principal + fees + VATLUMP_FEE_VAT(default): Two debits, principal, then fees+VAT combinedSPLIT_FEE_VAT: Three debits, principal, fees, and VAT separately
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

