> ## 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 接口说明与公共规则

> 了解 HaiPay 接口类型、公共字段、签名规则、回调机制和通用返回结构，帮助快速理解整体 API 设计。

如果您要快速理解 HaiPay API，这一页主要回答 3 个问题：支持哪些接入方式、接口通信要遵循什么规则、以及请求结构是什么。

## 1. 接入方式

| 接口类型     | API文档路径               | 适用业务范围 | 功能说明                                                 |
| :------- | :-------------------- | :----- | :--------------------------------------------------- |
| 全球收银台    | 全球（收银台）               | 全球业务   | 一次对接，支持全球多种支付方式。系统根据用户IP自动跳转至对应国家支付页面，用户可选择支付方式完成付款。 |
| 本地收银台    | 北美、南美、欧洲、亚洲、中东等单一国家业务 | 单一国家业务 | 独立对接，API同步返回指定国家支持的支付页面，供用户选择并完成支付。                  |
| 纯API支付接口 | 北美、南美、欧洲、亚洲、中东等单一国家业务 | 单一国家业务 | 独立对接，API同步返回指定支付方式的相关信息，便于客户自定义支付页面。                 |
| 其他支付接口   | 全球（国际信用卡、信用卡订阅）       | 全球业务   | 独立对接，API同步返回支付页面，代收支付; 信用卡支持订阅扣款。                    |

## 2. 通信协议

商户接入HaiPay服务，调用API须遵循以下规则：

| 类型          | 说明                                                                                      |
| :---------- | :-------------------------------------------------------------------------------------- |
| 传输方式        | 为保证交易安全性，采用HTTPS传输                                                                      |
| 提交方式        | 采用POST方法提交                                                                              |
| 数据格式        | 提交和返回数据都为application/json格式                                                             |
| 字符编码        | 统一采用UTF-8字符编码                                                                           |
| 签名算法        | SHA256WithRSA                                                                           |
| 签名要求        | 请求和接受数据均需要校验签名，详细方法参考 [配置与签名](/docs/zh/guide/config_settings_and_signature_rules_guide) |
| SSL/TLS协议版本 | TLSv1.2 TLSv1.3                                                                         |

## 3. 接口结构

如下是调用HaiPay接口的http结构，接口名称放到请求地址后面，data里边的内容为不同业务结构拼接而成的报文

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

请求地址：

| 联调环境 | 请求地址                                                                   |
| :--- | :--------------------------------------------------------------------- |
| 测试   | [https://uat-interface.haipay.asia](https://uat-interface.haipay.asia) |
| 生产   | 上线提供                                                                   |

## 4. 接口列表

| 产品   | 接口名称           | 接口地址            | 描述            |
| ---- | -------------- | --------------- | ------------- |
| 代收   | 代收申请           | /collect/apply  | 用户向商户进行付款(充值) |
| 代收查询 | /collect/query |                 |               |
| 退款申请 | /refund/apply  |                 |               |
| 代付   | 代付申请           | /pay/apply      | 商户向用户进行付款(提现) |
| 代付查询 | /pay/query     |                 |               |
| 账户余额 | 查询账户           | /account/ledger | 商户进行余额查询      |

详情查看 [接口文档](/docs/zh/guide/api_doc_list) 。

## 5. 参数

**请求接口公共参数**

| 参数名   | 必选 | 类型      | 说明                                                                         |
| :---- | :- | :------ | :------------------------------------------------------------------------- |
| appId | 是  | Integer | 业务ID（后台获取，需要根据URL中的币种传递对应的业务ID）                                            |
| sign  | 是  | String  | 签名（详情查看 [配置与签名](/docs/zh/guide/config_settings_and_signature_rules_guide)） |

**请求示例：**

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

**响应接口公共参数**

| 参数名    | 必选 | 类型     | 说明             |
| :----- | :- | :----- | :------------- |
| status | 是  | String | 1：正常，0：异常      |
| error  | 是  | String | 错误编码           |
| msg    | 是  | String | 错误描述           |
| data   | 是  | Object | 业务数据(**参与验签**) |

**响应示例：**

```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=="
        }
    }
```

**错误编码**

| 错误编码 | 英文回复                                                           | 中文含义                                 |
| :--- | :------------------------------------------------------------- | :----------------------------------- |
| 1001 | param is null                                                  | 参数为空                                 |
| 1002 | Illegal Param                                                  | 非法参数                                 |
| 1003 | system exception                                               | 系统异常(**订单可能已入库，等待异步通知或者查询结果确定最终状态**) |
| 1004 | system is busy                                                 | 系统繁忙(**订单可能已入库，等待异步通知或者查询结果确定最终状态**) |
| 4005 | order already exit                                             | 订单已存在                                |
| 4011 | appId do not exit                                              | 业务ID不存在                              |
| 4012 | you do not have an available product, please connect admin     | 商户业务产品不可用，联系管理员                      |
| 4013 | order not exit                                                 | 订单不存在                                |
| 4014 | order is already end status                                    | 订单为终态                                |
| 4015 | this merchant do not have a collect bank                       | 没有可用的收款账号                            |
| 4016 | your account do not have enough money                          | 账号余额不足                               |
| 4031 | ip adress is Forbidden                                         | 非法IP                                 |
| 5012 | pay in channel not functional, please connect customer service | 系统异常                                 |

## 相关主题

* [HaiPay 接口说明与公共规则](/docs/zh/guide/api_description_guide)
* [HaiPay 商户指南](/docs/zh/guide/README)
* [HaiPay 集成步骤指南](/docs/zh/guide/integration_guide)