> ## Documentation Index
> Fetch the complete documentation index at: https://doc.haipay.net/llms.txt
> Use this file to discover all available pages before exploring further.

# HaiPay Error Codes and Error Response Reference

> Error Response

## Response Structure

| Field | Type | Description |
| :- | :- | :- |
| status | String | Call result: `1` success, `0` failure |
| error | String | `00000000` on success; the corresponding error code on failure (see table below) |
| msg | String | Result description: empty string on success; error text on failure |
| data | Object | Business data: `null` on failure |

<Warning>
  The `error` field is not a fixed contract:

  * **Meaning varies by response source**:
    * API responses: on failure, `status="0"` and `error` carries the corresponding error code (see the scenario sections on this page);
    * Merchant console and checkout page responses: on failure, only `status` is `"0"` while `error` remains `00000000` (identical to the success value), with the message text in `msg`;
    * Order outcomes: when an order fails, the query API still returns `status="1"` and `error="00000000"`, with the actual outcome in `data.status` and `data.errorMsg`
  * **Subject to change at any time**: error codes and messages may be added, adjusted, or change meaning in any release; do not use `error` code values or `msg` texts directly to determine business outcomes.
</Warning>

**Success Response**

```json theme={null}
{
  "status": "1",
  "error": "00000000",
  "msg": "",
  "data": {}
}
```

**Failure Response (missing a required parameter)**

```json theme={null}
{
  "status": "0",
  "error": "1002",
  "msg": "The field 'name' is required",
  "data": null
}
```

## Error Code Overview

| Error Code | Scenario | Description |
| :- | :- | :- |
| `1001` | Missing required parameter | A required field is missing or empty |
| `1002` | Invalid parameter / business validation failed | Most common: validation failures for parameter format, amount, account, order, etc. |
| `1003` | System exception | Internal service error. **The order may already be recorded; wait for the async notification or query the order to confirm the final status.** Do not treat it as a failure outright. |
| `1004` | System busy | System busy or processing timeout. **The order may already be recorded; wait for the async notification or query the order to confirm the final status.** You may retry later. |
| `2001` | Exchange rate not configured | The exchange rate for the requested currency is not configured |
| `2002` | Exchange rate query not enabled | The merchant has not enabled exchange rate query |
| `4031` | IP not authorized / region restricted | The request IP is not in the allowlist, or the region is restricted |
| `4038` | Merchant capability restricted | Collection/disbursement capability not enabled, or onboarding status restricted |
| `70000102` | Request format incorrect | Content-Type or request payload cannot be parsed |
| `70000103` | Missing token / JSON format error | Missing token, or the request body JSON is malformed |

## Errors by Scenario

### Signature, Authentication & Access

| Error Code | Error Message | Description |
| :- | :- | :- |
| `1002` | `Invalid request signature` | Signature verification failed. Check the signature algorithm, the fields included and their ordering, the encoding, and whether the public/private keys match. |
| `70000103` | `Miss token.` | Missing access token. Carry the correct token per the API instructions and retry. |
| `70000102` | `Request format incorrect.` | Request format error. Ensure `Content-Type: application/json` and that the payload is parseable. |
| `70000103` | `json format incorrect.` | The request body JSON is malformed. Validate the JSON and retry. |
| `4031` | `client ip is in a region where access is forbidden` | The request IP's region is restricted. Confirm the region and network environment of the server making the request. |
| `4031` | `<your-ip> not in ip white list` | The request IP is not in the allowlist. Configure the server egress IP allowlist in the merchant portal and retry. |
| `1002` | `ip error` | Request IP validation failed; contact support |

**Signature Failure Example**

```json theme={null}
{
  "status": "0",
  "error": "1002",
  "msg": "Invalid request signature",
  "data": null
}
```

### Merchant Capability & Onboarding Status

