Initiate Transfers Within OneKhusa Organisation

Initiate Inter-Organisation Transfer

curl --request POST \
  --url https://dev.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@example.com"
}
'

import requests

url = "https://dev.api.onekhusa.com/sandbox/v1/disbursements/single/inter/add"

payload = {
    "merchantAccountNumber": 52333818,
    "transactionAmount": 25000,
    "transactionDescription": "Payment to partner merchant",
    "beneficiaryName": "Partner Merchant Ltd",
    "beneficiaryAccountNumber": "58931443",
    "sourceReferenceNumber": "INV-20260703",
    "capturedBy": "user@example.com"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    merchantAccountNumber: 52333818,
    transactionAmount: 25000,
    transactionDescription: 'Payment to partner merchant',
    beneficiaryName: 'Partner Merchant Ltd',
    beneficiaryAccountNumber: '58931443',
    sourceReferenceNumber: 'INV-20260703',
    capturedBy: 'user@example.com'
  })
};

fetch('https://dev.api.onekhusa.com/sandbox/v1/disbursements/single/inter/add', 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://dev.api.onekhusa.com/sandbox/v1/disbursements/single/inter/add",
  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([
    'merchantAccountNumber' => 52333818,
    'transactionAmount' => 25000,
    'transactionDescription' => 'Payment to partner merchant',
    'beneficiaryName' => 'Partner Merchant Ltd',
    'beneficiaryAccountNumber' => '58931443',
    'sourceReferenceNumber' => 'INV-20260703',
    'capturedBy' => 'user@example.com'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "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://dev.api.onekhusa.com/sandbox/v1/disbursements/single/inter/add"

	payload := strings.NewReader("{\n  \"merchantAccountNumber\": 52333818,\n  \"transactionAmount\": 25000,\n  \"transactionDescription\": \"Payment to partner merchant\",\n  \"beneficiaryName\": \"Partner Merchant Ltd\",\n  \"beneficiaryAccountNumber\": \"58931443\",\n  \"sourceReferenceNumber\": \"INV-20260703\",\n  \"capturedBy\": \"user@example.com\"\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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://dev.api.onekhusa.com/sandbox/v1/disbursements/single/inter/add")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"merchantAccountNumber\": 52333818,\n  \"transactionAmount\": 25000,\n  \"transactionDescription\": \"Payment to partner merchant\",\n  \"beneficiaryName\": \"Partner Merchant Ltd\",\n  \"beneficiaryAccountNumber\": \"58931443\",\n  \"sourceReferenceNumber\": \"INV-20260703\",\n  \"capturedBy\": \"user@example.com\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://dev.api.onekhusa.com/sandbox/v1/disbursements/single/inter/add")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"merchantAccountNumber\": 52333818,\n  \"transactionAmount\": 25000,\n  \"transactionDescription\": \"Payment to partner merchant\",\n  \"beneficiaryName\": \"Partner Merchant Ltd\",\n  \"beneficiaryAccountNumber\": \"58931443\",\n  \"sourceReferenceNumber\": \"INV-20260703\",\n  \"capturedBy\": \"user@example.com\"\n}"

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

{
  "merchantAccountNumber": 52333818,
  "responseCode": "S100",
  "transactionReferenceNumber": "260703X9Y8Z7",
  "collectionTransactionReferenceNumber": "260703X9Y8Z7",
  "beneficiaryMerchantAccountNumber": 58931443
}

POST

disbursements

single

inter

add

Initiate Inter-Organisation Transfer

curl --request POST \
  --url https://dev.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@example.com"
}
'

import requests

url = "https://dev.api.onekhusa.com/sandbox/v1/disbursements/single/inter/add"

payload = {
    "merchantAccountNumber": 52333818,
    "transactionAmount": 25000,
    "transactionDescription": "Payment to partner merchant",
    "beneficiaryName": "Partner Merchant Ltd",
    "beneficiaryAccountNumber": "58931443",
    "sourceReferenceNumber": "INV-20260703",
    "capturedBy": "user@example.com"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    merchantAccountNumber: 52333818,
    transactionAmount: 25000,
    transactionDescription: 'Payment to partner merchant',
    beneficiaryName: 'Partner Merchant Ltd',
    beneficiaryAccountNumber: '58931443',
    sourceReferenceNumber: 'INV-20260703',
    capturedBy: 'user@example.com'
  })
};

fetch('https://dev.api.onekhusa.com/sandbox/v1/disbursements/single/inter/add', 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://dev.api.onekhusa.com/sandbox/v1/disbursements/single/inter/add",
  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([
    'merchantAccountNumber' => 52333818,
    'transactionAmount' => 25000,
    'transactionDescription' => 'Payment to partner merchant',
    'beneficiaryName' => 'Partner Merchant Ltd',
    'beneficiaryAccountNumber' => '58931443',
    'sourceReferenceNumber' => 'INV-20260703',
    'capturedBy' => 'user@example.com'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "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://dev.api.onekhusa.com/sandbox/v1/disbursements/single/inter/add"

	payload := strings.NewReader("{\n  \"merchantAccountNumber\": 52333818,\n  \"transactionAmount\": 25000,\n  \"transactionDescription\": \"Payment to partner merchant\",\n  \"beneficiaryName\": \"Partner Merchant Ltd\",\n  \"beneficiaryAccountNumber\": \"58931443\",\n  \"sourceReferenceNumber\": \"INV-20260703\",\n  \"capturedBy\": \"user@example.com\"\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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://dev.api.onekhusa.com/sandbox/v1/disbursements/single/inter/add")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"merchantAccountNumber\": 52333818,\n  \"transactionAmount\": 25000,\n  \"transactionDescription\": \"Payment to partner merchant\",\n  \"beneficiaryName\": \"Partner Merchant Ltd\",\n  \"beneficiaryAccountNumber\": \"58931443\",\n  \"sourceReferenceNumber\": \"INV-20260703\",\n  \"capturedBy\": \"user@example.com\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://dev.api.onekhusa.com/sandbox/v1/disbursements/single/inter/add")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"merchantAccountNumber\": 52333818,\n  \"transactionAmount\": 25000,\n  \"transactionDescription\": \"Payment to partner merchant\",\n  \"beneficiaryName\": \"Partner Merchant Ltd\",\n  \"beneficiaryAccountNumber\": \"58931443\",\n  \"sourceReferenceNumber\": \"INV-20260703\",\n  \"capturedBy\": \"user@example.com\"\n}"

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

{
  "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 Level	Behaviour
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@example.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

Getting Started

Accept Payments

Disbursements

Bill Payments

Merchants

Disputes

Security

Supporting APIs

Initiate Transfers Within OneKhusa Organisation

Validation Rules

Workflow Behaviour

Authorizations

Headers

Body

Response

​Validation Rules

​Workflow Behaviour

Authorizations

Headers

Body

Response

Validation Rules

Workflow Behaviour