Standard Checkout

cURL

curl -X POST "https://api.onekhusa.com/sandbox/v1/checkout/push/initiate" \
  --header "Authorization: Bearer your-jwt-token" \
  --header "Content-Type: application/json" \
  --header "Accept-Language: en" \
  --header "X-Idempotency-Key: your-idempotency-key" \
  -d '{
    "payment": {
      "merchantAccountNumber": 58931443,
      "amount": 150.00,
      "description": "Groceries purchase",
      "sourceReferenceNumber": "DR48JS93G3F",
      "capturedBy": "username@onekhusa.com"
    },
    "route": {
      "successRedirectionUrl": "YOUR_APP_REDIRECTION_SUCCESS_PAGE_URL",
      "failureRedirectionUrl": "YOUR_APP_REDIRECTION_ERROR_PAGE_URL"
    }
  }'

import requests

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

payload = {
    "payment": {
        "merchantAccountNumber": 58931443,
        "amount": 150,
        "description": "Payment for Order #10234",
        "sourceReferenceNumber": "{{$guid}}",
        "capturedBy": "username@onekhusa.com"
    },
    "route": {
        "successRedirectionUrl": "YOUR_APP_REDIRECTION_SUCCESS_PAGE_URL",
        "failureRedirectionUrl": "YOUR_APP_REDIRECTION_ERROR_PAGE_URL"
    }
}
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({
    payment: {
      merchantAccountNumber: 58931443,
      amount: 150,
      description: 'Payment for Order #10234',
      sourceReferenceNumber: '{{$guid}}',
      capturedBy: 'username@onekhusa.com'
    },
    route: {
      successRedirectionUrl: 'YOUR_APP_REDIRECTION_SUCCESS_PAGE_URL',
      failureRedirectionUrl: 'YOUR_APP_REDIRECTION_ERROR_PAGE_URL'
    }
  })
};

fetch('https://api.onekhusa.com/sandbox/v1/checkout/push/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/push/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([
    'payment' => [
        'merchantAccountNumber' => 58931443,
        'amount' => 150,
        'description' => 'Payment for Order #10234',
        'sourceReferenceNumber' => '{{$guid}}',
        'capturedBy' => 'username@onekhusa.com'
    ],
    'route' => [
        'successRedirectionUrl' => 'YOUR_APP_REDIRECTION_SUCCESS_PAGE_URL',
        'failureRedirectionUrl' => 'YOUR_APP_REDIRECTION_ERROR_PAGE_URL'
    ]
  ]),
  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/push/initiate"

	payload := strings.NewReader("{\n  \"payment\": {\n    \"merchantAccountNumber\": 58931443,\n    \"amount\": 150,\n    \"description\": \"Payment for Order #10234\",\n    \"sourceReferenceNumber\": \"{{$guid}}\",\n    \"capturedBy\": \"username@onekhusa.com\"\n  },\n  \"route\": {\n    \"successRedirectionUrl\": \"YOUR_APP_REDIRECTION_SUCCESS_PAGE_URL\",\n    \"failureRedirectionUrl\": \"YOUR_APP_REDIRECTION_ERROR_PAGE_URL\"\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/push/initiate")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"payment\": {\n    \"merchantAccountNumber\": 58931443,\n    \"amount\": 150,\n    \"description\": \"Payment for Order #10234\",\n    \"sourceReferenceNumber\": \"{{$guid}}\",\n    \"capturedBy\": \"username@onekhusa.com\"\n  },\n  \"route\": {\n    \"successRedirectionUrl\": \"YOUR_APP_REDIRECTION_SUCCESS_PAGE_URL\",\n    \"failureRedirectionUrl\": \"YOUR_APP_REDIRECTION_ERROR_PAGE_URL\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.onekhusa.com/sandbox/v1/checkout/push/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  \"payment\": {\n    \"merchantAccountNumber\": 58931443,\n    \"amount\": 150,\n    \"description\": \"Payment for Order #10234\",\n    \"sourceReferenceNumber\": \"{{$guid}}\",\n    \"capturedBy\": \"username@onekhusa.com\"\n  },\n  \"route\": {\n    \"successRedirectionUrl\": \"YOUR_APP_REDIRECTION_SUCCESS_PAGE_URL\",\n    \"failureRedirectionUrl\": \"YOUR_APP_REDIRECTION_ERROR_PAGE_URL\"\n  }\n}"

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

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

POST

checkout

push

initiate

cURL

curl -X POST "https://api.onekhusa.com/sandbox/v1/checkout/push/initiate" \
  --header "Authorization: Bearer your-jwt-token" \
  --header "Content-Type: application/json" \
  --header "Accept-Language: en" \
  --header "X-Idempotency-Key: your-idempotency-key" \
  -d '{
    "payment": {
      "merchantAccountNumber": 58931443,
      "amount": 150.00,
      "description": "Groceries purchase",
      "sourceReferenceNumber": "DR48JS93G3F",
      "capturedBy": "username@onekhusa.com"
    },
    "route": {
      "successRedirectionUrl": "YOUR_APP_REDIRECTION_SUCCESS_PAGE_URL",
      "failureRedirectionUrl": "YOUR_APP_REDIRECTION_ERROR_PAGE_URL"
    }
  }'

