cURL

curl -X POST "https://api.onekhusa.com/sandbox/v1/checkout/rtp/initiate" \
  --header "Content-Type: application/json" \
  --header "X-Idempotency-Key: your-idempotency-key" \
  -d '{
    "authentication": {
      "apiKey": "API_KEY",
      "apiSecret": "API_SECRET"
    },
    "merchant": {
    "organisationId": ORG123456789
     "merchantAccountNumber": 12345678
    },
    "payment": {
      "sourceReferenceNumber": "SRN123456789",
      "description": "GROCERIES PAYMENT",
      "amount": 450000.00
    },
    "route": {
      "successRedirectionUrl": "YOUR_APP_REDIRECTION_SUCCESS_PAGE_URL",
      "failureRedirectionUrl": "YOUR_APP_REDIRECTION_ERROR_PAGE_URL",
      "callbackApiUrl": "YOUR_WEBHOOK_PAYLOAD_ENDPOINT"
    }
  }'

import requests

url = "https://api.onekhusa.com/sandbox/v1/checkout/rtp/initiate"

payload = {
    "authentication": {
        "apiKey": "API_KEY",
        "apiSecret": "API_SECRET"
    },
    "merchant": {
        "organisationId": "ORG123456789",
        "merchantAccountNumber": 12345678
    },
    "payment": {
        "sourceReferenceNumber": "SRN123456789",
        "description": "GROCERIES PAYMENT",
        "amount": 450000
    },
    "route": {
        "successRedirectionUrl": "YOUR_APP_REDIRECTION_SUCCESS_PAGE_URL",
        "failureRedirectionUrl": "YOUR_APP_REDIRECTION_ERROR_PAGE_URL",
        "callbackApiUrl": "YOUR_WEBHOOK_PAYLOAD_ENDPOINT"
    }
}
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({
    authentication: {apiKey: 'API_KEY', apiSecret: 'API_SECRET'},
    merchant: {organisationId: 'ORG123456789', merchantAccountNumber: 12345678},
    payment: {
      sourceReferenceNumber: 'SRN123456789',
      description: 'GROCERIES PAYMENT',
      amount: 450000
    },
    route: {
      successRedirectionUrl: 'YOUR_APP_REDIRECTION_SUCCESS_PAGE_URL',
      failureRedirectionUrl: 'YOUR_APP_REDIRECTION_ERROR_PAGE_URL',
      callbackApiUrl: 'YOUR_WEBHOOK_PAYLOAD_ENDPOINT'
    }
  })
};

