OnePay — Full API Reference for Sri Lanka Payment Gateway

> This is the expanded, machine-readable reference for OnePay's REST API.
> It inlines the real HTTP methods, endpoints, and required parameters so an
> AI agent can answer integration questions without crawling every page.
> Human-readable docs with full examples live at the linked pages below.
> Base API URL for all endpoints: https://api.onepay.lk

## Authentication

OnePay uses a dual-credential model. Get your `app_id` and `hash_salt` from
the merchant dashboard (API Keys section). Each merchant has separate live
and sandbox credential pairs.

- Most endpoints require an `Authorization` header containing your App Token.
- Payment creation requires a SHA-256 hash in the request body:
  `hash = SHA256(app_id + currency + amount + hash_salt)` — concatenate as
  plain strings with no separators, computed server-side only. Never expose
  `hash_salt` in client-side code.

Full details: https://docs.onepay.lk/api-documentation/authentication

## Errors

Conventional HTTP status codes. `200` = success, `4xx` = client error.

| Code | Meaning |
|------|---------|
| 200 | Request succeeded |
| 400 | Invalid request body (bad app_id, amount, app state, or unsupported currency) |
| 401 | Missing/invalid Authorization header or incorrect hash |
| 429 | Rate limited — too many requests within one second |

Full details: https://docs.onepay.lk/api-documentation/error-handling

## Payment API (checkout redirect flow)

Base flow: create a transaction → redirect the customer to the returned
`redirect_url` → OnePay POSTs a callback to your webhook → verify status.

- `POST /v3/checkout/link/` — Create a payment transaction.
  Required body: `app_id`, `amount`, `currency`, `hash`, `reference`,
  `customer_first_name`, `customer_last_name`, `customer_phone_number`,
  `customer_email`, `transaction_redirect_url` (HTTPS).
  Optional: `additionalData`, `items` (array of item IDs).
  Returns a `redirect_url` to send the customer to the hosted OnePay page.

- `POST /v3/transaction/status/` — Check transaction status.
  Required body: `app_id`, `onepay_transaction_id`.
  Response: `status` (bool, true = paid), `ipg_transaction_id`, `amount`,
  `currency`, `paid_on`.

- Webhook callback: configure your callback URL in the OnePay portal (APP
  section). OnePay POSTs JSON to it after transaction completion:
  `{ "transaction_id": "...", "status": 1, "status_message": "SUCCESS",
  "additional_data": "" }`.

Full details: https://docs.onepay.lk/api-documentation/payment-api

## Payment Link API