| Error Code | Error Message | Description |
| :- | :- | :- |
| `4038` | `Your acquiring capability is restricted. Please check your onboarding status or contact customer support.` | Collection capability restricted. Check your onboarding/activation status, or contact HaiPay support. |
| `4038` | `Your disbursement capability is restricted. Please check your onboarding status or contact customer support.` | Disbursement capability restricted. Check your onboarding/activation status, or contact HaiPay support. |

### Missing Required Parameters

Provide the missing required field(s) and retry. Field names depend on the specific API.

| Error Code | Error Message | Description |
| :- | :- | :- |
| `1002` | `The field 'name' is required` | Name is empty |
| `1002` | `The field 'email' is required` | Email is empty |
| `1002` | `The field 'accountNo' is required` | Account number is empty |
| `1002` | `The field 'phone' is required` | Phone number is empty |
| `1002` | `The field 'bankCode' is required` | Bank code is empty |
| `1002` | `The field 'subject' is required` | Subject (order title / product name) is empty |
| `1002` | `The field 'orderNos' is required` | Order number list is empty (batch query / voucher download scenarios) |
| `1001` | `The field 'partnerUserId' is required` | Partner user ID is empty |
| `1002` | `Email cannot be empty` / `Phone number cannot be empty` | Recipient email / phone number is empty |
| `1001` | `Account number cannot be empty` | Account number is empty |
| `1002` | `Account information should not be empty.` | Recipient account information is incomplete (account number or name missing) |
| `1001` | `The field 'accountType' is required` | Missing account type |
| `1001` | `The field 'amount' is required` | Missing amount |
| `1001` | `The field 'appId' is required` | Missing appId |
| `1001` | `The field 'inBankCode' is required` | Missing bank code |
| `1001` | `The field 'payType' is required` | Missing payment type |
| `1001` | `The field 'sign' is required` | Missing signature |

### Invalid Parameter Format

The field format, length, or value does not meet requirements. Correct it per the field rules on the corresponding API page.

| Error Code | Error Message | Description |
| :- | :- | :- |
| `1002` | `Invalid format for field 'phone'` | Invalid phone number format |
| `1002` | `Invalid format for field 'email'` | Invalid email format |
| `1002` | `Invalid format for field 'accountNo'` | Invalid account number format |
| `1002` | `Invalid format for field 'payType'` | Invalid payment method value |
| `1002` | `Invalid format for field 'country'` | Invalid country/region value |
| `1002` | `Invalid format for field 'CPF'` / `'ifsc'` / `'bankcode'` | Invalid ID / IFSC / bank code format |
| `1001` | `Invalid format for field 'partnerUserId'` | Invalid merchant user ID format |
| `1002` | `Amount format is invalid` | Invalid amount format |
| `1002` | `IBAN format is invalid.` / `Swift code is invalid.` | Invalid IBAN / Swift format |
| `1002` | `Invalid CLABE account number format or check digit` | Invalid CLABE account number format or check digit |
| `1002` | `The name can only contain English letters and spaces` | The name may only contain English letters and spaces |
| `1002` | `The name contains at least firstName and lastName, separated by spaces` | The name must include a first and last name, separated by a space |
| `1002` | `The firstName and lastName can't be the same` | The first and last name cannot be the same |
| `1002` | `birth is not a valid date` / `gender is not valid` | Invalid date of birth / gender |
| `1002` | `idCard must be 13 digits` | Invalid ID number length |
| `1002` | `accountNo must be 11 digits starting with 0` | Invalid account number length/prefix |
| `1002` | `recipient_account length must be 16 or 18 digits` | The recipient account must be 16 or 18 digits |
| `1002` | `Invalid format for field  'callBackUrl'` | Invalid callback URL format |
| `1002` | `Invalid format for field  'clientIp'` | Invalid client IP format |
| `1002` | `Invalid format for field  'notifyUrl'` | Invalid notify URL format |
| `1002` | `Invalid format for field 'amount'` | Invalid amount format |
| `1002` | `Invalid format for field 'callBackFailUrl'` | Invalid failure callback URL format |
| `1002` | `Invalid format for field 'cancelUrl'` | Invalid cancel URL format |
| `1002` | `Invalid format for field 'customerIp'` | Invalid customer IP format |
| `1002` | `Invalid format for field 'orderNo'` | Invalid order number format |
| `1002` | `Please configure the merchant public key` | Merchant public key not configured; complete key configuration in the merchant console first |
| `1002` | `orderId is too long` | Order ID exceeds 48 characters |
| `1002` | `partnerUserId is too long` | Partner user ID exceeds 64 characters |
| `1002` | `partnerUserId must be either numbers, lowercase letters, uppercase letters, or common symbols` | Partner user ID allows only digits, letters and common symbols |
| `1002` | `phone is too long` | Phone number exceeds 20 characters |

