POST
/
checkout
/
push
/
initiate
cURL
curl -X POST "https://dev.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": "Payment for Order #10234",
      "sourceReferenceNumber": "DR48JS93G3F",
      "capturedBy": "username@onekhusa.com"
    },
    "route": {
      "successRedirectionUrl": "YOUR_APP_REDIRECTION_SUCCESS_PAGE_URL",
      "failureRedirectionUrl": "YOUR_APP_REDIRECTION_ERROR_PAGE_URL"
    }
  }'
{
  "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
​
route
object
required

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"