API Conventions and Common Rules

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 (International Credit Cards, 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 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.

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
Production	To be provided at go-live

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.

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)

Request Example:

{
    "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:

    {
        "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.

Quick start

Merchant Guide

Common Payment

Global Payment

Unified API

Appendix

Merchant FAQ

API Conventions and Common Rules

1. Integration Methods

2. Communication Protocol

3. API Structure

4. API List

5. Parameters

​1. Integration Methods

​2. Communication Protocol

​3. API Structure

​4. API List

​5. Parameters

​Related Topics

1. Integration Methods

2. Communication Protocol

3. API Structure

4. API List

5. Parameters

Related Topics