> ## 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 API Description and Common Rules

> Learn HaiPay interface types, shared fields, signing rules, callback handling, and common response structures before implementation.

If you need the short version, this page answers three things first: which integration modes HaiPay supports, which communication rules apply, and what the API request structure looks like.

## 1. Integration Methods

| Interface Type | API Documentation Path | Business Scope | Description |
| :- | :- | :- | :- |
| Global Cashier | Global (Cashier) | Global Business | One integration supports multiple payment methods worldwide. The system automatically redirects users to the corresponding country's payment page based on their IP, allowing users to choose payment methods to complete payment. |
| Local Cashier | North America, South America, Europe, Asia, Middle East, etc. | Single Country Business | Independent integration, API synchronously returns payment pages supported by specific countries for users to choose and complete payment. |
| Pure API Payment Interface | North America, South America, Europe, Asia, Middle East, etc. | Single Country Business | Independent integration, API synchronously returns relevant information for specific payment methods, facilitating customer-customized payment pages. |
| Other Payment Interfaces | Global (Credit Card Payments, Credit Card Subscriptions) | Global Business | Independent integration, API synchronously returns payment pages, credit Cards supports subscription deductions. |

## 2. Communication Protocol

When merchants integrate with HaiPay services and call the API, they must follow the rules below:

| Type | Description |
| :- | :- |
| Transmission | To ensure transaction security, HTTPS transmission is required |
| Submission | Requests must be submitted using the POST method |
| Data Format | Both requests and responses must use application/json format |
| Character Set | UTF-8 character encoding must be used |
| Signature Algo | SHA256WithRSA |
| Signature Req. | Both request and response data must be signed and verified. See [Configuration & Signature Rules](https://doc.haipay.net/docs/en/guide/config_settings_and_signature_rules_guide.md) for details |
| SSL/TLS Version | TLSv1.2, TLSv1.3 |

## 3. API Structure

Below is the structure for calling HaiPay APIs. The API name is appended to the request URL. The content inside `data` contains the concatenated payload for different business operations.

```json theme={null}
POST https://uat-interface.haipay.asia/{currency}/{api_endpoint}
{
    "appId": 1054,
    "orderId": "M233323000059",
    ...
    "sign": "af0gAHkUOyYHu9owQp8NJ4mPEeUW4vuJcjdxqLIzrVw8AvpLSjD1DXupReSG/CyuSkFRyiIvCp5u703AuGGmfgD2gKDH3Ywau41bAbG2jnHJ8mtjiSJ5iWUzanyd4Kr7d1+rETbzUl7/BkW3t0X8UUFdqpxwG8DPUjAwUKfplWDHV7koG51Ozexd80DCsmW6eWdouAZ1uNXGLYmV3ftE3BmfNRtuv1C5bfTJWrTEIOxbF6g2uYOFZTlIgrQgd7/2PsAYwQQXNz8Q8CYl4OxqCv4pXJxaLWPbR5tqZu9og5kn32C9aHW/NlU1y39vzz+4ef81yPAqUV9oHlSMSPrMmw=="
}
```

Request URL:

| Environment | URL |
| :- | :- |
| Test | [https://uat-interface.haipay.asia](https://uat-interface.haipay.asia) |
| Production | To be provided at go-live |

> [!TIP]
>
> The example request above uses the **test environment** URL. For the production URL, please contact HaiPay business support at go-live. Test and production environments use separate accounts; appId is not interchangeable.

## 4. API List

| Product | API Name | Endpoint | Description |
| - | - | - | - |
| Collection | Collection Apply | /collect/apply | User makes a payment to the merchant (Top-up) |
| Collection | Collection Query | /collect/query | |
| Refund Apply | Refund Apply | /refund/apply | |
| Disbursement | Disbursement Apply | /pay/apply | Merchant makes a payment to the user (Withdrawal) |
| Disbursement | Disbursement Query | /pay/query | |
| Account Balance | Account Query | /account/ledger | Merchant queries account balance |

For details, see [API Documentation](https://doc.haipay.net/docs/en/guide/api_doc_list.md).

## 5. Parameters

**Common Request Parameters**

| Parameter | Required | Type | Description |
| :- | :- | :- | :- |
| appId | Yes | Integer | Business ID (retrieved from the backend, must correspond to the currency in the request URL) |
| sign | Yes | String | Signature (see [Configuration & Signature Rules](https://doc.haipay.net/docs/en/guide/config_settings_and_signature_rules_guide.md)) |

**Request Example:**

```json theme={null}
{
    "appId": 1000,
    "...": "...",
    "sign": "fCywFPOojpRIPi4ph81+CwoAvMXV1va2XR1DQVJeGnZwzNVd0hmvpud7nbP/3lc5JeTVELomruwVTGLtr+BTGT0IweAFTGNvNUuqOs3I4KG5tjvhPM7wm9NtwK2uAX1niLoylt4DcLfy2TeaxPQYDCJJRf7Qm7sDwJX5VoFt8RO9EC2ih+0Ike2+cAyRpIfKENPoIGQbUwvH6KkzHzjljcuvcSqq4D+iZid7up58A866RFrrJH9vkwaF+2mYxa/7awQIwAq8HPOxHkzLfVg74MZC8I1TOKvQAxkAquoNMMyrcAqRIopURfrgEaAtyW/ThPdyduYVlFeMg7BkpGLqZQ=="
}
```

**Common Response Parameters**

| Parameter | Required | Type | Description |
| :- | :- | :- | :- |
| status | Yes | String | 1: Normal, 0: Exception |
| error | Yes | String | Error code |
| msg | Yes | String | Error description |
| data | Yes | Object | Business data (**included in signature check**) |

**Response Example:**

```json theme={null}
    {
        "status": "1",
        "error": "00000000",
        "msg": "",
        "data": {
            "...": "...",
            "sign": "PWA7B2u1hGr1VRxOCZbRuXQXtJiA6BgPExFnFv73hKJ+zcZfOe/R+y+inlwWcdDBzfix35+dl6raEs/yG/hcYyQOwDQ+mVjIt5wFk6iX7GPw557138yBdAmuMqvWM2IF+omLFcQFJvzfbR84rCyOmebDJlhkYMga5TTFHVLicUx3bPIrOJLoWJHrnZfcVFAJ+P5mUQhMH/cf+YmYZvrqq34pMJh6PcP5vyruJ8aNV0QfyHR42AHLIgp+HnOcZpA0aUzFXM5zpsgXK3QR/KO3vLiKd77UaZNO6g5TN/Ck2MtLkBVxyvIHstgXFXKF1e+uc91FdBHK5nfmrjLQ2wyeUA=="
        }
    }
```

**Error Codes**

For the complete error codes, the error response structure, and scenario-based error messages with handling advice, see [HaiPay Error Codes and Error Response Reference](https://doc.haipay.net/docs/en/V20261001/guide/error_response_appendix.md).

## Related Topics

* [HaiPay Integration Environment and Request URLs](https://doc.haipay.net/docs/en/guide/api_parameters_doc)
* [HaiPay Configuration and Signature Guide](https://doc.haipay.net/docs/en/guide/config_settings_and_signature_rules_guide.md)
* [HaiPay Error Codes and Error Response Reference](https://doc.haipay.net/docs/en/V20261001/guide/error_response_appendix.md)


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