import requests

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

payload = {
    "payment": {
        "merchantAccountNumber": 58931443,
        "amount": 150,
        "description": "Payment for Order #10234",
        "sourceReferenceNumber": "{{$guid}}",
        "capturedBy": "username@onekhusa.com"
    },
    "route": {
        "successRedirectionUrl": "YOUR_APP_REDIRECTION_SUCCESS_PAGE_URL",
        "failureRedirectionUrl": "YOUR_APP_REDIRECTION_ERROR_PAGE_URL"
    }
}
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({
    payment: {
      merchantAccountNumber: 58931443,
      amount: 150,
      description: 'Payment for Order #10234',
      sourceReferenceNumber: '{{$guid}}',
      capturedBy: 'username@onekhusa.com'
    },
    route: {
      successRedirectionUrl: 'YOUR_APP_REDIRECTION_SUCCESS_PAGE_URL',
      failureRedirectionUrl: 'YOUR_APP_REDIRECTION_ERROR_PAGE_URL'
    }
  })
};

fetch('https://api.onekhusa.com/sandbox/v1/checkout/push/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/push/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([
    'payment' => [
        'merchantAccountNumber' => 58931443,
        'amount' => 150,
        'description' => 'Payment for Order #10234',
        'sourceReferenceNumber' => '{{$guid}}',
        'capturedBy' => 'username@onekhusa.com'
    ],
    'route' => [
        'successRedirectionUrl' => 'YOUR_APP_REDIRECTION_SUCCESS_PAGE_URL',
        'failureRedirectionUrl' => 'YOUR_APP_REDIRECTION_ERROR_PAGE_URL'
    ]
  ]),
  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/push/initiate"

	payload := strings.NewReader("{\n  \"payment\": {\n    \"merchantAccountNumber\": 58931443,\n    \"amount\": 150,\n    \"description\": \"Payment for Order #10234\",\n    \"sourceReferenceNumber\": \"{{$guid}}\",\n    \"capturedBy\": \"username@onekhusa.com\"\n  },\n  \"route\": {\n    \"successRedirectionUrl\": \"YOUR_APP_REDIRECTION_SUCCESS_PAGE_URL\",\n    \"failureRedirectionUrl\": \"YOUR_APP_REDIRECTION_ERROR_PAGE_URL\"\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/push/initiate")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"payment\": {\n    \"merchantAccountNumber\": 58931443,\n    \"amount\": 150,\n    \"description\": \"Payment for Order #10234\",\n    \"sourceReferenceNumber\": \"{{$guid}}\",\n    \"capturedBy\": \"username@onekhusa.com\"\n  },\n  \"route\": {\n    \"successRedirectionUrl\": \"YOUR_APP_REDIRECTION_SUCCESS_PAGE_URL\",\n    \"failureRedirectionUrl\": \"YOUR_APP_REDIRECTION_ERROR_PAGE_URL\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.onekhusa.com/sandbox/v1/checkout/push/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  \"payment\": {\n    \"merchantAccountNumber\": 58931443,\n    \"amount\": 150,\n    \"description\": \"Payment for Order #10234\",\n    \"sourceReferenceNumber\": \"{{$guid}}\",\n    \"capturedBy\": \"username@onekhusa.com\"\n  },\n  \"route\": {\n    \"successRedirectionUrl\": \"YOUR_APP_REDIRECTION_SUCCESS_PAGE_URL\",\n    \"failureRedirectionUrl\": \"YOUR_APP_REDIRECTION_ERROR_PAGE_URL\"\n  }\n}"

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

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

In order to accept push/card 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 by choosing the payment method
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: You are required to subscribe to all merchant webhook events for push payment i.e. Reversed Push Payment, Successful Push Payment and Failed Push Payment otherwise initiating a payment will be denied.

1. Initiate Payment Request

This step allows your application to initiate the payment request and waits for the successful response to redirect to OneKhusa hosted checkout service. Take note that this endpoint requires access-token for authentication.

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. Standard Checkout

Figure 1: Standard Checkout Your initiated payment transaction will be displayed as illustrated in figure 1 above. Under the card payment method tab, the customer enters card information to finalize the payment. Upon clicking PAY, the customer may be prompted by 3DS authorization through OTP based on the card setup. Once payment is successful and received, the customer is redirected automatically to your application.

3. Simulate Card Checkout Payment

To simulate a card payment made by a customer through the managed checkout service, refer to the Test Cards page.

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

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 the checkout session.

Example:

"GENERATED_TRANSACTION_ID"

checkoutUrl

string<uri>

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

1. Initiate Payment Request

2. Redirect To Checkout

3. Simulate Card Checkout Payment

Authorizations

Headers

Body

Response

​1. Initiate Payment Request

​2. Redirect To Checkout

​3. Simulate Card Checkout Payment

Authorizations

Headers

Body

Response

1. Initiate Payment Request

2. Redirect To Checkout

3. Simulate Card Checkout Payment