### Amount & Limits

| Error Code | Error Message | Description |
| :- | :- | :- |
| `1002` | `Amount is outside the allowed range` | The amount is outside the allowed range for this market/payment method. Check the limits on the corresponding country API page and adjust. |
| `1002` | `Amount decimal places cannot exceed 2` | The amount has more than 2 decimal places. Adjust per the currency precision (some currencies do not support decimals). |
| `1002` | `Amount does not support decimal places` | The currency does not support decimal amounts. |
| `1002` | `Amount must be an integer` | The amount must be an integer. |

**Amount Limit Exceeded Example**

```json theme={null}
{
  "status": "0",
  "error": "1002",
  "msg": "Amount is outside the allowed range",
  "data": null
}
```

### Recipient Account Info (Disbursement)

| Error Code | Error Message | Description |
| :- | :- | :- |
| `1002` | `please put the right accountNo` | Invalid recipient account number |
| `1002` | `please put the right name` | Invalid recipient name |
| `1002` | `The field 'accountType' only supports EWALLET` | Only the EWALLET account type is supported in this scenario |
| `1002` | `please put the more than 14 characters accountNo when accountType is BANK_CARD` | The account number is too short for the BANK\_CARD type |
| `1002` | `BANK_CARD Number must be input when recipient_account is 16 digits` | A bank card number must be provided when recipient\_account is 16 digits |
| `1002` | `BANK_ACCOUNT Clabe must be input when recipient_account is 18 digits` | A CLABE must be provided when recipient\_account is 18 digits |

### Order Related

| Error Code | Error Message | Description |
| :- | :- | :- |
| `1002` | `order not Exist or do not config callBackUrl` | The order does not exist, or the callback URL is not configured |
| `1002` | `orderNos can not exceed 100` | A batch query cannot exceed 100 order numbers |
| `1002` | `please request the right url` | Incorrect request URL |
| `1002` | `getfee is error, must 0, 1 or none` | The disbursement query parameter `getfee` must be 0, 1, or omitted |
| `1002` | `isamount is error, must 0, 1 or none` | The disbursement query parameter `isamount` must be 0, 1, or omitted |
| `1002` | `order already exist` | Order ID already exists; do not resubmit |
| `1002` | `order not exist` | Order does not exist |

### Key & Encryption Configuration

| Error Code | Error Message | Description |
| :- | :- | :- |
| `1002` | `Public key is not configured.` | The public key is not configured in the merchant portal. Complete key configuration first. |
| `1002` | `Private key is not configured.` | The private key is not configured. Complete key configuration first. |
| `1002` | `The public and private keys do not match.` | The public and private keys do not match. Regenerate and upload a matching key pair. |
| `1002` | `decryption failed.` / `encryption failed.` / `signing failed.` | Decryption/encryption/signing failed. Check the key and algorithm configuration. |

### Exchange Rate Query

| Error Code | Error Message | Description |
| :- | :- | :- |
| `2001` | `exchange rate is not configured` | The exchange rate for the requested currency is not configured. Contact HaiPay support. |
| `2002` | `current user has not enabled exchange rate query` | Exchange rate query is not enabled |
| `1004` | `rate error` | Failed to get the exchange rate. Retry later. |
| `1001` | `The field 'currency' is required` | Missing currency |
| `1001` | `The field 'sourceCurrency' is required` | Missing source currency |
| `1001` | `The field 'targetCurrency' is required` | Missing target currency |
| `1002` | `payType and inBankCode must be provided together` | payType and inBankCode must be provided together |
| `1002` | `please send right currency` | Requested currency does not match business configuration |
| `1002` | `the app does not support this currency.` | The application does not support this currency |

