Skip to main content
POST
Direct Integration
Used to initiate a checkout transaction and obtain the secure payment provider redirection URL.

Request

Headers

string
required
Your unique Merchant ID assigned by CommercePay.
string
required
Your API credentials used for authentication (typically a Bearer token).
string
required
A unique security hash used to verify the integrity of the request body. See Generate Signature for how to generate this.

Body

Omitting channelId routes the customer to CommercePay’s hosted payment page instead, where they pick their own payment method. If you’d rather let CommercePay handle channel selection this way, see API Hosted Session Checkout.
integer
An identifier that represents the CommercePay payment channel. Refer to the id from the response of the API Get Channel List, or see the Channel List for common values. This parameter can be omitted if you choose to utilize the CommercePay Hosted Payment Web interface.
string
An identifier that represents the specific upstream payment provider sub-channel (e.g., a bank code for online banking). This becomes mandatory if the chosen channel configuration has isProviderHostChannel: true. Obtain valid values from the API Get Provider Channels, or see the Channel List for common values.
string
required
Currency code with a 3-letter ISO 4217 standard code (e.g., MYR).
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).
string
required
The merchant-side unique order reference or invoice tracking sequence code.Maximum string length: 50
string
required
The customer’s IP address captured by the merchant server.Maximum string length: 50
string
[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
string
required
The synchronous return URL where the customer’s browser is automatically redirected after the transaction is completed.Maximum string length: 500
int64
required
Numeric timestamp in milliseconds representing request validation freshness, generated via new Date().getTime(). Example: 1621851652617.
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 before using it (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
string
Target address utilized for asynchronous host-to-host webhook payment status change push actions. See Callback Notifications for the payload and signature verification steps.Maximum string length: 500

Request Payload Sample

Payload

Response

Body

string
Currency code with a 3-letter ISO 4217 standard code (e.g., MYR).Maximum string length: 3
int64
The transaction payment value returned in pure integer units (e.g., 1000 is equivalent to 10.00 for the backend processing rules).
string
Unique CommercePay Transaction Number mapped internally for auditing.Maximum string length: 24
integer
The primary identity mapping identifier. Corresponds to the id from the response of the API Get Channel List.
integer
Defines how you present the payment to the customer. Check this value first, because it decides which of the other fields you use.Which values you receive depends on the channel. See the Channel List.
string
The target link for the payment. For redirectionType 1 it’s the page to send the customer to. For 4 and 6 it holds the QR code link or payment link instead.
string
Script to render in the customer’s browser. Only set when redirectionType is 2, otherwise null.
string
Token that identifies this transaction on CommercePay’s hosted payment page. It’s always returned, so you don’t need to parse it out of redirectUrl, which may point to the payment provider instead.
string
Base64-encoded QR code image. Only set for QR channels (redirectionType 4 or 6, channel dependent), otherwise null.
integer
How many seconds the payment stays valid from the time of this response, for example how long a QR code can be scanned. Only set for channels with a short validity period (QR channels and some card channels), otherwise null. Use transactionExpired for the exact deadline.
int64
Payment serial number the customer quotes at the counter. Only set when redirectionType is 5, otherwise null.
string
Deadline for completing the payment as an ISO 8601 date-time. It can be null when the channel doesn’t report one.
Fields that don’t apply to the channel are returned as null.

Response Payload Sample

Response_2XX
For QR channels, redirectionType is 4 or 6 and the QR fields are filled in:
Response_2XX_QR

Error Responses

Response_400