Generates a shareable payment URL — for invoicing, ERP, and B2B collection
flows where you don't want a checkout session redirect. Authenticates with
a Company API Key in the `Authorization` header (different from the
Payment API's hash-based signing); `app_id` is passed as a query parameter.

- `POST /v3/payment-link/?app_id={app_id}` — Create a payment link.
- `GET /v3/payment-link/{link_id}/?app_id={app_id}` — Get link details.
  Key response fields: `data.is_complete` (bool, true once paid),
  `data.is_delete`, `data.link_url`, `data.amount`, `data.expiration_date`.
- `PUT /v3/payment-link/{link_id}/` — Update a link. Only `description` is
  mutable; amount, currency, reference, customer, and expiry are immutable.
  Body: `app_id`, `description`.
- `DELETE /v3/payment-link/{link_id}/?app_id={app_id}` — Soft-delete a link
  (`is_delete = true`). Fails with 400 if the link has a successful payment.

Supports `allow_partial_payment` (instalments, min 30–100% of total, for
amounts over LKR 100,000 / USD 100) and `expiration_date` to enforce
payment deadlines.

Full details: https://docs.onepay.lk/api-documentation/payment-link

## Refund API

- `POST /v3/transaction/refund/` — Refund a successfully paid live
  transaction. Only one active refund is allowed per transaction, and only
  live (`is_live = true`), paid (`status = true`) transactions qualify.
  Headers: `Authorization` (App Token), `Content-Type: application/json`.
  Required body: `app_id`, `onepay_transaction_id`, `refund_reason`.
  Optional: `is_partially` (bool, default false), `amount` (required if
  `is_partially = true`), `refund_note`.
  Reason codes: `DUPLICATED`, `FRAUDULENT`, `OUT_OF_ORDER`,
  `REQUESTED_BY_CUSTOMER`, `OTHER`.
  Response: `status`, `message`, `data.refund_id`, `data.status`
  (`"refund-initiated"`), `data.is_partially`, `data.requested_amount`,
  `data.refund_reason`.

Full details: https://docs.onepay.lk/api-documentation/refund

## Items Management API

- `POST /v3/item/` — Create a catalog item.
- `GET /v3/item/?app_id={app_id}` — List items.
- `PUT /v3/item/{item_id}/` — Update an item.
- `DELETE /v3/item/{item_id}/?app_id={app_id}` — Delete an item.
Item IDs can be attached to a Payment API transaction via the `items` field.

Full details: https://docs.onepay.lk/api-documentation/items-management

## Automated Charging / Card on File (Customer Tokenizer)

Tokenize customer cards for recurring billing and usage-based charging
without re-entering card details.

- `POST /v3/customers/` — Create a customer.
- `GET /v3/customers/` — List customers.
- `GET /v3/customers/{customer_id}/?app_id={app_id}` — Get a customer.
- `GET /v3/customers/{customer_id}/cards/?app_id={app_id}` — List a
  customer's saved (tokenized) cards.
- `GET /v3/customers/{customer_id}/cards/{token_id}/?app_id={app_id}` — Get
  a specific saved card token.
- `DELETE /v3/customers/{customer_id}/cards/{token_id}/?app_id={app_id}` —
  Remove a saved card token.
- `POST /v3/customers/{customer_id}/payments/` — Charge a customer using a
  saved card token (server-initiated, no redirect).
- `GET /v3/customers/{customer_id}/transactions/?app_id={app_id}` — List a
  customer's transaction history.

Full details: https://docs.onepay.lk/api-documentation/customer-tokenizer

## Payouts API

Settlement runs on a T+2 schedule. Query settlement status per transaction
or across a date range.

- `GET /v3/payout/transaction/?onepay_transaction_id={id}` — Get payout
  status for a single transaction (use the transaction ID captured at
  checkout time). Header: `Authorization: YOUR_APP_TOKEN`.
- `GET /v3/payout/transactions/?start_date={date}&end_date={date}&page={n}&page_size={n}` —
  Paginated list of settled transactions in a date range (`YYYY-MM-DD`).

Full details: https://docs.onepay.lk/api-documentation/payouts

## Currencies & Payment Options

Cards: Visa, Mastercard, Amex, Diners Club, Discover, UnionPay.
Mobile wallets: Google Pay, Frimi, Qplus, Helapay.
Multi-currency support is built in — see the page for the full supported
currency list.

Full details: https://docs.onepay.lk/api-documentation/currencies

## Index

For the general documentation index (guides, plugins, blogs, onboarding),
see: https://docs.onepay.lk/llms.txt

## Pricing Packages

1. Standard Plan: LKR 499.00 monthly. Payment processing fee is 3.50%. Features: Accepts payment from Links, Plugins, API, SDK.
2. Essential Plan: LKR 799.00 monthly. Payment processing fee is 3.25%. Features: Everything in Standard Plan, plus Team Access, Automated Charging - Card On File, USD, GBP, EURO, INR, JPY acceptance and payout.
3. Elevate Plan: LKR 2,999.00 monthly. Payment processing fee is 2.75%. Features: Everything in Essential Plan.
4. Premier Plan: LKR 5,999.00 monthly. Payment processing fee is 2.50%. Features: Everything in Elevate Plan, plus Unlimited Monthly Payment Limit.