### Payment Method & Bank Code

| Error Code | Error Message | Description |
| :- | :- | :- |
| `1002` | `Field 'bankcode' is invalid or the specified bank is not supported` | The bank code is invalid or the bank is not supported |
| `1002` | `Invalid format for field 'bankcode'` | Invalid bank code format |
| `1002` | `please specify the MXN payment method (OXXO or PAYCASH)` | For MXN, specify the payment method (OXXO or PAYCASH) |

### Application (appId)

| Error Code | Error Message | Description |
| :- | :- | :- |
| `1002` | `Application ID not found` | The appId does not exist. Verify the appId obtained from the portal. |
| `1002` | `Application ID is disabled` | The appId is disabled. Contact HaiPay support. |

### System Busy & Processing Timeout

| Error Code | Error Message | Description |
| :- | :- | :- |
| `1003` | `system exception` | Internal system error. Retry with the same `orderId` using exponential backoff to avoid duplicate orders. |
| `1004` | `system is busy` | System busy or processing timeout. Retry later; for fund-related operations, query the final order status first. |

### Voucher / PDF Generation

| Error Code | Error Message | Description |
| :- | :- | :- |
| `1002` | `PDF generation failed: PDF data is empty` | Voucher data is empty. Retry later; if it keeps failing, contact support. |
| `1002` | `PDF generation failed: response data is null` | No data returned for voucher generation. Retry later. |
| `1001` | `The field 'orderNo' is required` | Missing order number |
| `1002` | `PDF generation failed` | Voucher PDF generation failed; retry later |
| `1002` | `The order was not successful` | Only successful orders can generate vouchers |

### Subscription

| Error Code | Error Message | Description |
| :- | :- | :- |
| `1001` | `The field 'country' is required` | Missing country/region |
| `1001` | `The field 'recurringInterval' is required` | Missing recurring interval type (D/W/M/Y) |
| `1001` | `The field 'recurringIntervalCount' is required` | Missing recurring interval count |
| `1001` | `The field 'recurringMaxNumber' is required` | Missing maximum recurring number |
| `1001` | `The field 'subscriptionNo' is required` | Missing subscription number |
| `1001` | `The field 'subscriptionOrderId' is required` | Missing merchant subscription order ID |
| `1001` | `The field 'website' is required` | Missing website |
| `1002` | `Coupon amount per period cannot be greater than order amount` | Coupon amount per period cannot exceed order amount |
| `1002` | `Invalid format for field  'recurringInterval'` | Invalid recurring interval type (D/W/M/Y only) |
| `1002` | `Invalid format for field 'couponAmountPerPeriod'` | Invalid coupon amount per period |
| `1002` | `Invalid format for field 'couponPeriod'` | Invalid coupon period |
| `1002` | `Invalid format for field 'recurringIntervalCount'` | Recurring interval count must be a positive integer |
| `1002` | `Invalid format for field 'recurringMaxNumber'` | Maximum recurring number must be a positive integer |
| `1002` | `Invalid format for field 'retryTimes'` | Retry times must be >= 0 |
| `1002` | `Invalid format for field subscriptionNo` | Invalid subscription number format |
| `1002` | `The amount can have at most two decimal places` | Subscription amount allows at most two decimal places |
| `1002` | `The couponAmountPerPeriod can have at most two decimal places` | Coupon amount per period allows at most two decimal places |
| `1002` | `The final payment amount must be greater than or equal to the minimum subscription amount` | Final payment amount must be >= minimum subscription amount |
| `1002` | `The subscription period cannot exceed three years` | Subscription period cannot exceed three years |
| `1002` | `coupon param error` | Coupon params invalid: period and amount must be both present or both absent |
| `1002` | `couponPeriod must equal 1 or be equal to recurringMaxNumber` | Coupon period supports first period or full term only |
| `1002` | `subscriptionOrderId is too long` | Subscription order ID exceeds 48 characters |

