Checkout Mode

Local Acquiring

Checkout Mode

In checkout mode, after a user places an order, they are directed to the PayCools checkout page, where they select a payment method and complete the payment. The checkout page displays the payment methods available for the current order, so you do not need to build your own payment method selection page, which reduces integration work.

Overview

In checkout mode, PayCools renders the payment page, and users select a payment method (such as QR or EWALLET) on the PayCools checkout page themselves. Merchants only need to obtain the checkout link and redirect the user; there is no need to develop your own payment page.

The API can restrict multiple payment methods: Merchants can specify which payment methods are supported in the order creation API, such as "QR + EWALLET" or "QR" only.
Users choose themselves: After opening the checkout page, users see the available payment methods on the page and select one to complete the payment.
The checkout page is provided by PayCools: This is a responsive H5 page maintained by PayCools, supporting multiple languages and adaptive layouts across devices.

Use Cases

Fast time to market: Avoid spending significant time developing a payment page and use PayCools' mature checkout directly.
Multiple payment methods: Let users choose their own payment method rather than locking the merchant into a single payment method in the API.
PC / H5 pages: Users open the page from a PC or mobile browser, and the checkout adapts to the device size.

Interaction Flow

Checkout Features

Responsive design: Automatically adapts to different screens such as PC, mobile, and tablet.
Multi-language: Displays the corresponding language version based on the user's browser language or the language specified in the API.
Payment method list: Dynamically displays the corresponding payment options based on the payment method types specified in the API.
Customizable styling: Supports customizing the checkout logo.

Integration Steps

1. Create a Checkout

Create a checkout on your server and submit the order information. Below are example requests and responses for creating a checkout. View API documentation

Create Checkout Request Example

curl --location --request POST 'https://globalapi-dev.paycools.com:8902/open-api/payment/checkout/generate' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appId": "your appId",
    "sign": "********************************",
    "param": "{\"timestamp\":1790662526,\"mchOrderId\":\"NSDdgrVwhA4DTYEyMNtHWIH14hh\",\"countryCode\":\"PH\",\"currency\":\"PHP\",\"settlementCurrency\":\"PHP\",\"channelTypeList\":null,\"channelCodeList\":null,\"amount\":5000,\"customerName\":\"test\",\"email\":\"test@example.com\",\"mobile\":\"09234567890\",\"notifyUrl\":\"https://test.com\",\"redirectUrl\":\"https://test.com\"}"
}'

Create Checkout Response Example

{
  "code": 10000,
  "message": "Success",
  "data": {
    "checkoutId": "CH2104817245258649600",
    "checkoutUrl": "https://globalapi-dev.paycools.com:8904/cashier/checkout/SZGYAPSYaC9e9R0lDHtX9OOiFGSgMSjwjVPuV5DLEEY=",
    "status": "PENDING",
    "expiresTime": "2026-09-29 14:45:11"
  }
}

2. Open the Checkout Page

After the checkout is created successfully, direct the user to the PayCools checkout page. The user selects a payment method on the checkout page and completes the payment by following the on-screen instructions.

3. Confirm the Payment Result

After the user completes the payment, you can confirm the payment status in the following ways:

Receive payment result notifications: PayCools sends the payment result to the notification URL you configured. After receiving the notification, please complete signature verification according to the corresponding notification documentation and update the order status.
Actively query the payment result: If you do not receive a notification or need to confirm the payment status again, you can query the corresponding payment record.

Please rely on the payment result notification or active query as the source of truth. The user returning to your page does not mean the payment has succeeded.

API Description

In checkout mode, merchants need to call the PayCools checkout API to obtain the checkout link. Key parameters of the order creation API include:

Parameter	Description
mchOrderId	Merchant order ID (unique)
countryCode	Transaction country, e.g.: PH
currency	Currency; for Local Acquiring, it must correspond one-to-one with the transaction country, e.g.: PHP
settlementCurrency	Settlement currency; for Local Acquiring, it must correspond one-to-one with the transaction country, e.g.: PHP
channelTypeList	Channel types; multiple can be specified to restrict the channel types available on the checkout page, e.g. "QR + EWALLET"
channelCodeList	Restricts the specific channels used; if provided, channelTypeList is required
amount	Order amount
customerName	Payer's name
email	Payer's email
mobile	Payer's mobile number
notifyUrl	Asynchronous payment result notification URL
redirectUrl	URL the user is redirected back to on the merchant's site after payment is completed
expireSeconds	Checkout expiration time (seconds), up to 86400 (1 day); after timeout, the checkout status changes to CLOSED

