Initiate Transfers Between OneKhusa Organisations

Initiate Intra-Organisation Transfer

curl --request POST \
  --url https://dev.api.onekhusa.com/sandbox/v1/disbursements/single/intra/add \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "merchantAccountNumber": 52333818,
  "transactionAmount": 15000,
  "transactionDescription": "Branch fund allocation",
  "beneficiaryName": "Branch Operations",
  "beneficiaryAccountNumber": "52333819",
  "sourceReferenceNumber": "BRA-001",
  "capturedBy": "user@example.com"
}
'

import requests

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

payload = {
    "merchantAccountNumber": 52333818,
    "transactionAmount": 15000,
    "transactionDescription": "Branch fund allocation",
    "beneficiaryName": "Branch Operations",
    "beneficiaryAccountNumber": "52333819",
    "sourceReferenceNumber": "BRA-001",
    "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: 15000,
    transactionDescription: 'Branch fund allocation',
    beneficiaryName: 'Branch Operations',
    beneficiaryAccountNumber: '52333819',
    sourceReferenceNumber: 'BRA-001',
    capturedBy: 'user@example.com'
  })
};

fetch('https://dev.api.onekhusa.com/sandbox/v1/disbursements/single/intra/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/intra/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' => 15000,
    'transactionDescription' => 'Branch fund allocation',
    'beneficiaryName' => 'Branch Operations',
    'beneficiaryAccountNumber' => '52333819',
    'sourceReferenceNumber' => 'BRA-001',
    '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/intra/add"

	payload := strings.NewReader("{\n  \"merchantAccountNumber\": 52333818,\n  \"transactionAmount\": 15000,\n  \"transactionDescription\": \"Branch fund allocation\",\n  \"beneficiaryName\": \"Branch Operations\",\n  \"beneficiaryAccountNumber\": \"52333819\",\n  \"sourceReferenceNumber\": \"BRA-001\",\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/intra/add")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"merchantAccountNumber\": 52333818,\n  \"transactionAmount\": 15000,\n  \"transactionDescription\": \"Branch fund allocation\",\n  \"beneficiaryName\": \"Branch Operations\",\n  \"beneficiaryAccountNumber\": \"52333819\",\n  \"sourceReferenceNumber\": \"BRA-001\",\n  \"capturedBy\": \"user@example.com\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://dev.api.onekhusa.com/sandbox/v1/disbursements/single/intra/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\": 15000,\n  \"transactionDescription\": \"Branch fund allocation\",\n  \"beneficiaryName\": \"Branch Operations\",\n  \"beneficiaryAccountNumber\": \"52333819\",\n  \"sourceReferenceNumber\": \"BRA-001\",\n  \"capturedBy\": \"user@example.com\"\n}"

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

{
  "merchantAccountNumber": 52333818,
  "responseCode": "S100",
  "transactionReferenceNumber": "260703A1B2C3",
  "collectionTransactionReferenceNumber": "260703A1B2C3",
  "beneficiaryMerchantAccountNumber": 52333819
}

POST

disbursements

single

intra

add

Initiate Intra-Organisation Transfer

curl --request POST \
  --url https://dev.api.onekhusa.com/sandbox/v1/disbursements/single/intra/add \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "merchantAccountNumber": 52333818,
  "transactionAmount": 15000,
  "transactionDescription": "Branch fund allocation",
  "beneficiaryName": "Branch Operations",
  "beneficiaryAccountNumber": "52333819",
  "sourceReferenceNumber": "BRA-001",
  "capturedBy": "user@example.com"
}
'

import requests

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

payload = {
    "merchantAccountNumber": 52333818,
    "transactionAmount": 15000,
    "transactionDescription": "Branch fund allocation",
    "beneficiaryName": "Branch Operations",
    "beneficiaryAccountNumber": "52333819",
    "sourceReferenceNumber": "BRA-001",
    "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: 15000,
    transactionDescription: 'Branch fund allocation',
    beneficiaryName: 'Branch Operations',
    beneficiaryAccountNumber: '52333819',
    sourceReferenceNumber: 'BRA-001',
    capturedBy: 'user@example.com'
  })
};

fetch('https://dev.api.onekhusa.com/sandbox/v1/disbursements/single/intra/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/intra/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' => 15000,
    'transactionDescription' => 'Branch fund allocation',
    'beneficiaryName' => 'Branch Operations',
    'beneficiaryAccountNumber' => '52333819',
    'sourceReferenceNumber' => 'BRA-001',
    '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/intra/add"

	payload := strings.NewReader("{\n  \"merchantAccountNumber\": 52333818,\n  \"transactionAmount\": 15000,\n  \"transactionDescription\": \"Branch fund allocation\",\n  \"beneficiaryName\": \"Branch Operations\",\n  \"beneficiaryAccountNumber\": \"52333819\",\n  \"sourceReferenceNumber\": \"BRA-001\",\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/intra/add")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"merchantAccountNumber\": 52333818,\n  \"transactionAmount\": 15000,\n  \"transactionDescription\": \"Branch fund allocation\",\n  \"beneficiaryName\": \"Branch Operations\",\n  \"beneficiaryAccountNumber\": \"52333819\",\n  \"sourceReferenceNumber\": \"BRA-001\",\n  \"capturedBy\": \"user@example.com\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://dev.api.onekhusa.com/sandbox/v1/disbursements/single/intra/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\": 15000,\n  \"transactionDescription\": \"Branch fund allocation\",\n  \"beneficiaryName\": \"Branch Operations\",\n  \"beneficiaryAccountNumber\": \"52333819\",\n  \"sourceReferenceNumber\": \"BRA-001\",\n  \"capturedBy\": \"user@example.com\"\n}"

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

{
  "merchantAccountNumber": 52333818,
  "responseCode": "S100",
  "transactionReferenceNumber": "260703A1B2C3",
  "collectionTransactionReferenceNumber": "260703A1B2C3",
  "beneficiaryMerchantAccountNumber": 52333819
}

Internal Transfers: Use this endpoint for fund reallocation between departments, branches, or accounts under the same organisation. For transfers to merchants in a different organisation, use the Inter-Organisation Transfer endpoint.

Validation Rules

Beneficiary must be in the same organisation
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:

15000

transactionDescription

string

required

Purpose of transfer (5-99 characters)

Required string length: 5 - 99

Example:

"Branch fund allocation"

beneficiaryName

string

required

Beneficiary name (3-99 characters)

Required string length: 3 - 99

Example:

"Branch Operations"

beneficiaryAccountNumber

string

required

8-digit beneficiary merchant account number

Example:

"52333819"

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:

"BRA-001"

Response

200 - application/json

Success - Intra-organisation transfer initiated

merchantAccountNumber

integer

Example:

52333818

responseCode

string

Example:

"S100"

transactionReferenceNumber

string

Example:

"260703A1B2C3"

collectionTransactionReferenceNumber

string

Example:

"260703A1B2C3"

beneficiaryMerchantAccountNumber

integer

Example:

52333819

Getting Started

Accept Payments

Disbursements

Bill Payments

Merchants

Disputes

Security

Supporting APIs

Initiate Transfers Between OneKhusa Organisations

Validation Rules

Workflow Behaviour

Authorizations

Headers

Body

Response

​Validation Rules

​Workflow Behaviour

Authorizations

Headers

Body

Response

Validation Rules

Workflow Behaviour