curl -X POST "https://api.onekhusa.com/sandbox/v1/collections/requestToPay/initiate" \
--header "Authorization: Bearer your-jwt-token" \
--header "Content-Type: application/json" \
--header "Accept-Language: en" \
--header "X-Idempotency-Key: your-idempotency-key" \
-d '{
"merchantAccountNumber": 12345678,
"transactionAmount": 8375000.00,
"transactionDescription": "Samsung 85inch TV purchase",
"referenceNumber": "1020XDFS76GS777",
"capturedBy": "username@onekhusa.com"
}'import requests
url = "https://api.onekhusa.com/sandbox/v1/collections/requestToPay/initiate"
payload = {
"merchantAccountNumber": 12345678,
"transactionAmount": 8375000,
"transactionDescription": "Samsung 85inch TV purchase",
"referenceNumber": "1020XDFS76GS777",
"capturedBy": "username@onekhusa.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: 12345678,
transactionAmount: 8375000,
transactionDescription: 'Samsung 85inch TV purchase',
referenceNumber: '1020XDFS76GS777',
capturedBy: 'username@onekhusa.com'
})
};
fetch('https://api.onekhusa.com/sandbox/v1/collections/requestToPay/initiate', 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.onekhusa.com/sandbox/v1/collections/requestToPay/initiate",
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' => 12345678,
'transactionAmount' => 8375000,
'transactionDescription' => 'Samsung 85inch TV purchase',
'referenceNumber' => '1020XDFS76GS777',
'capturedBy' => 'username@onekhusa.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://api.onekhusa.com/sandbox/v1/collections/requestToPay/initiate"
payload := strings.NewReader("{\n \"merchantAccountNumber\": 12345678,\n \"transactionAmount\": 8375000,\n \"transactionDescription\": \"Samsung 85inch TV purchase\",\n \"referenceNumber\": \"1020XDFS76GS777\",\n \"capturedBy\": \"username@onekhusa.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://api.onekhusa.com/sandbox/v1/collections/requestToPay/initiate")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"merchantAccountNumber\": 12345678,\n \"transactionAmount\": 8375000,\n \"transactionDescription\": \"Samsung 85inch TV purchase\",\n \"referenceNumber\": \"1020XDFS76GS777\",\n \"capturedBy\": \"username@onekhusa.com\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.onekhusa.com/sandbox/v1/collections/requestToPay/initiate")
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\": 12345678,\n \"transactionAmount\": 8375000,\n \"transactionDescription\": \"Samsung 85inch TV purchase\",\n \"referenceNumber\": \"1020XDFS76GS777\",\n \"capturedBy\": \"username@onekhusa.com\"\n}"
response = http.request(request)
puts response.read_body{
"merchantAccountNumber": 12345678,
"timedAccountNumber": "11005533",
"expiryDate": "2026-01-05T10:01:56.412Z",
"expiryInMinutes": 15
}Direct Transfer API
This feature enables the merchants to associate the transactions initiated/originated from their systems by their customers to pay for the purchased goods, subscribed services through either bank or MNO channel for example, e-commence shop, school fees payments, driving license renewal, passport renewal etc.
Important Actions
-
Your merchant system is required to subscribe to webhook events namely
payrequest.successandpayrequest.reversedto get notified once the customer transaction is received or reserved in OneKhusa platform. -
If you are using sandbox, to test the receiving of a transaction from the customer to trigger the webhook event,
payrequest.success, use this Simulate Accept Direct Transfer Payment endpoint.
curl -X POST "https://api.onekhusa.com/sandbox/v1/collections/requestToPay/initiate" \
--header "Authorization: Bearer your-jwt-token" \
--header "Content-Type: application/json" \
--header "Accept-Language: en" \
--header "X-Idempotency-Key: your-idempotency-key" \
-d '{
"merchantAccountNumber": 12345678,
"transactionAmount": 8375000.00,
"transactionDescription": "Samsung 85inch TV purchase",
"referenceNumber": "1020XDFS76GS777",
"capturedBy": "username@onekhusa.com"
}'import requests
url = "https://api.onekhusa.com/sandbox/v1/collections/requestToPay/initiate"
payload = {
"merchantAccountNumber": 12345678,
"transactionAmount": 8375000,
"transactionDescription": "Samsung 85inch TV purchase",
"referenceNumber": "1020XDFS76GS777",
"capturedBy": "username@onekhusa.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: 12345678,
transactionAmount: 8375000,
transactionDescription: 'Samsung 85inch TV purchase',
referenceNumber: '1020XDFS76GS777',
capturedBy: 'username@onekhusa.com'
})
};
fetch('https://api.onekhusa.com/sandbox/v1/collections/requestToPay/initiate', 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.onekhusa.com/sandbox/v1/collections/requestToPay/initiate",
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' => 12345678,
'transactionAmount' => 8375000,
'transactionDescription' => 'Samsung 85inch TV purchase',
'referenceNumber' => '1020XDFS76GS777',
'capturedBy' => 'username@onekhusa.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://api.onekhusa.com/sandbox/v1/collections/requestToPay/initiate"
payload := strings.NewReader("{\n \"merchantAccountNumber\": 12345678,\n \"transactionAmount\": 8375000,\n \"transactionDescription\": \"Samsung 85inch TV purchase\",\n \"referenceNumber\": \"1020XDFS76GS777\",\n \"capturedBy\": \"username@onekhusa.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://api.onekhusa.com/sandbox/v1/collections/requestToPay/initiate")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"merchantAccountNumber\": 12345678,\n \"transactionAmount\": 8375000,\n \"transactionDescription\": \"Samsung 85inch TV purchase\",\n \"referenceNumber\": \"1020XDFS76GS777\",\n \"capturedBy\": \"username@onekhusa.com\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.onekhusa.com/sandbox/v1/collections/requestToPay/initiate")
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\": 12345678,\n \"transactionAmount\": 8375000,\n \"transactionDescription\": \"Samsung 85inch TV purchase\",\n \"referenceNumber\": \"1020XDFS76GS777\",\n \"capturedBy\": \"username@onekhusa.com\"\n}"
response = http.request(request)
puts response.read_body{
"merchantAccountNumber": 12345678,
"timedAccountNumber": "11005533",
"expiryDate": "2026-01-05T10:01:56.412Z",
"expiryInMinutes": 15
}Authorizations
Bearer authentication header of the form Bearer Token, Where accessToken is the access token used to authenticate the request.
Body
An active account number for the merchant registered on OneKhusa for accepting payments.
12345678
The total transaction (checkout) amount the customer is supposed to pay, and this is created by the merchant system.
8375000
The description generated by the merchant system for the service/product(s) purchased by the customer.
"Samsung 85inch TV purchase"
The unique reference number generated by the merchant system to easily identify and reconcile a request-to-pay transaction through webhook. The allowed alpha-numeric characters is a range of 5 to 25.
5 - 25"1020XDFS76GS777"
The background user registered under the merchant account being used, initiated on behalf of a customer.
"username@onekhusa.com"
Response
Success Response (200)
An account number for the merchant used for initiating a request-to-pay transaction.
12345678
A random and unique temporary (short-lived) account number tied to an initiated request-to-pay transaction. This account number will always start with "1".
"11005533"
The time assigned to TAN to expire.
"2026-01-05T10:01:56.412Z"
Number of minutes TAN will expire after creation.
15