Redirection API Base URL Hash Generation Create Transaction Transaction Status Callback Response

Payment API — Redirection

The Redirection Payment API is the most widely adopted integration method. Your server creates a checkout session, and the customer is redirected to the secure OnePay hosted payment page, no new tab, same window. After payment, the customer is returned to your transaction_redirect_url.

This is a same-window redirect flow. The payment page loads in the current browser tab — no pop-ups, no new tabs. This design passes strict browser pop-up blocking policies and improves conversion rates.

Get credentials

App ID + Hash Salt

Create transaction

POST to /v3/checkout/link/

Redirect customer

Use redirect_url in response

Receive callback

Verify via status API

Base URL

All API requests should be made to the following base URL:

https://api.onepay.lk

Onepay API hash generation tutorial

To secure your payment requests, Onepay requires a SHA-256 hash in the request body. This hash ensures that the transaction details have not been tampered with.

HASH FORMULA

SHA256(app_id + currency + amount + HASH_SALT)

Never share your HASH_SALT in client-side code. This should be kept securely on your server.

1. Create Transaction

Creates a payment request and returns a redirect URL to the Onepay Payment Gateway. You can associate items with the transaction if needed.

POSThttps://api.onepay.lk/v3/checkout/link/

REQUEST BODY

PARAMETER	TYPE	DESCRIPTION
`app_id` required	string	Your unique application identifier from the merchant dashboard.
`amount` required	number	The transaction amount, e.g. `100.00`. Use two decimal places.
`currency` required	string	Three-letter ISO currency code. Accepted values: `LKR`, `USD`.
`hash` required	string	SHA-256 hash of `app_id + currency + amount + HASH_SALT`. Generate server-side.
`reference` required	string	Your internal order or reference ID. Used to correlate transactions in your system.
`customer_first_name` required	string	Customer's first name.
`customer_last_name` required	string	Customer's last name.
`customer_phone_number` required	string	Customer's phone number in E.164 format, e.g. `+94771234567`.
`customer_email` required	string	Customer's email address. Used for payment receipts.
`transaction_redirect_url` required	string	The URL the customer is redirected to after payment. Must be HTTPS.
`additionalData` optional	string	Any additional metadata you want to associate with the transaction.
`items` optional	array	Array of item IDs created via the Items API. Attaches itemized billing details to the transaction.

How to Initiate a Postman Request

Follow the steps below to initiate a request using Postman. A detailed walkthrough video will be added shortly for your reference.

2. Transaction Status

After a customer completes (or cancels) payment, verify the outcome by querying the transaction status endpoint. Always verify server-side do not rely solely on URL parameters returned to your redirect page.

Endpoint

POSThttps://api.onepay.lk/v3/transaction/status/

REQUEST BODY

PARAMETER	TYPE	DESCRIPTION
`app_id` required	string	Your unique application identifier.
`onepay_transaction_id` required	string	The transaction ID returned in the `ipg_transaction_id` field when the transaction was created.

RESPONSE FIELDS — 200 OK

FIELD	TYPE	DESCRIPTION
`status`	boolean	`true` if the payment was successful.
`ipg_transaction_id`	string	OnePay's internal transaction identifier.
`amount`	number	The amount charged.
`currency`	string	Currency of the transaction.
`paid_on`	string	Timestamp of payment confirmation in `YYYY-MM-DD HH:mm:ss` format.

3. Onepay webhook callback setup

Set up your system to receive transaction status updates:

Update your callback URL in the APP section of the Onepay portal
Your endpoint should be configured to accept POST requests with JSON payloads
After transaction completion, Onepay will send a callback with transaction details

SAMPLE CALLBACK PAYLOAD

FIELD	TYPE	DESCRIPTION
`transaction_id`	string	The provided transaction ID (e.g. `WQBV118E584C83CBA50C6`).
`status`	number	A numeric representation of the status (e.g. `1`).
`status_message`	string	A message describing the status (e.g. `SUCCESS`).
`additional_data`	string	Any additional data provided during the transaction creation.

callback-response.json

{
    "transaction_id": "WQBV118E584C83CBA50C6",
    "status": 1,
    "status_message": "SUCCESS",
    "additional_data": ""
}

Use this callback data for logging, verification, and updating transaction status in your system.

On This Page