### Refunds

| Error Code | Error Message | Description |
| :- | :- | :- |
| `1002` | `Refund order do not exist` | Refund order does not exist |
| `1002` | `Refund order refundType is wrong` | Refund type not supported for query |
| `1002` | `The Refund order has been refunded` | Refund order already refunded or in progress |
| `1002` | `The Refund order refundFee is wrong` | Invalid refund fee |
| `1002` | `The order has exceeded 180 days` | Orders older than 180 days cannot be refunded |
| `1002` | `The order status is not success` | Only successful orders can be refunded |
| `1002` | `The refund application number cannot be duplicated with the original transaction number` | Refund application No. must differ from the original transaction No. |
| `1002` | `account is null` | Merchant balance account not found; contact support |
| `1002` | `request param is wrong[orderId or refundNo Cannot all be empty]` | Merchant refund No. and platform refund No. cannot both be empty |
| `1002` | `update account is fail` | Balance update failed; query order status later |

### Balance & Deductions

| Error Code | Error Message | Description |
| :- | :- | :- |
| `1002` | `Account balance is not enough` | Insufficient merchant account balance (payout, refund, etc.) |
| `1002` | `Failed to update account balance.` | Balance deduction or ledger creation failed; query order status later |
| `1002` | `The order amount is not enough to deduct the merchant fee` | Order amount insufficient to cover merchant fee |

### Reconciliation Files

| Error Code | Error Message | Description |
| :- | :- | :- |
| `1001` | `The field 'date' is required` | Missing reconciliation date |
| `1001` | `The field 'type' is required` | Missing reconciliation file type (15 payout / 20 collection / 40 statement) |
| `1002` | `Unsupported file type` | Reconciliation file type supports 15/20/40 only |

### Global Cashier

| Error Code | Error Message | Description |
| :- | :- | :- |
| `1002` | `Cashier not configured` | Cashier not configured; contact support |
| `1002` | `Invalid format for field orderNo` | Invalid order number format |
| `1002` | `partnerUserId is blocked"` | This partner user ID is blocked; contact support |
| `1002` | `please request the right currency` | Requested currency does not match business configuration |
| `1002` | `Missing KYC configuration URL` | Onboarding verification configuration incomplete; contact support |

## Merchant Console Common Errors

The messages in this section appear when signing in to and operating the merchant console (they are not API response payloads). Follow the descriptions below; if the issue persists, contact HaiPay support with the message and error code. Codes here are console-service codes, a separate system from API error codes (1001/1002…); `—` means the message carries no discriminating code.

### Login & Session

| Error Code | Error Message | Description |
| :- | :- | :- |
| `2023` | `user do not exist or password is incorrect.` | Username does not exist or password is incorrect |
| `2020` | `user has been deactivated, please contact customer service.` | Account deactivated. Contact support |
| `2021` | `password error '<n>' times, account locked for '<m>' minutes, please contact customer service` | Too many password errors; account locked for the shown minutes. Retry later or contact support |
| `—` | `verification failed. please refresh and try again.` | Page security verification failed. Refresh and retry |
| `2005` | `login status has expired, need to log in again.` | Login session expired. Log in again |
| `2028` | `we detected that your account was logged in on another device. for your security, this session has been terminated.` | Account logged in on another device; this session was terminated for security. Change your password if this was not you |

### Security Verification (MFA & Codes)

| Error Code | Error Message | Description |
| :- | :- | :- |
| `2014` | `please enter the email verification code` | Enter the email verification code |
| `2012` | `please enter the correct email verification code` | Incorrect email verification code. Check and re-enter |
| `2017` | `email authenticator not bind, please contact the customer service` | Email authenticator not bound. Contact support |
| `2008` | `please enter the verification code` | Enter the authenticator code |
| `2009` | `please enter the correct verification code` | Incorrect authenticator code. Check and re-enter |
| `2010` | `please bind authenticator` | Bind an authenticator first |
| `—` | `operation failed, please complete the verification first` | Complete the preceding verification step first |
| `—` | `failed to generate qr code` | Failed to generate the authenticator QR code. Refresh and retry |

