Payment General Rules
Payment General Rules
This page summarizes the general rules for PayCools payment APIs. It currently includes parameter format conventions (such as phone numbers), as well as the unified callback notification rules for both Checkout Page mode and direct API integration. Please follow the conventions on this page when calling APIs such as order creation, collection, and payout. More general logic, parameters, and definitions will continue to be documented on this page over time.
Phone Number Format
The following are the phone number format conventions for each country/region. PayCools currently does not verify phone number authenticity (it does not check whether the number actually exists or is registered), but it does validate the format (prefix and length); incorrect formats will result in API errors or rejection.
| Country/Region | Prefix | Total Length | Description |
|---|---|---|---|
| Philippines | 09 | 11 | Starts with 09, 11 digits total |
| Indonesia | 08 | 10–13 | Starts with 08, 10–13 digits total |
| Malaysia | 01 | 10–11 | Starts with 01, 10–11 digits total |
| Thailand | 06 / 08 / 09 | 10 | Starts with 06, 08, or 09, 10 digits total |
| Vietnam | 03–09 | 10 | Starts with 03–09 (not 0, 1, or 2), 10 digits total |
| Russia | 9 | 10 | Starts with 9, 10 digits total (excluding country code 7) |
| Saudi Arabia | 05 | 10 | Starts with 05, 10 digits total |
| UAE | 05 | 10 | Starts with 05, 10 digits total |
| Qatar | 3 / 5 / 6 / 7 | 8 | Starts with 3, 5, 6, or 7, 8 digits total |
| Kuwait | 41 / 5 / 6 / 9 | 8 | Starts with 41, 5, 6, or 9, 8 digits total |
| Oman | 7 / 9 | 8 | Starts with 7 or 9, 8 digits total |
| Bahrain | 3 / 66 / 69 | 8 | Starts with 3, 66, or 69, 8 digits total |
| Mexico | 52 | 12 | Always starts with country code 52, the 3rd digit is 1–9, 12 digits total |
| Colombia | 57 | 12 | Always starts with country code 57, followed by a 10-digit local number, 12 digits total |
| Argentina | — | — | Format is not validated at present; the value is passed through to the channel as-is |
Callback Notification Rules
Callback notifications are used to sync transaction results to merchants. Both Checkout Page mode and direct API integration follow the unified delivery and retry rules below:
- Callback result is determined by the HTTP status code: PayCools does not parse the content of the callback response body (
body); if the merchant returnsHTTP 200upon receiving the callback, the callback is considered successful and PayCools will not retry the callback. In exceptional cases, please return a non-200 status code. - Retry frequency: After a failed callback (non-200 response), notifications are sent once per minute for the first 10 minutes, then once per hour after 10 minutes.
- Callback time limit: For transactions older than 1 day, automatic callbacks based on status codes will no longer be sent.
Please note that different products have different policies regarding failed event callbacks: Checkout Page mode only callbacks for successful transactions, while direct API integration callbacks for both successful and failed transactions. Please refer to the corresponding product documentation.
API Response Codes
The code and message returned in real time by the API, used to indicate the processing result of the request.
General API Response Codes
| code | message | Description |
|---|---|---|
| 10000 | Success | Request successful |
| 21000 | Server error, Please try again later. | Server error, please try again later |
| 21001 | Request sign error | Request signature verification failed |
| 21002 | Request param error | Invalid request parameters |
| 21003 | Request appId error | appId error |
| 21004 | Merchant is unavailable | Merchant is unavailable |
| 21005 | Merchant channel is unavailable | Merchant channel is unavailable |
| 21006 | Merchant transaction not found | Merchant transaction not found |
| 21007 | Duplicate merchant order id | Duplicate merchant order id |
| 21008 | Request timestamp error | Invalid request timestamp |
| 21009 | Request timestamp error | Invalid request timestamp |
| 21010 | The amount exceeds the limit | Amount exceeds the limit |
| 21011 | Network error | Network error |
| 21012 | Request bank code error | Invalid bank code |
| 21013 | Request wallet code error | Invalid wallet code |
| 21014 | Merchant balance insufficient | Insufficient merchant balance |
| 21015 | Duplicate idempotencyId | Duplicate idempotencyId |
| 21016 | Merchant ip forbidden | Merchant IP is not whitelisted |
| 21017 | Merchant has not opened this national service | Merchant has not enabled service for this country/region |
| 21018 | Request transfer code error | transferCode error |
| 21019 | Request pay method code error | payMethodCode error |
| 21020 | Too many requests, please retry later. | Too many requests, please retry later |
| 21021 | Transaction Amount Invalid | Invalid transaction amount |
| 21022 | Transaction Volume Limit | Transaction count exceeds the limit |
| 21023 | Transaction create failed | Transaction creation failed |
| 21024 | Invalid access token | Invalid access token |
| 21025 | Not allowed to cancel | Cancellation not allowed |
| 21026 | Customer Balance not enough | Insufficient customer balance |
| 21027 | Transaction creation exceeds limit | Transaction creation exceeds the limit |
| 21028 | Transaction already paid or closed | Transaction already paid or closed |
| 21050 | Business unit not found | Business unit not found |
| 21051 | Business unit does not belong to this merchant | Business unit does not belong to this merchant |
| 21056 | Cross region business is not allowed for this merchant | Cross-region business is not allowed for this merchant |
Refund API Response Codes
| code | message | Description |
|---|---|---|
| 21401 | Refund is processing | Refund is processing |
| 21402 | Not allowed to refund | Refund not allowed |
| 21403 | Transactions 60 days ago cannot initiate refunds | Refunds cannot be initiated for transactions older than 60 days |
| 21404 | The original transaction channel not support full refund | The original transaction channel does not support full refund |
| 21405 | The original transaction channel not support partial refund | The original transaction channel does not support partial refund |
| 21406 | Refund amount invalid | Invalid refund amount |
| 21407 | MchRefundOrderId is repeat | Duplicate refund order id |
| 21408 | The original transaction is not completed | The original transaction is not completed |
| 21409 | The original transaction already exist pending refund | The original transaction already has a pending refund |
Void API Response Codes
| code | message | Description |
|---|---|---|
| 21500 | Original transaction status is not success | The original transaction status is not success |
| 21501 | Cannot reverse | Cannot reverse |
| 21502 | Original transaction has been settled | The original transaction has been settled |
| 21503 | Cannot void over the day | Voiding across days is not supported |
| 21504 | Original transaction has been already voided | The original transaction has already been voided |
| 21505 | Duplicate mchVoidOrderID detected. Please provide a unique mchvoidOrderID and retry. | Duplicate void order id. Please use a unique order id and retry |
For the complete list of prompt codes and descriptions, please refer to General API Prompt Codes.