note

For personal information parameters such as the payer's name, email, and mobile number, PayCools currently does not verify their authenticity (it does not check whether the number actually exists or is registered), but it does validate the format; please pass them in the correct format for the corresponding country/region. For mobile number formats by country/region, refer to Payment General Rules.

For complete API parameter descriptions, signature rules, and request/response examples, refer to the API documentation.

Response content: The API returns a cashierUrl, which the merchant must provide to the user.

Checkout Order Statuses and Integration Recommendations

Checkout Order Statuses

The status return parameter of the checkout query API can take the following values:

Status	Meaning	Description
`PENDING`	Pending payment	The user has not yet completed payment; the user can continue and pay with any available payment method
`PAID`	Payment successful	The checkout automatically redirects to the payment success page, and the order is finalized
`CLOSED`	Closed	The checkout has expired or the merchant closed it manually; no new payment transactions can be created through this checkout, but transactions generated before closing may still be payable

Use the Checkout Order Status as the Source of Truth

In checkout mode, multiple payment results generated by the user within the checkout are ultimately aggregated onto the checkout order (checkoutId). It is recommended that merchants use the checkout order status as the source of truth, rather than treating intermediate results of a single payment method as the final order status.

The reason is that the checkout allows users to select different payment methods multiple times within the same order to complete payment, and some channels inherently have no "failed" status; a failed payment is essentially equivalent to "not yet paid" and should not prevent the user from switching to another payment method to continue paying. Therefore, when a single payment method fails, PayCools will not close the checkout order, and the order status remains PENDING.

Payment Result Callbacks

In checkout mode, payment result callbacks are sent only for successful transactions; when a payment method fails, PayCools will not send a callback.

The reason is that after a payment method fails, the user can still continue and pay with another payment method, so the merchant will not be notified of "order payment failed" due to a single payment method failure. If merchants are concerned about missing payments, they can confirm the transaction result after the checkout order status becomes PAID, or actively via the payment query API.

Callback delivery and retries follow unified rules (HTTP 200 as the success criterion, retry frequency and time limits after failure, etc.); see Payment General Rules · Callback Notification Rules for details.

Scenarios Triggering CLOSED

CLOSED indicates that the checkout order has been closed: no new payment transactions can be created through this checkout, but transactions generated before closing that are still within their validity period may still be payable. This typically occurs in the following two scenarios:

Checkout expired: The validity period is controlled via the expireSeconds parameter when creating the checkout (up to 86400 seconds, i.e. 1 day); after the validity period expires, the checkout status changes to CLOSED.
Merchant manual closure: You can call the checkout closure API to close the order manually; after closing, the status changes to CLOSED.

Behavior After Successful Payment

After the user pays successfully, the checkout status changes to PAID and the checkout redirects to the payment success page; at this point the checkout order is finalized, and the user can no longer create new payment transactions through this checkout.

Only in one rare scenario can "multiple paid transactions correspond to a single checkout order": the user selected payment methods multiple times on the checkout before paying, generating multiple transactions, and subsequently completed payment for more than one of them. In such cases, merchants only need to reconcile based on the checkout order status; if end users raise feedback about this, handle it through the customer complaint process.

note

On the merchant side, orders should be updated based on the checkout order status (PENDING / PAID / CLOSED) and payment result notifications: the checkout only sends callbacks for successful transactions, a single channel failure will not trigger a callback, and you should not close the entire order due to a single payment method failure. For a checkout creation example, see "Integration Steps" above.

Integration Prerequisites

Before using checkout mode, make sure that:

You have completed public key configuration in the Merchant Dashboard and obtained the AppID and platform public key
You understand the signature and verification mechanism; API calls must include sign in the request parameters
You have reviewed the environment information and confirmed the request URLs
You have prepared the endpoint for receiving asynchronous payment result notifications (Notify URL)