### Password Management

| Error Code | Error Message | Description |
| :- | :- | :- |
| `2042` | `user does not exist.` | Account does not exist. Check the username |
| `—` | `please refresh and try again.` | Window credential mismatch (page state expired). Refresh and retry |
| `—` | `failed to change password, passwords do not match` | New password and confirmation do not match |
| `—` | `failed to change password, user does not exist` | Target account does not exist |
| `—` | `failed to change password, old password is wrong` | Old password is incorrect |

### Sub-accounts & Permissions

| Error Code | Error Message | Description |
| :- | :- | :- |
| `—` | `add '<username>' failed, record already exists` | Sub-account name already exists |
| `—` | `edit '<username>' failed, record already exists` | The new sub-account name already exists |
| `—` | `no permission to update user` | No permission to modify this sub-account |
| `2042` | `user does not exist` | Sub-account does not exist |
| `—` | `not allow edit the user` | Target account is not your sub-account; operation not allowed |
| `—` | `the current user type is not supported!` | Current account type does not support sub-account management |
| `—` | `employee illegal modification` | Current account type lacks this permission |
| `—` | `no permission` | Current account type lacks this permission |

### Batch Payout & Vouchers

| Error Code | Error Message | Description |
| :- | :- | :- |
| `—` | `amount is not right` | Invalid payout amount |
| `—` | `the current currency does not support` | Currency not supported for batch payout |
| `—` | `if the account amount is the same within five minutes, the transaction cannot be initiated` | Same amount to the same recipient within 5 minutes is blocked. Retry later |
| `—` | `this area is not supported at this time` | Region or currency not supported for batch payout currently |
| `—` | `please upload normal file format` | Batch payout file supports xlsx only |
| `—` | `file reading exception` | Failed to read the batch file. Check and re-upload |
| `—` | `transaction does not exist` | Payout order does not exist; voucher unavailable |

### Files & Export Center

| Error Code | Error Message | Description |
| :- | :- | :- |
| `—` | `the file must be smaller than 200mb` | File must be smaller than 200MB |
| `—` | `upload file error, please put right usefor` | Upload failed. Check file type and purpose, then retry |
| `—` | `invalid taskid` | Export task not found. Re-initiate the export |
| `—` | `data export does not exist` | No export record found |
| `—` | `data export is not complete, please try again later` | Export not complete. Retry later |
| `—` | `data export failed, unable to send download link email` | Export failed; download email not sent. Retry |
| `—` | `the maximum number of download link emails sent has reached 3 times` | Download link email limit (3) reached |

### Console Preferences

| Error Code | Error Message | Description |
| :- | :- | :- |
| `—` | `the timezone is not supported` | Selected timezone not supported |
| `—` | `unrecognised key` | Setting key not supported; only timezone is configurable |

### Others

| Error Code | Error Message | Description |
| :- | :- | :- |
| `5003` | `system exception` | Temporary console error. Retry later; contact support if it persists |

## Checkout Page Common Errors

Errors in this section are shown on the **checkout / payment link / redirect payment pages** and are seen by **your customers** (they are not API responses). These errors carry no dedicated error code: in JSON responses only `status` is `0` on failure while `error` remains `00000000` (identical to the success value), with the message text in `msg`; some redirect pages output plain text directly. If they persist, contact HaiPay support with the message and order number.

### Orders and Subscriptions

