POST
/
disbursements
/
single
/
inter
/
add
Initiate Inter-Organisation Transfer
curl --request POST \
  --url https://api.onekhusa.com/sandbox/v1/disbursements/single/inter/add \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "merchantAccountNumber": 52333818,
  "transactionAmount": 25000,
  "transactionDescription": "Payment to partner merchant",
  "beneficiaryName": "Partner Merchant Ltd",
  "beneficiaryAccountNumber": "58931443",
  "sourceReferenceNumber": "INV-20260703",
  "capturedBy": "user@onekhusa.com"
}
'
{
  "merchantAccountNumber": 52333818,
  "responseCode": "S100",
  "transactionReferenceNumber": "260703X9Y8Z7",
  "collectionTransactionReferenceNumber": "260703X9Y8Z7",
  "beneficiaryMerchantAccountNumber": 58931443
}
Business-to-Business Payments: This endpoint facilitates secure payments between OneKhusa merchants in different organisations. For transfers within the same organisation, use the Intra-Organisation Transfer endpoint instead.

ā€‹
Validation Rules

  • Beneficiary must belong to a different organisation than the sender
  • Sender and beneficiary currencies must match
  • Sender must have sufficient balance (amount + fees)
  • Both accounts must be active
  • Cannot transfer to self

ā€‹
Workflow Behaviour

Auth LevelBehaviour
Level 1 (Initiator Only)Transaction is created and funds are transferred immediately
Level 2+ (Initiator + Approver)Transaction is created in a pending state and requires approval

Authorizations

ā€‹
Authorization
string
header
required

Bearer authentication header of the form Bearer Token, Where accessToken is the access token used to authenticate the request.

Headers

ā€‹
Accept-Language
string
default:en

Preferred language for the response

ā€‹
X-Idempotency-Key
string

A unique key to ensure idempotent requests

Body

application/json
ā€‹
merchantAccountNumber
integer
required

Sender's 8-digit merchant account number

Required range: 10000000 <= x <= 99999999
Example:

52333818

ā€‹
transactionAmount
number<double>
required

Amount to transfer (must be greater than 0)

Example:

25000

ā€‹
transactionDescription
string
required

Purpose of transfer (5-99 characters)

Required string length: 5 - 99
Example:

"Payment to partner merchant"

ā€‹
beneficiaryName
string
required

Beneficiary name (3-99 characters)

Required string length: 3 - 99
Example:

"Partner Merchant Ltd"

ā€‹
beneficiaryAccountNumber
string
required

8-digit beneficiary merchant account number

Example:

"58931443"

ā€‹
capturedBy
string<email>
required

Email of the initiating user

Example:

"user@onekhusa.com"

ā€‹
sourceReferenceNumber
string

Merchant reference number (max 12 characters)

Maximum string length: 12
Example:

"INV-20260703"

Response

200 - application/json

Success - Inter-organisation transfer initiated

ā€‹
merchantAccountNumber
integer
Example:

52333818

ā€‹
responseCode
string
Example:

"S100"

ā€‹
transactionReferenceNumber
string
Example:

"260703X9Y8Z7"

ā€‹
collectionTransactionReferenceNumber
string
Example:

"260703X9Y8Z7"

ā€‹
beneficiaryMerchantAccountNumber
integer
Example:

58931443