fetch('https://api.onekhusa.com/sandbox/v1/checkout/rtp/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/checkout/rtp/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([
    'authentication' => [
        'apiKey' => 'API_KEY',
        'apiSecret' => 'API_SECRET'
    ],
    'merchant' => [
        'organisationId' => 'ORG123456789',
        'merchantAccountNumber' => 12345678
    ],
    'payment' => [
        'sourceReferenceNumber' => 'SRN123456789',
        'description' => 'GROCERIES PAYMENT',
        'amount' => 450000
    ],
    'route' => [
        'successRedirectionUrl' => 'YOUR_APP_REDIRECTION_SUCCESS_PAGE_URL',
        'failureRedirectionUrl' => 'YOUR_APP_REDIRECTION_ERROR_PAGE_URL',
        'callbackApiUrl' => 'YOUR_WEBHOOK_PAYLOAD_ENDPOINT'
    ]
  ]),
  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/checkout/rtp/initiate"

	payload := strings.NewReader("{\n  \"authentication\": {\n    \"apiKey\": \"API_KEY\",\n    \"apiSecret\": \"API_SECRET\"\n  },\n  \"merchant\": {\n    \"organisationId\": \"ORG123456789\",\n    \"merchantAccountNumber\": 12345678\n  },\n  \"payment\": {\n    \"sourceReferenceNumber\": \"SRN123456789\",\n    \"description\": \"GROCERIES PAYMENT\",\n    \"amount\": 450000\n  },\n  \"route\": {\n    \"successRedirectionUrl\": \"YOUR_APP_REDIRECTION_SUCCESS_PAGE_URL\",\n    \"failureRedirectionUrl\": \"YOUR_APP_REDIRECTION_ERROR_PAGE_URL\",\n    \"callbackApiUrl\": \"YOUR_WEBHOOK_PAYLOAD_ENDPOINT\"\n  }\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/checkout/rtp/initiate")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"authentication\": {\n    \"apiKey\": \"API_KEY\",\n    \"apiSecret\": \"API_SECRET\"\n  },\n  \"merchant\": {\n    \"organisationId\": \"ORG123456789\",\n    \"merchantAccountNumber\": 12345678\n  },\n  \"payment\": {\n    \"sourceReferenceNumber\": \"SRN123456789\",\n    \"description\": \"GROCERIES PAYMENT\",\n    \"amount\": 450000\n  },\n  \"route\": {\n    \"successRedirectionUrl\": \"YOUR_APP_REDIRECTION_SUCCESS_PAGE_URL\",\n    \"failureRedirectionUrl\": \"YOUR_APP_REDIRECTION_ERROR_PAGE_URL\",\n    \"callbackApiUrl\": \"YOUR_WEBHOOK_PAYLOAD_ENDPOINT\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.onekhusa.com/sandbox/v1/checkout/rtp/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  \"authentication\": {\n    \"apiKey\": \"API_KEY\",\n    \"apiSecret\": \"API_SECRET\"\n  },\n  \"merchant\": {\n    \"organisationId\": \"ORG123456789\",\n    \"merchantAccountNumber\": 12345678\n  },\n  \"payment\": {\n    \"sourceReferenceNumber\": \"SRN123456789\",\n    \"description\": \"GROCERIES PAYMENT\",\n    \"amount\": 450000\n  },\n  \"route\": {\n    \"successRedirectionUrl\": \"YOUR_APP_REDIRECTION_SUCCESS_PAGE_URL\",\n    \"failureRedirectionUrl\": \"YOUR_APP_REDIRECTION_ERROR_PAGE_URL\",\n    \"callbackApiUrl\": \"YOUR_WEBHOOK_PAYLOAD_ENDPOINT\"\n  }\n}"

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

{
  "sourceReferenceNumber": "SRN123456789",
  "merchantAccountNumber": 12345678,
  "paymentTransactionId": "GENERATED_TRANSACTION_ID",
  "checkoutUrl": "GENERATED_CHECKOUT_URL"
}

Direct Transfer Payments

Direct Transfer Checkout

The Direct Transfer Checkout is a managed OneKhusa service that simplifies the checkout process for accepting payments to be made by third party systems supported by Direct Transfer API feature. In order to accept payments through the managed checkout page, the process is as follows:

Your system initiates a checkout payment request
On successful payment request, redirect to the hosted checkout page
Finalise the payment through bank account or mobile wallet
Update the payment status in your system through webhook notification
The checkout service redirects to your system to mark the process as successful

Let’s implement the checkout flow to start accepting payments from your customers:

Important: It is recommended to configure the Reversed Request To Pay webhook in case the OneKhusa payment gateway has received a payment reversal after the original transaction was successful so that your system should take an appropriate action.

1. Initiate Payment Request

This step allows your application initiates the payment request and waits for the successful response to redirect to OneKhusa hosted checkout service.

POST

checkout

rtp

initiate

cURL

curl -X POST "https://api.onekhusa.com/sandbox/v1/checkout/rtp/initiate" \
  --header "Content-Type: application/json" \
  --header "X-Idempotency-Key: your-idempotency-key" \
  -d '{
    "authentication": {
      "apiKey": "API_KEY",
      "apiSecret": "API_SECRET"
    },
    "merchant": {
    "organisationId": ORG123456789
     "merchantAccountNumber": 12345678
    },
    "payment": {
      "sourceReferenceNumber": "SRN123456789",
      "description": "GROCERIES PAYMENT",
      "amount": 450000.00
    },
    "route": {
      "successRedirectionUrl": "YOUR_APP_REDIRECTION_SUCCESS_PAGE_URL",
      "failureRedirectionUrl": "YOUR_APP_REDIRECTION_ERROR_PAGE_URL",
      "callbackApiUrl": "YOUR_WEBHOOK_PAYLOAD_ENDPOINT"
    }
  }'