| Error Code | Error Message | Description |
| :- | :- | :- |
| `—` | `orderNo does not legal` | Order number format validation failed |
| `—` | `orderNo does not right` | Order number format validation failed |
| `—` | `Order does not exist` | Order does not exist |
| `—` | `order not exist` | Order does not exist |
| `—` | `The order has expired, please place another order` | The order has expired; the customer needs to place a new order |
| `—` | `The status is incorrect` | The submitted order status is invalid; only success or failure is accepted |
| `—` | `Result does not exist` | Merchant request information cannot be retrieved for the order |
| `—` | `The order is already in progress, please do not submit again` | The order is already in progress; do not submit it again |
| `—` | `subscription not found` | Subscription not found |
| `—` | `Invalid recurringInterval` | Invalid subscription interval; only day, week, month and year are supported |

### Risk Control and Exchange Rate

| Error Code | Error Message | Description |
| :- | :- | :- |
| `—` | `Sorry, your region <region> is not supported at this time. <orderNo>` | The customer's region is not supported at this time; the message includes the region and order number |
| `—` | `The exchange rate conversion is wrong, please contact customer service` | Exchange rate conversion failed; please contact customer service |

### Payment Link

| Error Code | Error Message | Description |
| :- | :- | :- |
| `—` | `The current link is invalid` | The payment link has been disabled |
| `—` | `Please add at least one currency configuration` | No business configuration exists for the selected currency |
| `—` | `Sorry, this email provider is not supported. Please use a different email address.` | The email provider is not supported; the customer needs to use a different email address |
| `—` | `Too many orders are created in a short time. Please try again later` | Too many orders were created in a short time (rate limits apply per link and per IP); try again later |
| `—` | `Currency is not supported` | The selected currency is not supported |
| `—` | `Limited capability, global checkout page is not activated. Please contact customer support.` | The global checkout page is not activated; please contact customer support |

### Information Collection and KYC

| Error Code | Error Message | Description |
| :- | :- | :- |
| `—` | `Email cannot be empty` | Email is required for this payment scenario |
| `—` | `idCard cannot be empty` | An ID number is required for this region |
| `—` | `user not found` | KYC user information not found |
| `—` | `Missing PDF configuration` | The PDF template configuration is missing when generating the KYC document; please contact customer support |
| `—` | `The data does not exist` | No user information matches the provided name and ID number |
| `—` | `The name or ID number does not match the one you previously entered. Please re-enter.` | The name or ID number does not match the previous entry; re-enter it |

### Card Payment

| Error Code | Error Message | Description |
| :- | :- | :- |
| `—` | `Enter a valid 14- to 19-digit card number.` | Invalid card number format; a 14- to 19-digit number is required |
| `—` | `Please use a card from the brands displayed` | The card BIN is not recognized; use a card from the brands displayed |

### Redirect Pages

| Error Code | Error Message | Description |
| :- | :- | :- |
| `—` | `the url is not correct, try again !` | The order number in the redirect URL is invalid |
| `—` | `this website is not allow payment, please connect the customer service!` | The referring website is not allowed to initiate payments; please contact customer service |

## Order Failure Reason (data.errorMsg)

In the `data` of collection and disbursement order query APIs, besides the order `status` (a number), there is an `errorMsg` field representing **the original failure reason of that order**. This field describes the order's own processing result and may contain text returned by the bank or the recipient.

Determine the order result from `data.status` and handle accordingly; if you need help, contact HaiPay support with the `orderNo`.

<Warning>
  Do not treat `data.errorMsg` as the API call result. The success or failure of the API call is determined by the **top-level** `status` and `error`; `data.errorMsg` describes the order's business-level processing result. They are at different layers.
</Warning>

| Failure reason | Description |
| :- | :- |
| `Your account is restricted from ordering. Please contact customer support for help.` | Account restricted from ordering due to onboarding status; contact support |
| `Your payment was declined due to security checks. Please try another card or payment method` | Declined by risk control; use another card or payment method |
| `Your payment was declined due to security checks. Please try another card or payment method.(HP)` | Same as above, suffixed variant |

## Related Topics

* [HaiPay FAQ & Troubleshooting](/docs/en/guide/frequently_asked_question)
* [HaiPay API Description and Common Rules](/docs/en/guide/api_description_guide)
* [HaiPay Integration Environment and Request URLs](/docs/en/guide/api_parameters_doc)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.