Skip to main content
POST /api/payments/initiate Creates a new payment transaction. On success, a transactionId is returned — use it in subsequent Confirm or Status calls.

​
Request Body

​
merchantId
string (uuid)
required
Merchant unique identifier in UUID format.Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
​
referenceNo
string
required
Merchant-assigned reference number for this transaction. Must be unique within the merchant.Example: MER-20240616-001
​
description
string
Optional description or purpose of the payment.
​
amount
integer
required
Payment amount in the smallest currency unit (e.g., cents for MYR).
ValueEquivalent
1001.00 MYR
349134.91 MYR
15000150.00 MYR
​
currencyCode
string
default:"MYR"
ISO 4217 currency code.Examples: MYR, USD, SGD
​
productCode
string
required
Target product or service code.Examples: TNB, AIR_SELANGOR, STARBUCK, RAZER_PIN
​
quantity
integer
Number of items. Applicable for products such as gift cards or PINs.
​
countryCode
string
ISO 3166-1 alpha-2 country code.Examples: MY, SG
​
storeId
string
required
Merchant store identifier originating the payment request.Example: STORE-001
​
deviceId
string
Device identifier of the terminal or client making the request.Example: DEV-12345
​
payerId
string
Payer identifier. Accepts a mobile number, bill account number, e-wallet QR code, or any account number.
​
returnUrl
string
URL to redirect the payer to after the payment is completed or cancelled (for redirect-based flows).
​
extraProperties
string (JSON)
Additional product-specific properties serialised as a JSON string.Example: "{\"accountNumber\":\"123456\"}"

​
Response

​
200 — Payment Initiated

​
isSuccess
boolean
true
​
errorCode
null
null on success.
​
message
string | null
Optional informational message.
​
data
object

​
400 — Bad Request

Model validation failed or the request is logically invalid.

​
500 — Internal Server Error

​
Examples

{
  "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "referenceNo": "MER-20240616-001",
  "description": "TNB Electricity Bill Payment",
  "amount": 15000,
  "currencyCode": "MYR",
  "productCode": "TNB",
  "quantity": 1,
  "countryCode": "MY",
  "storeId": "STORE-001",
  "deviceId": "DEV-12345",
  "payerId": "0123456789",
  "returnUrl": "https://merchant.example.com/payment/callback",
  "extraProperties": {
    "accountNumber": "123456"
  }
}