import requests

url = "https://api.onekhusa.com/sandbox/v1/checkout/rtp/initiate"

payload = {
    "authentication": {
        "apiKey": "API_KEY",
        "apiSecret": "API_SECRET"
    },
    "merchant": {
        "organisationId": "ORG123456789",
        "merchantAccountNumber": 12345678
    },
    "payment": {
        "sourceReferenceNumber": "SRN123456789",
        "description": "GROCERIES PAYMENT",
        "amount": 450000
    },
    "route": {
        "successRedirectionUrl": "YOUR_APP_REDIRECTION_SUCCESS_PAGE_URL",
        "failureRedirectionUrl": "YOUR_APP_REDIRECTION_ERROR_PAGE_URL",
        "callbackApiUrl": "YOUR_WEBHOOK_PAYLOAD_ENDPOINT"
    }
}
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({
    authentication: {apiKey: 'API_KEY', apiSecret: 'API_SECRET'},
    merchant: {organisationId: 'ORG123456789', merchantAccountNumber: 12345678},
    payment: {
      sourceReferenceNumber: 'SRN123456789',
      description: 'GROCERIES PAYMENT',
      amount: 450000
    },
    route: {
      successRedirectionUrl: 'YOUR_APP_REDIRECTION_SUCCESS_PAGE_URL',
      failureRedirectionUrl: 'YOUR_APP_REDIRECTION_ERROR_PAGE_URL',
      callbackApiUrl: 'YOUR_WEBHOOK_PAYLOAD_ENDPOINT'
    }
  })
};

fetch('https://api.onekhusa.com/sandbox/v1/checkout/rtp/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/checkout/rtp/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([
    'authentication' => [
        'apiKey' => 'API_KEY',
        'apiSecret' => 'API_SECRET'
    ],
    'merchant' => [
        'organisationId' => 'ORG123456789',
        'merchantAccountNumber' => 12345678
    ],
    'payment' => [
        'sourceReferenceNumber' => 'SRN123456789',
        'description' => 'GROCERIES PAYMENT',
        'amount' => 450000
    ],
    'route' => [
        'successRedirectionUrl' => 'YOUR_APP_REDIRECTION_SUCCESS_PAGE_URL',
        'failureRedirectionUrl' => 'YOUR_APP_REDIRECTION_ERROR_PAGE_URL',
        'callbackApiUrl' => 'YOUR_WEBHOOK_PAYLOAD_ENDPOINT'
    ]
  ]),
  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/checkout/rtp/initiate"

	payload := strings.NewReader("{\n  \"authentication\": {\n    \"apiKey\": \"API_KEY\",\n    \"apiSecret\": \"API_SECRET\"\n  },\n  \"merchant\": {\n    \"organisationId\": \"ORG123456789\",\n    \"merchantAccountNumber\": 12345678\n  },\n  \"payment\": {\n    \"sourceReferenceNumber\": \"SRN123456789\",\n    \"description\": \"GROCERIES PAYMENT\",\n    \"amount\": 450000\n  },\n  \"route\": {\n    \"successRedirectionUrl\": \"YOUR_APP_REDIRECTION_SUCCESS_PAGE_URL\",\n    \"failureRedirectionUrl\": \"YOUR_APP_REDIRECTION_ERROR_PAGE_URL\",\n    \"callbackApiUrl\": \"YOUR_WEBHOOK_PAYLOAD_ENDPOINT\"\n  }\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/checkout/rtp/initiate")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"authentication\": {\n    \"apiKey\": \"API_KEY\",\n    \"apiSecret\": \"API_SECRET\"\n  },\n  \"merchant\": {\n    \"organisationId\": \"ORG123456789\",\n    \"merchantAccountNumber\": 12345678\n  },\n  \"payment\": {\n    \"sourceReferenceNumber\": \"SRN123456789\",\n    \"description\": \"GROCERIES PAYMENT\",\n    \"amount\": 450000\n  },\n  \"route\": {\n    \"successRedirectionUrl\": \"YOUR_APP_REDIRECTION_SUCCESS_PAGE_URL\",\n    \"failureRedirectionUrl\": \"YOUR_APP_REDIRECTION_ERROR_PAGE_URL\",\n    \"callbackApiUrl\": \"YOUR_WEBHOOK_PAYLOAD_ENDPOINT\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.onekhusa.com/sandbox/v1/checkout/rtp/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  \"authentication\": {\n    \"apiKey\": \"API_KEY\",\n    \"apiSecret\": \"API_SECRET\"\n  },\n  \"merchant\": {\n    \"organisationId\": \"ORG123456789\",\n    \"merchantAccountNumber\": 12345678\n  },\n  \"payment\": {\n    \"sourceReferenceNumber\": \"SRN123456789\",\n    \"description\": \"GROCERIES PAYMENT\",\n    \"amount\": 450000\n  },\n  \"route\": {\n    \"successRedirectionUrl\": \"YOUR_APP_REDIRECTION_SUCCESS_PAGE_URL\",\n    \"failureRedirectionUrl\": \"YOUR_APP_REDIRECTION_ERROR_PAGE_URL\",\n    \"callbackApiUrl\": \"YOUR_WEBHOOK_PAYLOAD_ENDPOINT\"\n  }\n}"

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

