> ## 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 |
| 签名要求 | 请求和接受数据均需要校验签名，详细方法参考 [配置与签名](https://doc.haipay.net/docs/zh/guide/config_settings_and_signature_rules_guide.md) |
| 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) |
| 生产 | 上线提供 |

> [!TIP]
>
> 上方示例请求地址为**测试环境**，生产环境请求地址请在上线时联系 HaiPay 商务获取。测试环境与生产环境账号独立，appId 不通用。

## 4. 接口列表

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

详情查看 [接口文档](https://doc.haipay.net/docs/zh/guide/api_doc_list.md) 。

## 5. 参数

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

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

**请求示例：**

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

**错误编码**

完整的错误码、错误返回结构，以及按场景归类的错误信息与处理建议，请见 [HaiPay 错误码与错误返回说明](https://doc.haipay.net/docs/zh/V20261001/guide/error_response_appendix.md)。

## 相关主题

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


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