Developers
OTA PG API reference
Take payments from your own system. Create a payment link for each order, refund it, send invoices, see what each settlement holds, and get a signed webhook the moment a customer pays.
Introduction
The API speaks JSON over HTTPS. Every address on this page starts with:
https://pg.ota.my/v1
- Amounts are ringgit, written as strings with two decimals:
"25.00". You may send a number such as25.00, but strings avoid rounding errors. The currency is alwaysMYR. - Times are in UTC, written as RFC 3339, such as
2026-11-14T03:15:00Z. Dates without a time, such as an invoice's due date, are Malaysian dates writtenYYYY-MM-DD. - Names of fields and parameters, and fixed values such as statuses and error codes, are lower case with underscores:
created_at,awaiting_payment. A field with no value isnull. - Test and live. Our staging service at
staging-pg.ota.myruns in test mode: its keys start withotapay_sk_test_and no real money moves. Live keys start withotapay_sk_live_and work only atpg.ota.my. Every object carriesmode, so you can tell which you are looking at.
Keys and access
Create secret keys in your dashboard under Developers → API keys & webhooks. A key is shown once, when you create it. Keep it on your server: never put it in an app, a web page or a code repository. If one leaks, revoke it in the dashboard and make another.
Send the key with every request:
curl https://pg.ota.my/v1/account \ -H "Authorization: Bearer otapay_sk_live_…"
Every key can read your payment links, refunds, invoices and events. When you create a key you choose what else it may do. You can only give a key what your own dashboard account may do: a teammate who cannot refund cannot make a key that refunds.
| Access | What it allows |
|---|---|
payment_links | Create, close and reopen payment links. |
invoices | Send, remind and cancel invoices. |
refunds | Refund payments. |
settlements | Read settlements: what each transfer to your bank holds. |
A call the key may not make is refused with 403 and the code missing_access.
Check a key
GET /v1/account
Says which business and key a request runs as. Use it to check that a new key works.
{
"object": "account",
"id": "kedai-ali",
"name": "Kedai Ali",
"mode": "live",
"can_take_payments": true,
"settlement_days": 2,
"key": {
"id": "key-3f9a1c2b7d10",
"name": "Shop backend",
"prefix": "otapay_sk_live_9c41e2",
"access": ["payment_links", "refunds"],
"created_at": "2026-11-14T03:15:00Z"
}
}
can_take_payments is false until your account is activated. Until then, creating payment links and invoices is refused with account_not_active.
Errors
A failed request answers with an HTTP status and a body like this:
{
"error": {
"code": "amount_too_large",
"message": "Only RM 40.00 is left to refund on this payment.",
"request_id": "req_8d0c5a1e93b24f67"
}
}
Act on code; show or log message, which is written for people and may change. Every response, good or bad, has an OTA-Request-Id header with the same ID: quote it when you ask us about a request.
| Status | Meaning | Common codes |
|---|---|---|
400 | Something in the request is wrong. Fix it before trying again. | invalid_json, invalid_request, invalid_amount, invalid_date, invalid_status, reference_required, idempotency_key_required |
401 | No key, a wrong key or a revoked one. | unauthorized |
403 | The key or the account may not do this. | missing_access, account_not_active |
404 | No such object, or no such address. Another business's objects look the same as missing ones. | not_found |
409 | The object is not in a state that allows this. | already_paid, not_paid, fully_refunded, amount_too_large, invoice_link, invoice_number_used, reference_in_use, idempotency_in_progress |
422 | Understood, but refused. | refund_declined, idempotency_key_reused |
429 | Too many requests. Wait for the Retry-After seconds. | rate_limited |
5xx | A problem on our side. Retry with the same Idempotency-Key. | internal_error |
We may add codes. Treat a code you do not know by its HTTP status.
Safe retries
Networks fail. When a request times out you cannot tell whether it reached us, so every request that changes something can be retried safely:
- Payment links and invoices are matched by your own number. Sending the same
referenceor invoicenumberagain returns the first one with200, not a second one. - Any POST may carry an
Idempotency-Keyheader: a value unique to that action, such as a UUID. We keep the first answer to each key for 24 hours and return it again for every retry with the same key, with the headerOTA-Idempotent-Replay: true. - Refunds require an Idempotency-Key. A refund moves money back to the customer, so it is never sent twice.
curl -X POST https://pg.ota.my/v1/refunds \ -H "Authorization: Bearer otapay_sk_live_…" \ -H "Idempotency-Key: 6b0f1e2a-4c55-4a77-9a0e-1d2c3b4a5f60" \ -H "Content-Type: application/json" \ -d '{"payment_link":"ord-6f1c2a9d0b3e4f57","amount":"10.00"}'
A key belongs to one request. Reusing it with a different body gets 422 idempotency_key_reused. If the first request is still running, a retry gets 409 idempotency_in_progress: wait a moment and retry. Answers that changed nothing, such as a 400 for a missing field, are not kept, so you can correct the request and send it with the same key.
Lists and pages
Lists come newest first, a page at a time:
{
"object": "list",
"data": [ { "id": "ord-6f1c2a9d0b3e4f57", "object": "payment_link", … } ],
"has_more": true,
"next_cursor": "MTc2MzA4OTMwMDAwMDAwMDAwMHxvcmQtNmYxYzJhOWQwYjNlNGY1Nw"
}
| Parameter | Description |
|---|---|
limit | How many to return, from 1 to 100. The default is 20. |
cursor | The next_cursor of the page before, unchanged. Leave it out for the first page. |
A cursor marks where the last page ended, so objects created while you page through neither repeat nor go missing. When has_more is false, you have them all and next_cursor is null.
Rate limits
Each key may make 25 requests a second on average, with short bursts up to 50. Beyond that we answer 429 with the code rate_limited and a Retry-After header in seconds. Instead of polling a payment link in a loop, use webhooks.
Payment links
A payment link is one amount to collect, with a checkout page at its url. Send the customer there, or show it as a QR code. They choose online banking (FPX), DuitNow QR, a card or an e-wallet. A link is paid once; after that it shows the receipt.
The payment link object
| Field | Type | Description |
|---|---|---|
id | string | Our ID, such as ord-6f1c2a9d0b3e4f57. |
object | string | payment_link |
reference | string | Your own order number. Unique in your account. |
amount | string | What the customer pays, such as "48.00". |
currency | string | MYR |
description | string | Shown to the customer and on their bank statement. |
status | string | See statuses. |
url | string | The checkout page to send the customer to. |
source | string | Where the link came from: api, dashboard, invoice or button (a Pay button). |
created_at | time | When it was created. |
expires_at | time or null | When it stops taking new payments. A payment begun before this time can still finish after it. |
paid_at | time or null | When it was paid. |
fee | string | Our fee, once paid. Fixed at the moment of payment. |
net | string | The amount minus the fee, once paid. |
amount_refunded | string | Refunded so far, including refunds still in progress. |
payment | object | Once paid: method (fpx, dnqr, card, tng, grab, boost or shopeepay), bank for FPX, and reference_id and payment_id to quote when you ask us about the payment. |
refunds | array | Its refunds, newest last. |
mode | string | test or live. |
Statuses
| Status | Meaning |
|---|---|
open | Waiting for the customer. |
awaiting_payment | The customer has started paying, and their bank or app has not answered yet. |
failed | The last try was declined or cancelled. The customer can try again while the link is open. |
expired | Closed with nothing paid: its time ran out, or it was closed. |
paid | Paid in full. This is the moment to fulfil the order. |
partially_refunded | Paid, and part of it refunded. |
refunded | Paid, then refunded in full. |
Create a payment link
POST /v1/payment-links
Needs payment_links access.
| Field | Description |
|---|---|
amount required | From RM 1.00 to RM 30,000.00. |
description required | Up to 60 letters, numbers, spaces, dots and hyphens. |
reference required | Your order number: up to 64 letters, numbers and . _ : / # -, starting with a letter or number. Sending a reference that is already used returns that link instead of making a new one. |
valid_minutes | How long the link takes payments, from 5 minutes to 30 days (43200). The default is 24 hours. |
curl -X POST https://pg.ota.my/v1/payment-links \ -H "Authorization: Bearer otapay_sk_live_…" \ -H "Content-Type: application/json" \ -d '{"amount":"48.00","description":"Order 1042","reference":"1042","valid_minutes":60}'
201 Created { "id": "ord-6f1c2a9d0b3e4f57", "object": "payment_link", "reference": "1042", "amount": "48.00", "currency": "MYR", "description": "Order 1042", "status": "open", "url": "https://pg.ota.my/pay/ord-6f1c2a9d0b3e4f57", "source": "api", "created_at": "2026-11-14T03:15:00Z", "expires_at": "2026-11-14T04:15:00Z", "paid_at": null, "amount_refunded": "0.00", "refunds": [], "mode": "live" }
List payment links
GET /v1/payment-links
| Parameter | Description |
|---|---|
status | One status, or several separated by commas: paid,partially_refunded. |
reference | Your order number. Gives the one link with it, or none. |
created_from, created_to | Created on or after, and on or before. A date such as 2026-11-14 means that whole day in Malaysia; an RFC 3339 time is exact. |
limit, cursor | See lists and pages. |
curl "https://pg.ota.my/v1/payment-links?status=paid&created_from=2026-11-01" \ -H "Authorization: Bearer otapay_sk_live_…"
Get a payment link
GET /v1/payment-links/{id}
Returns the link as it is now. If a payment is in progress, we ask the payment network first, so the answer is never behind.
Close a payment link
POST /v1/payment-links/{id}/close
Stops the link taking new payments, for example when the customer cancels the order. Needs payment_links access. A paid link cannot be closed (409 already_paid). An invoice's link cannot be closed here: cancel the invoice instead.
Reopen a payment link
POST /v1/payment-links/{id}/reopen
Lets a closed or expired link take payments again, for valid_minutes from now (default 24 hours). Needs payment_links access.
curl -X POST https://pg.ota.my/v1/payment-links/ord-6f1c2a9d0b3e4f57/reopen \ -H "Authorization: Bearer otapay_sk_live_…" \ -H "Content-Type: application/json" \ -d '{"valid_minutes":120}'
Refunds
A refund sends all or part of a payment back to the customer. Online banking (FPX) and card payments can be refunded in part; other methods only in full. Refunding an FPX payment costs RM 0.70 per refund; refunds on other methods are free. Refunds and their fees come off your next settlement.
The refund object
| Field | Type | Description |
|---|---|---|
id | string | Our ID, a UUID. |
object | string | refund |
payment_link | string | The ID of the payment link refunded. |
reference | string | That link's reference, your order number. |
amount | string | The amount refunded. |
fee | string | The refund fee. "0.00" for a failed refund. |
currency | string | MYR |
status | string | pending (in progress), succeeded or failed. |
created_at | time | When it was asked for. |
mode | string | test or live. |
Create a refund
POST /v1/refunds
Needs refunds access and an Idempotency-Key header (see safe retries).
| Field | Description |
|---|---|
payment_link required | The ID of the paid payment link. |
amount | How much to refund. Leave it out to refund everything not yet refunded. |
201 Created { "id": "0b8e6c1d-2f4a-4e1b-9c7d-5a3f2e1d0c9b", "object": "refund", "payment_link": "ord-6f1c2a9d0b3e4f57", "reference": "1042", "amount": "10.00", "fee": "0.70", "currency": "MYR", "status": "pending", "created_at": "2026-11-15T02:40:12Z", "mode": "live" }
The answer is one of:
201: the refund is accepted, usually aspending. You hear when it settles through arefund.updatedwebhook.202: we sent the refund but the payment network has not answered yet. It shows aspendingand we keep the amount aside. Do not send it again with a new key; check it withGET /v1/refunds/{id}, or wait for the webhook.422 refund_declined: the payment network refused it, and nothing was refunded. The message says why.409: the link is not paid (not_paid), already refunded in full (fully_refunded), or the amount is more than is left (amount_too_large).400 partial_refund_unsupported: the payment's method can only be refunded in full.
List refunds
GET /v1/refunds
Filter with payment_link (one link's refunds) and status (pending, succeeded or failed), and page with limit and cursor.
Get a refund
GET /v1/refunds/{id}
For a refund still pending, we ask the payment network first, at most every 10 seconds.
Invoices
An invoice emails your customer a payment request with its own payment link, and reminds them around the due date until it is paid. When they pay, they get a receipt and you get an invoice.paid webhook. These are payment requests that quote your invoice number, not LHDN e-Invoices: keep issuing those from your accounting software.
Emails come from your business name "via OTA PG", and replies go to the contact email in your dashboard settings. Each business can send a set number of invoice emails a day (100 to start; ask us for more). Emails over the limit wait for the next morning at 9am. Each invoice's link stays open until 60 days after its due date, and at least two weeks.
The invoice object
| Field | Type | Description |
|---|---|---|
id | string | Our ID, such as inv-2c7e90a1f4b35d68. |
object | string | invoice |
number | string | Your invoice number. It is also the reference of its payment link. |
customer | object | name, email and phone. |
amount | string | The amount due. |
description | string | What it is for, shown in the email. |
issue_date, due_date | date | The invoice's date (or null) and when it is due. |
status | string | See statuses. |
payment_link, url | string | Its payment link's ID, and the page the email links to. |
reminders | array | Days from the due date when reminders go: -3 is three days before, 0 the day itself, 3 three days after. |
message | string | Your note to the customer, shown in each email. |
emails | array | Each email sent: kind (invoice, reminder or receipt), at, to and delivered. |
email_notice | string or null | Why the next email is waiting, such as the daily limit. |
send_at, next_email_at | time | When the first email goes (or went), and when the next one is due. |
sent_at, viewed_at, paid_at, cancelled_at | time or null | When it was emailed, first opened by the customer, paid and cancelled. |
created_at, mode | As on other objects. |
Statuses
| Status | Meaning |
|---|---|
scheduled | Waiting for its send time, or for the daily email limit. |
sent | Emailed, not paid yet. |
viewed | Sent, and the customer has opened its payment page. |
overdue | Sent, unpaid and past its due date. |
paid | Paid through its link. |
cancelled | Cancelled; its link is closed. |
failed | The first email could not be delivered after three tries. Check the address. |
Create an invoice
POST /v1/invoices
Needs invoices access. The checks are the same as for a spreadsheet upload in the dashboard.
| Field | Description |
|---|---|
number required | Your invoice number: up to 64 letters, numbers and . _ : / # -, no spaces. Sending a number again with the same amount, email and due date returns the first invoice with 200; with different ones, 409 invoice_number_used. |
customer.name required | Up to 100 characters. |
customer.email required | Where the invoice goes. |
customer.phone | For your records. |
amount required | From RM 1.00 to RM 30,000.00. |
due_date required | YYYY-MM-DD. A date already past is accepted; the email says when it was due. |
issue_date | YYYY-MM-DD. |
description | Up to 200 characters. |
reminders | Any of -7, -3, -1, 0, 3, 7 and 14. The default is [-3, 0, 3]; send [] for none. Reminders go at 9am Malaysia time. |
message | A note to the customer, up to 500 characters. |
send_at | An RFC 3339 time up to 60 days ahead. Leave it out to send now. |
curl -X POST https://pg.ota.my/v1/invoices \ -H "Authorization: Bearer otapay_sk_live_…" \ -H "Content-Type: application/json" \ -d '{ "number": "INV-2041", "customer": { "name": "Restoran Mawar", "email": "[email protected]" }, "amount": "1250.00", "due_date": "2026-11-30", "description": "November supplies", "reminders": [-3, 0, 7] }'
List invoices
GET /v1/invoices
Filter with status (any status above, or unpaid for sent, viewed and overdue together) and number, and page with limit and cursor.
Get an invoice
GET /v1/invoices/{id}
Send a reminder now
POST /v1/invoices/{id}/remind
Emails a reminder straight away. Needs invoices access. Only a sent, unpaid invoice can be reminded, and at most once an hour by hand (409 cannot_remind). It counts towards the daily email limit.
Cancel an invoice
POST /v1/invoices/{id}/cancel
Stops its reminders and closes its payment link. Needs invoices access. A paid invoice cannot be cancelled (409 cannot_cancel); refund it instead.
Settlements
We never hold your money. Each business day's payments reach your bank account 2 business days later in one transfer, with our fees and that day's refunds already taken off. A settlement is one such transfer. Needs settlements access.
Settlements are worked out from your payments and refunds, so they always agree with them. Dates are estimates until the transfer is made: public holidays can move them. Card fees are estimated at the credit card rate until we know which kind of card was used; fees_estimated says so.
The settlement object
| Field | Type | Description |
|---|---|---|
id, date | string | The transfer's date, YYYY-MM-DD. |
object | string | settlement |
expected_at | time | When it is due to reach your bank. |
status | string | upcoming or sent. |
payments, refunds | number | How many of each it holds. |
gross | string | The payments' total. |
fees | string | Payment fees taken off. |
refunded, refund_fees | string | Refunds and refund fees taken off. |
carried_over | string | A shortfall from an earlier day, taken off here ("0.00" or less). |
net | string | What reaches your bank. Never below zero. |
shortfall | string | When refunds are more than the day's payments, the difference, taken off the next settlement. |
fees_estimated | boolean | True while card fees are estimates. |
List settlements
GET /v1/settlements
Filter with status (upcoming or sent), and page with limit and cursor.
Get a settlement
GET /v1/settlements/{date}
The settlement with its lines: every payment and refund in it, each with type (payment or refund), at, payment_link, reference, channel, amount (negative for a refund), fee and net.
{
"id": "2026-11-18",
"object": "settlement",
"date": "2026-11-18",
"expected_at": "2026-11-18T01:00:00Z",
"status": "upcoming",
"currency": "MYR",
"payments": 2,
"refunds": 1,
"gross": "148.00",
"fees": "1.85",
"refunded": "10.00",
"refund_fees": "0.70",
"carried_over": "0.00",
"net": "135.45",
"shortfall": "0.00",
"fees_estimated": false,
"lines": [
{ "type": "payment", "at": "2026-11-14T03:21:40Z", "payment_link": "ord-6f1c2a9d0b3e4f57",
"reference": "1042", "channel": "FPX · Maybank2u", "amount": "48.00", "fee": "1.00", "net": "47.00", "fee_estimated": false },
…
]
}
Events
Every webhook we send is also an event you can read, with how its delivery went. Use events to catch up after your server was down. We keep recent events, not a full history.
The event object
| Field | Type | Description |
|---|---|---|
id | string | Such as evt_4b1e0c9a7d2f6e8a3c51. The same ID as the webhook. |
object | string | event |
type | string | See event types. |
created_at | time | When it happened. |
payment_link | string or null | The payment link it is about. |
data | object | The object as it was at that moment. |
delivery | object | status (pending, delivered, failed or no_endpoint), attempts, last_attempt_at, last_http_status and next_attempt_at. |
List events
GET /v1/events
Filter with type and payment_link, and page with limit and cursor.
Get an event
GET /v1/events/{id}
Webhooks
Set your endpoint in the dashboard under Developers → API keys & webhooks. We then POST each event to it as JSON, signed with your signing secret. Use Send test event there to check your endpoint, and Webhook logs to see every delivery and send one again.
POST /webhooks/ota-pg HTTP/1.1
Content-Type: application/json
User-Agent: OTA-PG-Webhooks/1.0
OTA-Event-Id: evt_4b1e0c9a7d2f6e8a3c51
OTA-Event-Type: payment.succeeded
OTA-Signature: t=1794626500,v1=5f2b9c…
{
"id": "evt_4b1e0c9a7d2f6e8a3c51",
"type": "payment.succeeded",
"created": "2026-11-14T03:21:40Z",
"data": { "id": "ord-6f1c2a9d0b3e4f57", "object": "payment_link", "status": "paid", … }
}
Event types
| Type | When | data |
|---|---|---|
payment.succeeded | A payment link is paid. | The payment link |
refund.updated | A refund is asked for, or its status changes. | The refund |
invoice.paid | An invoice is paid. Its payment link's payment.succeeded comes too. | The invoice |
test | You pressed Send test event. | A message |
Answering a webhook
- Answer with any
2xxstatus within 10 seconds. Do slow work after answering. - If you do not, we try again after 1 minute, 5 minutes, 15 minutes, 1 hour, 6 hours and 24 hours: seven tries over about 31 hours. After that the event is marked failed; you can still send it again from the dashboard, or read it from events.
- The same event can arrive more than once, and events can arrive out of order. Use the event
idto skip ones you have handled, and when the order matters, fetch the object's current state from the API. - Your endpoint must be a public HTTPS address.
Verify a webhook
Check the signature before you trust a webhook, so nobody else can tell your system an order is paid. The OTA-Signature header is t=<unix seconds>,v1=<signature>, where the signature is the hex HMAC-SHA256 of the time, a dot and the raw request body, keyed with your signing secret. Compare it in constant time, and refuse times more than 5 minutes old so an old message cannot be replayed. Use the raw body exactly as it arrived: parsing and re-encoding the JSON changes it.
Node.js
const crypto = require('crypto');
function verify(rawBody, header, secret) {
const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=')));
const mac = crypto.createHmac('sha256', secret).update(t + '.' + rawBody).digest('hex');
const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
return fresh && mac.length === v1.length && crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(v1));
}
PHP
function verify(string $rawBody, string $header, string $secret): bool {
parse_str(str_replace(',', '&', $header), $sig);
$mac = hash_hmac('sha256', $sig['t'] . '.' . $rawBody, $secret);
return abs(time() - (int) $sig['t']) < 300 && hash_equals($mac, $sig['v1'] ?? '');
}
$ok = verify(file_get_contents('php://input'), $_SERVER['HTTP_OTA_SIGNATURE'] ?? '', getenv('OTA_PG_WEBHOOK_SECRET'));
Python
import hashlib, hmac, time
def verify(raw_body: bytes, header: str, secret: str) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
mac = hmac.new(secret.encode(), parts["t"].encode() + b"." + raw_body, hashlib.sha256).hexdigest()
fresh = abs(time.time() - int(parts["t"])) < 300
return fresh and hmac.compare_digest(mac, parts.get("v1", ""))
Changes to the API
Version 1 only grows: we may add fields, endpoints, error codes and event types, so ignore what you do not recognise. Anything that would break your code comes as a new version, announced by email first.