{
  "sourceReferenceNumber": "SRN123456789",
  "merchantAccountNumber": 12345678,
  "paymentTransactionId": "GENERATED_TRANSACTION_ID",
  "checkoutUrl": "GENERATED_CHECKOUT_URL"
}

2. Redirect To Checkout

Once your application receives a successfully initiated payment response, redirect it to the OneKhusa checkout page using the URL generated under the checkoutUrl property. Direct Transfer Checkout

Figure 1: Request To Pay Checkout Your initiated payment transaction will be displayed as illustrated in figure 1 above and follow the instructions to pay through the supported banks and mobile money wallets on OneKhusa. Once payment is successful and received, you will be redirected automatically to your application.

3. Simulate Checkout Payment

To simulate a payment made by a customer through managed checkout service, do either one of the following:

Login to merchant portal, navigate to Test Your Integration – Simulate Accept Direct Transfer Payment, then provide details from the checkout (TAN and Amount) and finalise the payment OR
Use Simulate Accept Direct Transfer Payment endpoint

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

X-Idempotency-Key

string

A unique key to ensure idempotent requests

Body

application/json

authentication

object

required

Show child attributes

merchant

object

required

Show child attributes

payment

object

required

Show child attributes

route

object

required

Show child attributes

Response

200 - application/json

Successful initiation of checkout request

sourceReferenceNumber

string

required

Unique reference number provided in the request.

Example:

"SRN123456789"

merchantAccountNumber

integer

required

Merchant account used for the transaction.

Example:

12345678

paymentTransactionId

string

required

Generated transaction ID used for redirecting to checkout.

Example:

"GENERATED_TRANSACTION_ID"

checkoutUrl

string

required

Generated hosted checkout URL used to redirect the customer to the payment page.

Example:

"GENERATED_CHECKOUT_URL"

Getting Started

Accept Payments

Disbursements

Bill Payments

Merchants

Security

Supporting APIs

Direct Transfer Checkout

1. Initiate Payment Request

2. Redirect To Checkout

3. Simulate Checkout Payment

Authorizations

Headers

Body

Response

​2. Redirect To Checkout

​3. Simulate Checkout Payment

Authorizations

Headers

Body

Response

2. Redirect To Checkout

3. Simulate Checkout Payment