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

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.

AccessWhat it allows
payment_linksCreate, close and reopen payment links.
invoicesSend, remind and cancel invoices.
refundsRefund payments.
settlementsRead 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.

StatusMeaningCommon codes
400Something 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
401No key, a wrong key or a revoked one.unauthorized
403The key or the account may not do this.missing_access, account_not_active
404No such object, or no such address. Another business's objects look the same as missing ones.not_found
409The 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
422Understood, but refused.refund_declined, idempotency_key_reused
429Too many requests. Wait for the Retry-After seconds.rate_limited
5xxA 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:

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"
}
ParameterDescription
limitHow many to return, from 1 to 100. The default is 20.
cursorThe 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.

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

FieldTypeDescription
idstringOur ID, such as ord-6f1c2a9d0b3e4f57.
objectstringpayment_link
referencestringYour own order number. Unique in your account.
amountstringWhat the customer pays, such as "48.00".
currencystringMYR
descriptionstringShown to the customer and on their bank statement.
statusstringSee statuses.
urlstringThe checkout page to send the customer to.
sourcestringWhere the link came from: api, dashboard, invoice or button (a Pay button).
created_attimeWhen it was created.
expires_attime or nullWhen it stops taking new payments. A payment begun before this time can still finish after it.
paid_attime or nullWhen it was paid.
feestringOur fee, once paid. Fixed at the moment of payment.
netstringThe amount minus the fee, once paid.
amount_refundedstringRefunded so far, including refunds still in progress.
paymentobjectOnce 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.
refundsarrayIts refunds, newest last.
modestringtest or live.
StatusMeaning
openWaiting for the customer.
awaiting_paymentThe customer has started paying, and their bank or app has not answered yet.
failedThe last try was declined or cancelled. The customer can try again while the link is open.
expiredClosed with nothing paid: its time ran out, or it was closed.
paidPaid in full. This is the moment to fulfil the order.
partially_refundedPaid, and part of it refunded.
refundedPaid, then refunded in full.

Create a payment link

POST /v1/payment-links

Needs payment_links access.

FieldDescription
amount requiredFrom RM 1.00 to RM 30,000.00.
description requiredUp to 60 letters, numbers, spaces, dots and hyphens.
reference requiredYour 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_minutesHow 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

ParameterDescription
statusOne status, or several separated by commas: paid,partially_refunded.
referenceYour order number. Gives the one link with it, or none.
created_from, created_toCreated 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, cursorSee 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

FieldTypeDescription
idstringOur ID, a UUID.
objectstringrefund
payment_linkstringThe ID of the payment link refunded.
referencestringThat link's reference, your order number.
amountstringThe amount refunded.
feestringThe refund fee. "0.00" for a failed refund.
currencystringMYR
statusstringpending (in progress), succeeded or failed.
created_attimeWhen it was asked for.
modestringtest or live.

Create a refund

POST /v1/refunds

Needs refunds access and an Idempotency-Key header (see safe retries).

FieldDescription
payment_link requiredThe ID of the paid payment link.
amountHow 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:

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

FieldTypeDescription
idstringOur ID, such as inv-2c7e90a1f4b35d68.
objectstringinvoice
numberstringYour invoice number. It is also the reference of its payment link.
customerobjectname, email and phone.
amountstringThe amount due.
descriptionstringWhat it is for, shown in the email.
issue_date, due_datedateThe invoice's date (or null) and when it is due.
statusstringSee statuses.
payment_link, urlstringIts payment link's ID, and the page the email links to.
remindersarrayDays from the due date when reminders go: -3 is three days before, 0 the day itself, 3 three days after.
messagestringYour note to the customer, shown in each email.
emailsarrayEach email sent: kind (invoice, reminder or receipt), at, to and delivered.
email_noticestring or nullWhy the next email is waiting, such as the daily limit.
send_at, next_email_attimeWhen the first email goes (or went), and when the next one is due.
sent_at, viewed_at, paid_at, cancelled_attime or nullWhen it was emailed, first opened by the customer, paid and cancelled.
created_at, modeAs on other objects.

Statuses

StatusMeaning
scheduledWaiting for its send time, or for the daily email limit.
sentEmailed, not paid yet.
viewedSent, and the customer has opened its payment page.
overdueSent, unpaid and past its due date.
paidPaid through its link.
cancelledCancelled; its link is closed.
failedThe 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.

FieldDescription
number requiredYour 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 requiredUp to 100 characters.
customer.email requiredWhere the invoice goes.
customer.phoneFor your records.
amount requiredFrom RM 1.00 to RM 30,000.00.
due_date requiredYYYY-MM-DD. A date already past is accepted; the email says when it was due.
issue_dateYYYY-MM-DD.
descriptionUp to 200 characters.
remindersAny of -7, -3, -1, 0, 3, 7 and 14. The default is [-3, 0, 3]; send [] for none. Reminders go at 9am Malaysia time.
messageA note to the customer, up to 500 characters.
send_atAn 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

FieldTypeDescription
id, datestringThe transfer's date, YYYY-MM-DD.
objectstringsettlement
expected_attimeWhen it is due to reach your bank.
statusstringupcoming or sent.
payments, refundsnumberHow many of each it holds.
grossstringThe payments' total.
feesstringPayment fees taken off.
refunded, refund_feesstringRefunds and refund fees taken off.
carried_overstringA shortfall from an earlier day, taken off here ("0.00" or less).
netstringWhat reaches your bank. Never below zero.
shortfallstringWhen refunds are more than the day's payments, the difference, taken off the next settlement.
fees_estimatedbooleanTrue 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

FieldTypeDescription
idstringSuch as evt_4b1e0c9a7d2f6e8a3c51. The same ID as the webhook.
objectstringevent
typestringSee event types.
created_attimeWhen it happened.
payment_linkstring or nullThe payment link it is about.
dataobjectThe object as it was at that moment.
deliveryobjectstatus (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

TypeWhendata
payment.succeededA payment link is paid.The payment link
refund.updatedA refund is asked for, or its status changes.The refund
invoice.paidAn invoice is paid. Its payment link's payment.succeeded comes too.The invoice
testYou pressed Send test event.A message

Answering a webhook

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.

Version 1 · 14 November 2026. Questions? Write to [email protected].