Skip to main content
POST
/
api
/
v1
/
payments
/
transfer
Send a payment
curl --request POST \
  --url https://dev-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"
}
'
{
  "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"
  }
}

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)