cURL

curl -X POST "https://dev.api.onekhusa.com/sandbox/v1/collections/requestToPay/initiate" \
  --header "Authorization: Bearer your-jwt-token" \
  --header "Content-Type: application/json" \
  --header "Accept-Language: en" \
  -d '{
    "merchantAccountNumber": 12345678,
    "transactionAmount": "8375000.00",
    "transactionDescription": "Samsung 85inch TV purchase",
    "referenceNumber": "1020XDFS76GS777",
    "capturedBy": "username@example.com"
  }'

{
  "merchantAccountNumber": 12345678,
  "timedAccountNumber": "11005533",
  "expiryDate": "2026-01-05T10:01:56.412Z",
  "expiryInMinutes": 15
}

Accept Payments

Request To Pay

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.

How It Works

The following are the steps you need to follow to achieve this:

The merchant system generates the unique reference number to associate with collection transaction.
The merchant system invokes (calls) OneKhusa request-to-pay endpoint to generate a timed account number (TAN) which will expire in 15 minutes upon creation. TAN is a random short-lived (temporary) account tied to merchant account for that transaction.
A customer sends money using their preferred digital platform being provided by a bank or MNO. The flow is similar to Overview section.
A customer provides TAN and transaction amount being paid for the service offered or goods purchased.
The funds are credited to merchant account if:

o TAN has not expired

o TAN and transaction amount are matching
After a successful credit, OneKhusa triggers a request-to-pay webhook to notify the waiting system that the payment was successful
The merchant system notifies the customer that the payment was successful

POST

collections

requestToPay

initiate

cURL

curl -X POST "https://dev.api.onekhusa.com/sandbox/v1/collections/requestToPay/initiate" \
  --header "Authorization: Bearer your-jwt-token" \
  --header "Content-Type: application/json" \
  --header "Accept-Language: en" \
  -d '{
    "merchantAccountNumber": 12345678,
    "transactionAmount": "8375000.00",
    "transactionDescription": "Samsung 85inch TV purchase",
    "referenceNumber": "1020XDFS76GS777",
    "capturedBy": "username@example.com"
  }'

{
  "merchantAccountNumber": 12345678,
  "timedAccountNumber": "11005533",
  "expiryDate": "2026-01-05T10:01:56.412Z",
  "expiryInMinutes": 15
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer , where is your access token.

Headers

Accept-Language

string

default:en

Preferred language for the response

Body

application/json

merchantAccountNumber

integer

required

An active account number for the merchant registered on OneKhusa for accepting payments.

Example:

12345678

transactionAmount

string

required

The total transaction (checkout) amount the customer is supposed to pay, and this is created by the merchant system.

Example:

"8375000.00"

transactionDescription

string

required

The description generated by the merchant system for the service/product(s) purchased by the customer.

Example:

"Samsung 85inch TV purchase"

referenceNumber

string

required

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.

Required string length: 5 - 25

Example:

"1020XDFS76GS777"

capturedBy

string<email>

required

The background user registered under the merchant account being used, initiated on behalf of a customer.

Example:

"username@example.com"

Response

200 - application/json

Success Response (200)

merchantAccountNumber

integer

required

An account number for the merchant used for initiating a request-to-pay transaction.

Example:

12345678

timedAccountNumber

string

required

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".

Example:

"11005533"

expiryDate

string<date-time>

required

The time assigned to TAN to expire.

Example:

"2026-01-05T10:01:56.412Z"

expiryInMinutes

integer

required

Number of minutes TAN will expire after creation.

Example:

15

Overview Get Payments

⌘I

Getting Started

Disbursements

Accept Payments

Merchants

Security

Supporting APIs

Request To Pay

How It Works

Authorizations

Headers

Body

Response