Sign in
external-payments

Create a payment and get a hosted payment page URL

Creates a payment for the authenticated client and returns paymentUrl. Send the customer there; they pay on the gateway page and are redirected to your returnUrl with refNo, status, and clientReference query parameters. Treat the redirect as a hint only. The webhook (or GET /v1/payments/{refNo}) is the source of truth.

post/v1/payments

Headers

idempotency-keystring required
Idempotency-Keystring

Retrying with the same key returns the original payment instead of creating another.

Request body

amountstring required

Amount with up to two decimals

currencystring

ISO 4217 currency

descriptionstring required

Shown on the gateway page and in reports (max 200 chars)

returnUrlstring required

Where to send the customer after payment. Must be https and, if the client has an allow-list, match it.

clientReferencestring

Your own order / invoice reference. Echoed back on the return redirect and in webhooks.

gateway'revpay' | 'gkash'

Gateway to use. Defaults to the client default. Only revpay is available through this API today.

transactionType'PURCHASE' | 'RELOAD' | 'SUBSCRIPTION' | 'TOPUP' | 'OTHER'
paymentMethodstring

RevPay Payment_ID (Appendix A). Leave empty to let the customer choose on the RevPay page. 2 = card, 3 = FPX, 28 = Touch n Go.

bankCodestring

RevPay Bank_Code (Appendix B), only meaningful with paymentMethod 3 or 9.

customerNamestring
customerEmailstring

Required by RevPay for card payments (paymentMethod 2).

customerContactstring

Required by RevPay for card payments. Format +60123456789.

customerIpstring

Customer's IP as seen by you. If omitted, the IP that opens the hosted page is used.

Example request

{
  "amount": "52.40",
  "currency": "MYR",
  "description": "Order #1001",
  "returnUrl": "https://shop.example.com/checkout/return",
  "clientReference": "INV-1001",
  "bankCode": "MB2U0227",
  "customerName": "John Doe",
  "customerEmail": "john@example.com",
  "customerContact": "+60123456789",
  "customerIp": "203.0.113.10"
}

Response

refNostring required
clientReferencestring
gatewaystring required
status'pending' | 'processing' | 'success' | 'failed' | 'cancelled' | 'refunded' | 'expired' required
amountstring required
currencystring required
descriptionstring required
paymentUrlstring

Send the customer here. Present while the payment can still be paid.

returnUrlstring required
gatewayTransactionIdstring
bankReferencestring
responseCodestring

Raw gateway result code (RevPay Appendix C)

errorDescriptionstring
paymentMethodstring

RevPay Payment_ID actually used

refundedAmountstring required
createdAtstring date-time required
completedAtstring date-time

Example response

{
  "refNo": "RP1757150000000A1B2",
  "clientReference": "INV-1001",
  "gateway": "revpay",
  "amount": "52.40",
  "currency": "MYR",
  "description": "Order #1001",
  "refundedAmount": "0.00"
}

Changes

Changed in 1 of the 4 revisions of this API.1