Skip to main content
POST

Headers

​
Abp-TenantId
string
required

Your unique Merchant ID assigned by CommercePay.

​
Authorization
string
required

Your API credentials used for authentication (typically a Bearer token).

​
cap-signature
string
required

A unique security hash used to verify the integrity of the request body. See Generate Signature for how to generate this.

Body

application/json
​
currencyCode
string
required

Currency code with a 3-letter ISO 4217 standard code (e.g., MYR).

Maximum string length: 3
Example:

"MYR"

​
amount
integer<int64>
required

The transaction payment value. This field exclusively accepts integer units where the final decimals are represented as whole values (e.g., an amount value of 1000 translates to 10.00 in the system backend).

Example:

100

​
referenceCode
string
required

The merchant-side unique order reference or invoice tracking sequence code.

Maximum string length: 50
​
description
string
required

Short free-text summary of the transaction.

Use English letters, numbers, spaces and basic punctuation (. , - _ ( ) @ /). Avoid emojis and non-English characters: some payment providers remove unsupported characters or shorten the text (for example, FPX keeps only the first 30 characters), so the description shown to the customer by the provider may differ from what you sent. The payment is not rejected when characters are removed.

Maximum string length: 100
Example:

"Order details"

​
ipAddress
string
required

The customer's IP address captured by the merchant server.

Maximum string length: 50
​
returnUrl
string
required

The synchronous return URL where the customer's browser is automatically redirected after the transaction is completed.

Maximum string length: 500
Example:

"https://returnurl.com/"

​
timestamp
integer<int64>
required

Numeric timestamp in milliseconds representing request validation freshness, generated via new Date().getTime(). Example: 1621851652617.

Example:

1621851652617

​
channelId
integer<int32> | null

An identifier that represents a CommercePay payments channel. Refer to the id from the response of the Get Channel List.

Optional: Send without channelId parameter to call Payment web

Example:

2

​
providerChannelId
string | null

An identifier that represents the payment provider channel. To get providerChannelId, kindly refer to Get Provider Channels for more information

Example:

"TEST0021"

​
userAgent
string | null

[Conditional] Customer's user agent. It is recommended to input for a better user experience for specific channels due to different platforms such as desktop, mobile, or app view. Example channels impact: ShopeePay.

Maximum string length: 200
​
callbackUrl
string | null

Target address utilized for asynchronous host-to-host webhook payment status change push actions.

Maximum string length: 500
Example:

"https://callback.com/"

​
savePayment
boolean

[Conditional for Tokenize Payment] To save user info for subsequent payment

​
customer
object
​
subMerchant
object
​
localCitizen
boolean

[Conditional for certain channel] Example: If the customer is from Malaysia, kindly set it as True; else, set it as False

​
recurringPaymentInfo
object

[Conditional for Recurring Payment]

​
requestPaymentExtraInfo
object

[Optional]

​
platformCharge
object

Optional: Only Authorized Partners by CommercePay are allowed to charge platform fees to the merchant

​
ChannelDetails
object

[Optional]

​
BrowserInfo
object

[Optional]

​
VirtualAccountCode
string | null

Code to identify virtual account to make payment.

Maximum string length: 30
​
loyaltyPaymentInfoDto
LoyaltyPaymentInfoDto · object

[Conditional for Loyalty payment]

Response

Success

​
currencyCode
string | null

Currency code with a 3-letter ISO 4217 standard code (e.g., MYR).

Maximum string length: 3
Example:

"MYR"

​
amount
integer<int64>

Please take note: The Amount parameter only accepts integer units. For example, 1000 is equivalent to 10.00 for the backend

Example:

100

​
transactionNumber
string | null

Unique CommercePay Transaction Number

Maximum string length: 24
​
channelId
integer<int32> | null

Refer to the id from the response of the Get Channel List.

​
redirectionType
enum<integer>

How to present the payment to the customer.

Available options:
1,
2,
4,
5,
6
​
redirectUrl
string | null

URL used for the customer to redirect to the payment page

​
clientScript
string | null

Script to render in the customer's browser. Only set when redirectionType is 2.

​
base64Image
string | null

Base64-encoded QR code image. Only set for QR channels (redirectionType 4 or 6, channel dependent).

​
expiredInSeconds
integer<int32> | null

How many seconds the payment stays valid from the time of this response. Only set for channels with a short validity period (QR channels and some card channels). Use transactionExpired for the exact deadline.

​
serialNumber
integer<int64> | null

Payment serial number the customer quotes at the counter. Only set when redirectionType is 5.

​
transactionExpired
string<date-time> | null

Deadline for completing the payment. Can be null when the channel doesn't report one.

​
paymentToken
string | null

Token that identifies this transaction on CommercePay's hosted payment page. Always returned, so you don't need to parse it out of redirectUrl, which may point to the payment provider instead.