> ## 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.

# 信用卡支付(VISA/MASTER CARD)

> [!WARNING]
>
> 阅读该接口文档前，务必先查看 [**接口说明**](https://doc.haipay.net/docs/zh/guide/api_description_guide.md)

> [!TIP]
>
> * **针对信用卡交易,消费者有权在交易发生后180天内发起争议申请。当争议被提起时,每笔交易将产生20美元的争议处理费。**
> * **在收到争议通知后,您有两种应对方式可供选择**
>   * **其一:您可以选择接受争议,即向发卡银行提交回复,确认您不对退款金额提出异议。**
>   * **其二:您可以选择对争议进行抗辩,通过完成一个引导式的提交流程,根据提示提供相关证据和支持性文件来阐述您的立场。**
> * **若您选择对争议进行抗辩,将额外收取20美元的抗辩费。如果发卡银行不接受您提交的抗辩材料并判定消费者胜诉,抗辩费将被扣除,同时消费者的付款将被退还。**
> * **关于费用退还政策,如果您成功赢得争议,Haipay将退还抗辩费。然而,除非您的Haipay合同中另有明确规定,否则最初收取的争议处理费在任何情况下均不予退还。**

> [!CAUTION]
>
> 1. PCI 合规性：直接违反 PCI DSS 要求
> 2. 安全风险：WebView 和 iframe 可能无法提供足够的安全隔离
> 3. 中间人攻击：恶意应用可能拦截或篡改支付数据
> 4. 钓鱼风险：无法确保用户是在可信的环境中输入敏感信息

## 设备环境要求

> [!TIP]
>
> 如果您在支付页面中看不到您想要的钱包，则您的设备或浏览器可能不符合以下 Apple Pay 或 Google Pay 条件。
>
> * 钱包里必须至少有一张卡。
> * 您必须使用兼容的 [Apple Pay 设备](https://support.apple.com/zh-cn/102896) 和 [Google Pay 设备](https://developers.google.com/pay/issuers/overview/supported-devices#compatibility_requirements)。
> * 您必须使用 必须使用**HTTPS**和[支持的浏览器](#supported-browsers) 来测试您正在测试的钱包。
> * 允许适用的浏览器访问您的钱包。
>   * Chrome：**设置** > **自动填充和密码** > **付款方式** > **允许网站检查您是否已保存付款方式**
>   * Safari：**设置** > **高级** > **允许网站检查 Apple Pay 和 Apple 卡**
> * 不要使用 Chrome 隐身窗口或 Safari 私人窗口。
> * 确认您在受支持的 Apple Pay 地区 和 Google Pay 地区 进行操作。
> * 对于 Apple Pay，请确认您的设备支持[生物识别身份验证](https://support.apple.com/zh-cn/102626#:~:text=iPhone%20or%20.iPad,on%20all%20devices.)。

> [!TIP]
>
> **桌面浏览器**
>
> * Chrome 38+
> * Safari 10.1+
> * Firefox 29+
> * Edge 15+
> * Opera 25+
>
> **移动浏览器**
>
> * iOS Safari 9+ 以及其他使用系统提供的 WebKit 引擎的浏览器和 Web 视图
> * Android Chrome 38+
> * 三星浏览器 7.1+
>
> **其他说明**
>
> 对于未明确支持的浏览器，我们限制支持如下：
>
> * 要求浏览器支持 **TLS 1.2**
> * 需要足够现代的浏览器来支持 JavaScript 中的 **Promises**
> * 我们会响应错误报告，但不会主动测试其他浏览器

## 地区限制

> **不支持的地区列表**
>
> AD-安道尔
>
> AE-阿拉伯联合酋长国
>
> AF-阿富汗
>
> AG-安提瓜和巴布达
>
> AI-安圭拉
>
> AL-阿尔巴尼亚
>
> AM-亚美尼亚
>
> AO-安哥拉
>
> AQ-南极洲
>
> AR-阿根廷
>
> AS-美属萨摩亚
>
> AW-阿鲁巴
>
> AX-奥兰群岛
>
> BA-波斯尼亚和黑塞哥维那
>
> BB-巴巴多斯
>
> BD-孟加拉国
>
> BF-布基纳法索
>
> BH-巴林
>
> BI-布隆迪
>
> BJ-贝宁
>
> BL-圣巴泰勒米
>
> BM-百慕大
>
> BN-文莱
>
> BQ-博内尔、圣尤斯特歇斯和萨巴
>
> BS-巴哈马
>
> BT-不丹
>
> BV-布韦岛
>
> BW-博茨瓦纳
>
> BY-白俄罗斯
>
> BZ-伯利兹
>
> CC-科科斯（基林）群岛
>
> CD-刚果民主共和国
>
> CF-中非共和国
>
> CG-刚果共和国
>
> CI-科特迪瓦
>
> CK-库克群岛
>
> CM-喀麦隆
>
> CO-哥伦比亚
>
> CU-古巴
>
> CV-佛得角
>
> CW-库拉索
>
> CX-圣诞岛
>
> CY-塞浦路斯
>
> DJ-吉布提
>
> DM-多米尼克
>
> DO-多米尼加共和国
>
> DZ-阿尔及利亚
>
> EC-厄瓜多尔
>
> EE-爱沙尼亚
>
> EG-埃及
>
> EH-西撒哈拉
>
> ER-厄立特里亚
>
> ET-埃塞俄比亚
>
> FJ-斐济
>
> FK-福克兰群岛
>
> FM-密克罗尼西亚联邦
>
> FO-法罗群岛
>
> GA-加蓬
>
> GD-格林纳达
>
> GE-格鲁吉亚
>
> GF-法属圭亚那
>
> GG-根西岛
>
> GH-加纳
>
> GI-直布罗陀
>
> GL-格陵兰
>
> GM-冈比亚
>
> GN-几内亚
>
> GP-瓜德罗普
>
> GQ-赤道几内亚
>
> GS-南乔治亚和南桑威奇群岛
>
> GT-危地马拉
>
> GW-几内亚比绍
>
> HK-香港
>
> HM-赫德岛和麦克唐纳群岛
>
> HN-洪都拉斯
>
> HT-海地
>
> ID-印度尼西亚
>
> IL-以色列
>
> IM-马恩岛
>
> IN-印度
>
> IO-英属印度洋领地
>
> IQ-伊拉克
>
> IR-伊朗
>
> JM-牙买加
>
> JO-约旦
>
> JP-日本
>
> KE-肯尼亚
>
> KH-柬埔寨
>
> KI-基里巴斯
>
> KM-科摩罗
>
> KN-圣基茨和尼维斯
>
> KP-朝鲜
>
> KR-韩国
>
> KW-科威特
>
> KY-开曼群岛
>
> KZ-哈萨克斯坦
>
> LA-老挝
>
> LB-黎巴嫩
>
> LC-圣卢西亚
>
> LI-列支敦士登
>
> LK-斯里兰卡
>
> LR-利比里亚
>
> LS-莱索托
>
> LV-拉脱维亚
>
> LY-利比亚
>
> MD-摩尔多瓦
>
> ME-黑山
>
> MF-法属圣马丁
>
> MG-马达加斯加
>
> MH-马绍尔群岛
>
> MK-北马其顿
>
> ML-马里
>
> MM-缅甸
>
> MN-蒙古
>
> MP-北马里亚纳群岛
>
> MQ-马提尼克
>
> MR-毛里塔尼亚
>
> MS-蒙特塞拉特
>
> MU-毛里求斯
>
> MV-马尔代夫
>
> MW-马拉维
>
> MY-马来西亚
>
> MZ-莫桑比克
>
> NA-纳米比亚
>
> NC-新喀里多尼亚
>
> NE-尼日尔
>
> NF-诺福克岛
>
> NG-尼日利亚
>
> NI-尼加拉瓜
>
> NP-尼泊尔
>
> NR-瑙鲁
>
> NU-纽埃
>
> OM-阿曼
>
> PA-巴拿马
>
> PE-秘鲁
>
> PF-法属波利尼西亚
>
> PG-巴布亚新几内亚
>
> PH-菲律宾
>
> PK-巴基斯坦
>
> PM-圣皮埃尔和密克隆
>
> PN-皮特凯恩群岛
>
> PR-波多黎各
>
> PS-巴勒斯坦
>
> PW-帕劳
>
> RE-留尼汪
>
> RU-俄罗斯
>
> RW-卢旺达
>
> SA-沙特阿拉伯
>
> SB-所罗门群岛
>
> SC-塞舌尔
>
> SD-苏丹
>
> SH-圣赫勒拿
>
> SJ-斯瓦尔巴和扬马延
>
> SK-斯洛伐克
>
> SL-塞拉利昂
>
> SM-圣马力诺
>
> SN-塞内加尔
>
> SO-索马里
>
> SR-苏里南
>
> SS-南苏丹
>
> ST-圣多美和普林西比
>
> SV-萨尔瓦多
>
> SX-荷属圣马丁
>
> SY-叙利亚
>
> SZ-斯威士兰
>
> TC-特克斯和凯科斯群岛
>
> TD-乍得
>
> TF-法属南部领地
>
> TG-多哥
>
> TH-泰国
>
> TK-托克劳
>
> TL-东帝汶
>
> TM-土库曼斯坦
>
> TN-突尼斯
>
> TO-汤加
>
> TR-土耳其
>
> TT-特立尼达和多巴哥
>
> TV-图瓦卢
>
> TW-台湾
>
> TZ-坦桑尼亚
>
> UA-乌克兰
>
> UG-乌干达
>
> UM-美国本土外小岛屿
>
> UY-乌拉圭
>
> UZ-乌兹别克斯坦
>
> VA-梵蒂冈
>
> VC-圣文森特和格林纳丁斯
>
> VE-委内瑞拉
>
> VG-英属维尔京群岛
>
> VI-美属维尔京群岛
>
> VN-越南
>
> VU-瓦努阿图
>
> WF-瓦利斯和富图纳
>
> WS-萨摩亚
>
> YE-也门
>
> YT-马约特
>
> ZA-南非
>
> ZM-赞比亚
>
> ZW-津巴布韦

## 集成模式 

信用卡支付提供两种接入模式，核心区别在于支付页面由谁承载：

| 对比项 | PayUrl 跳转模式 | JS 嵌入模式 |
| :- | :- | :- |
| 支付页面 | 跳转到 HaiPay 托管的支付页面 | 在商户自己的页面中嵌入支付组件 |
| 前端工作量 | 几乎为零，只需处理跳转 | 需要引入 JS 脚本并监听事件 |
| UI 控制力 | 低，页面样式由 HaiPay 控制 | 高，可自定义主题、布局和交互 |
| 关键返回字段 | 使用响应中的 `payUrl` | 使用响应中的 `clientToken` |
| 适用场景 | 快速接入、对支付页面无定制需求 | 自建收银台、需要沉浸式支付体验 |

**PayUrl 跳转模式**

最简单的接入方式。商户服务端调用代收申请接口后，使用返回的 `payUrl` 将用户跳转到 HaiPay 托管的支付页面，用户在该页面完成信用卡信息填写和支付授权。

**接入流程**

**1. 服务端调用代收申请接口**

商户服务端向 HaiPay 发起 [代收申请](#1-代收申请)，在请求中传入交易金额、支付方式、回调地址等必要参数。

**2. 获取 payUrl 并跳转**

接口返回中包含 `payUrl` 字段，商户将用户浏览器重定向到该地址。

**3. 用户完成支付**

用户在 HaiPay 托管页面完成信用卡信息填写和支付授权。支付完成后，HaiPay 会将用户重定向回商户的 `callBackUrl`；如果传递了 `cancelUrl`，支付页面会展示返回按钮，用户点击跳转至该链接；同时向 `notifyUrl` 发送异步通知。

**示例代码（服务端获取 payUrl 后的前端跳转）**

```javascript theme={null}
// 假设你的服务端已调用代收申请接口，并将 payUrl 返回给前端
const payUrl = response.data.payUrl;

// 在当前窗口跳转
window.location.href = payUrl;

// 或者在新窗口打开
// window.open(payUrl, '_blank');
```

**适用建议**

* 希望最快速度完成支付接入，前端改动最少。
* 对支付页面的 UI 没有强定制需求。
* 移动端 H5 场景下，跳转体验通常也能满足需求。

**JS 嵌入模式**

通过引入 HaiPay JS 脚本，将支付组件直接嵌入商户页面。商户服务端调用代收申请接口获取 `clientToken`，前端使用该令牌初始化组件，用户无需跳转即可在当前页面完成支付。

JS 提供以下组件形态，请根据收银台设计需求选择：

**自定义组合模式**

在一个容器内同时展示 Google Pay、Apple Pay 和 Credit Card，支持通过 `mode` 参数切换普通支付与订阅支付，适合需要统一管理多种支付场景的商户。

**引入脚本**

`https://cashier.haipay.top/js/composite-component_1.0.0.min.js`

**配置参数**

| 参数 | 必填 | 说明 |
| :- | :- | :- |
| `sandbox` | 是 | `true` 为测试环境，`false` 为生产环境 |
| `clientToken` | 是 | 代收申请接口返回的客户端令牌 |
| `mode` | 是 | 支付场景：`payment`（普通支付）或 `subscription`（订阅支付） |
| `showPayButton` | 否 | 是否显示信用卡提交按钮，默认 `false`（不显示） |
| `themeMode` | 否 | 主题模式，可选 `light` / `dark`，默认 `light` |
| `paymentMethodConfig` | 否 | 支付方式组合，默认 `["GOOGLE_PAY","APPLE_PAY","CREDIT_CARD"]` |
| `applePayButtonType` | 否 | Apple Pay 按钮文案，可选 `buy`、`subscribe` 等 |
| `googlePayButtonType` | 否 | Google Pay 按钮文案，可选 `buy`、`subscribe` 等 |
| `cardPosition` | 否 | 信用卡放置位置，默认 `bottom`，可选：`bottom`、`top` |

**事件回调**

* `ready` — 组件渲染完成，可进行交互
* `error` — 初始化失败或支付过程出错
* `confirm` — 表单提交结果（成功/失败）
* `paymentStatus` — 支付结果通知，失败会返回错误信息（若未监听，组件将自动处理支付结果展示）
* `paymentMethodType` — 当前选中的支付方式

**适用建议**

* 新建收银台推荐优先选用此模式，页面结构更清晰、开发成本更低。
* 如仅开放部分支付方式，只需传入所需的组合即可。

```javascript theme={null}
<script src="https://cashier.haipay.top/js/composite-component_1.0.0.min.js"></script>

<div>
  <div id="paymentId"></div>
</div>

const elements = haiPay.create({
  mode: 'payment',
  sandbox: true,
  clientToken: 'your-client-token',
  themeMode: 'light',
  paymentMethodConfig: ['GOOGLE_PAY', 'APPLE_PAY', 'CREDIT_CARD']
});

elements.mount('#paymentId');

elements.on('ready', (event) => {
  console.log('rendered successfully:', event);
});

elements.on('error', (event) => {
  console.error('Payment error:', event);
});

elements.on('paymentMethodType', (event) => {
  console.log('payment method type', event);
});

elements.submitCardPayment();

elements.on('confirm', (event) => {
  console.log('confirm:', event);
});

elements.on('paymentStatus', (event, message) => {
  console.log('payment status:', event, message);
});

```

**Apple Pay / Google Pay（即将废弃）**

> [!WARNING]
>
> 该组件即将废弃，推荐使用「自定义组合模式」替代。

适合已具备钱包支付入口、希望快速拉起 Apple Pay / Google Pay 授权的场景。

**引入脚本**

`https://cashier.haipay.top/js/applePayGooglePay_1.0.0.min.js`

**配置参数**

| 参数 | 必填 | 说明 |
| :- | :- | :- |
| `sandbox` | 是 | `true` 为测试环境，`false` 为生产环境 |
| `clientToken` | 是 | 代收申请接口返回的客户端令牌 |
| `buttonType` | 否 | 按钮文案类型，可选 `plain`、`buy`（默认）、`check-out`、`subscribe` 等 |
| `buttonTheme` | 否 | 按钮主题色，可选 `black`（默认）、`white` |
| `buttonHeight` | 否 | 按钮高度（px），默认 `50` |

**事件回调**

* `ready` — 按钮渲染完成，可进行交互
* `error` — 初始化失败或支付过程出错
* `paymentStatus` — 支付结果通知（若未监听，组件将自动处理支付结果展示）
* `paymentMethodType` — 当前选中的支付方式

```javascript theme={null}
<script src="https://cashier.haipay.top/js/applePayGooglePay_1.0.0.min.js"></script>

<div>
  <div id="applePay-googlePay"></div>
</div>

const elements = applePayGooglePay.create('applePayGooglePay', {
  sandbox: true,
  clientToken: 'your-client-token',
  buttonType: 'buy',
  buttonTheme: 'black',
  buttonHeight: 50
});

elements.mount('#applePay-googlePay');

elements.on('ready', (data) => {
  console.log('Button rendered successfully:', data);
});

elements.on('error', (data) => {
  console.error('Payment error:', data);
});

elements.on('paymentMethodType', (event) => {
  console.log('payment method type', event);
});

elements.on('paymentStatus', (data) => {
  console.log('payment status:', data);
});
```

**Credit Card（即将废弃）**

> [!WARNING]
>
> 该组件即将废弃，推荐使用「自定义组合模式」替代。

适合需要直接展示信用卡支付表单、并由商户自行控制提交时机的场景。

**引入脚本**

`https://cashier.haipay.top/js/creditCard_1.0.0.min.js`

**配置参数**

| 参数 | 必填 | 说明 |
| :- | :- | :- |
| `sandbox` | 是 | `true` 为测试环境，`false` 为生产环境 |
| `clientToken` | 是 | 代收申请接口返回的客户端令牌 |
| `cardTheme` | 否 | 表单主题色，可选 `black`、`white`（默认） |

**事件回调**

* `ready` — 信用卡表单渲染完成，可进行交互
* `confirm` — 表单提交结果（成功/失败）
* `paymentStatus` — 支付结果通知（若未监听，组件将自动处理支付结果展示）

```javascript theme={null}
<script src="https://cashier.haipay.top/js/creditCard_1.0.0.min.js"></script>

<div>
  <div id="creditCardId"></div>
</div>

const elements = creditCard.create('card', {
  sandbox: true,
  clientToken: 'your-client-token',
  cardTheme: 'white'
});

elements.mount('#creditCardId');

elements.on('ready', (data) => {
  console.log('Card rendered successfully:', data);
});

elements.on('error', (data) => {
  console.error('Payment error:', data);
});

elements.submit();

elements.on('confirm', (data) => {
  console.log('confirm:', data);
});

elements.on('paymentStatus', (data) => {
  console.log('payment status:', data);
});
```

**常见错误**

| 错误信息 | 错误原因 | 解决方案 |
| :- | :- | :- |
| Missing required parameters: env, orderNo | 缺少必需的初始化参数 | 检查 `clientToken` 等参数是否正确传入 |
| Unsupported region: CN | 生产环境下不支持中国地区 | 确认商户配置与目标市场 |

## **限额**

| 交易类型 | 限额(单位:USD) |
| :- | - |
| 代收 | 0.99-1000 |

## **代收API**

### **1.代收申请**

**简要描述：**

* 查询代收订单

**URL：**

美元: `/usd/collect/apply`
说明：appId需使用美元对应的，用户支付成功后增加美元余额

**参数：**

| 参数名 | 必选 | 类型 | 说明 |
| :- | :- | :- | :- |
| appId | 是 | Long | 业务ID（后台获取，需要根据URL中的币种传递对应的业务ID） |
| orderId | 是 | String | 商户订单号(必须保证唯一性，长度不超过48) |
| name | 否 | String | 用户姓名，推荐使用真实姓名，格式：包含firstName和lastName，以空格分割的，示例：John Doe |
| phone | 是 | String | 真实手机号（格式参考 [电话号码格式](https://doc.haipay.net/docs/zh/guide/frequently_asked_question.md#zh_faq_phone-number-format) ） |
| email | 否 | String | 真实电子邮件 |
| amount | 是 | String | 交易金额（精确到小数点后两位；禁止添加标点符号，例如：”,”） |
| payType | 是 | String | [支付方式类型](#inBankCode) |
| inBankCode | 是 | String | [支付方式编码](#inBankCode) |
| clientIp | 否 | String | 用户端ip |
| callBackUrl | 是 | String | 用户支付成功后跳转地址 |
| callBackFailUrl | 是 | String | 用户支付失败后跳转地址 |
| cancelUrl | 否 | String | 如果传递，支付页面会展示返回按钮，用户点击跳转至该链接 |
| notifyUrl | 否 | String | 回调地址 |
| subject | 是 | String | 支付备注 |
| body | 否 | String | 备注详情 |
| partnerUserId | 是 | String | 用户唯一标识（如用户ID userId），用于风控系统，必须真实有效，否则会影响交易。 格式要求：数字、大小写字母或常用符号-\~!@#\$%&\*()\_。 |
| paymentMethods | 是 | String | 支持的支付方式列表，英文逗号分隔，如 CREDIT\_CARD,GOOGLE\_PAY,APPLE\_PAY |
| sign | 是 | String | 签名 |

**请求示例**

```json theme={null}
{
  "appId": 1054,
  "orderId": "M233323000059",
  "amount": "299.99",
  "phone": "02012345678",
  "email": "robert.taylor@gmail.com",
  "name": "Robert Taylor",
  "inBankCode": "USA",
  "payType": "BANK_TRANSFER",
  "partnerUserId": "149597870",
  "sign": "af0gAHkUOyYHu9owQp8NJ4mPEeUW4vuJcjdxqLIzrVw8AvpLSjD1DXupReSG/CyuSkFRyiIvCp5u703AuGGmfgD2gKDH3Ywau41bAbG2jnHJ8mtjiSJ5iWUzanyd4Kr7d1+rETbzUl7/BkW3t0X8UUFdqpxwG8DPUjAwUKfplWDHV7koG51Ozexd80DCsmW6eWdouAZ1uNXGLYmV3ftE3BmfNRtuv1C5bfTJWrTEIOxbF6g2uYOFZTlIgrQgd7/2PsAYwQQXNz8Q8CYl4OxqCv4pXJxaLWPbR5tqZu9og5kn32C9aHW/NlU1y39vzz+4ef81yPAqUV9oHlSMSPrMmw=="
}
```

**响应示例**

```json theme={null}
{
  "status": "1",
  "error": "00000000",
  "msg": "",
  "data": {
    "orderId": "M233323000059",
    "orderNo": "6023071013539074",
    "payUrl": "",
    "clientToken": "",
    "sign": "YEoA8Y2JzQFGVzwJSqmemm1Kfv/bfyIfCqv2dp7RNzT5B72AQvdD+nt2nR4sL1HWscvmNHyVt5ovAi7MMhy3ziih/sMph+wPx4YjH3W1h5DyBvSlWvaKfKrK5ViomZ0pPYWydwRHnnRnicxToHK9S6qtSy7Q73O0hdz4hJ9p41Th3ycBl2Q9SeqSZYSY1ohcPDhdyRf2y0prb8rHgpBKzxZ5BKX/1bsE9OmsSEHAEYT8OGgko6aNe8XPAhr4G48cpWTftvnGQuzh0O65nuZRI/PF+Axt2zJCVbFHDDSREI9NlAT82ebDqhlVdxQzKE67D1nxgjb3dPmDUYHOBpmwxQ=="
  }
}
```

返回data参数说明

| 参数名 | 类型 | 说明 |
| :- | :- | :- |
| orderId | String | 商户订单号(必须保证唯一性) |
| orderNo | String | 平台订单号 |
| payUrl | String | 支付链接 |
| bankCode | String | 支付方式编码 |
| clientToken | String | 在JavaScript Web SDK中使用的客户端令牌(见[HaiPaySDK.js](#haipaycdn)) |
| sign | String | 签名 |

### **2.代收申请 [MIT模式](#mit)**

**简要描述：**

* 创建MIT模式代收订单

**URL：**

美元: `/usd/mit/apply`
说明：appId需使用美元对应的，用户支付成功后增加美元余额

**参数：**

| 参数名 | 必选 | 类型 | 说明 |
| :- | :- | :- | :- |
| appId | 是 | Long | 业务ID（后台获取，需要根据URL中的币种传递对应的业务ID） |
| orderId | 是 | String | 商户订单号(必须保证唯一性，长度不超过48) |
| name | 否 | String | 用户姓名，推荐使用真实姓名，格式：包含firstName和lastName，以空格分割的，示例：John Doe |
| phone | 否 | String | 真实手机号（格式参考 [电话号码格式](https://doc.haipay.net/docs/zh/guide/frequently_asked_question.md#zh_faq_phone-number-format) ） |
| email | 否 | String | 真实电子邮件 |
| amount | 是 | String | 交易金额（精确到小数点后两位；禁止添加标点符号，例如：”,”） |
| payType | 是 | String | [支付方式类型](#inBankCode) |
| inBankCode | 是 | String | [支付方式编码](#inBankCode) |
| clientIp | 否 | String | 用户端ip |
| callBackUrl | 是 | String | 用户支付成功后跳转地址 |
| callBackFailUrl | 是 | String | 用户支付失败后跳转地址 |
| cancelUrl | 否 | String | 如果传递，支付页面会展示返回按钮，用户点击跳转至该链接 |
| notifyUrl | 否 | String | 回调地址 |
| subject | 是 | String | 支付备注 |
| body | 否 | String | 备注详情 |
| partnerUserId | 是 | String | 用户唯一标识（如用户ID userId），用于风控系统，必须真实有效，否则会影响交易。 格式要求：数字、大小写字母或常用符号-\~!@#\$%&\*()\_。 |
| tokenID | 否 | String | 支付令牌，首次交易不需要，后续主动扣款需要，通过回调获取 |
| loadingType | 否 | Integer | 0（默认） – 显示正常的支付结果页面; 1 – 显示加载中动画（loading 转圈），不展示订单信息。 |
| paymentMethods | 否 | String | 支持的支付方式列表，英文逗号分隔，如 CREDIT\_CARD,GOOGLE\_PAY,APPLE\_PAY(与payType,inBankCode 不可同时传递) |
| sign | 是 | String | 签名 |

**请求示例**

```json theme={null}
{
  "appId": 1054,
  "orderId": "M233323000059",
  "amount": "299.99",
  "phone": "02012345678",
  "email": "robert.taylor@gmail.com",
  "name": "Robert Taylor",
  "inBankCode": "USA",
  "payType": "BANK_TRANSFER",
  "partnerUserId": "149597870",
  "sign": "af0gAHkUOyYHu9owQp8NJ4mPEeUW4vuJcjdxqLIzrVw8AvpLSjD1DXupReSG/CyuSkFRyiIvCp5u703AuGGmfgD2gKDH3Ywau41bAbG2jnHJ8mtjiSJ5iWUzanyd4Kr7d1+rETbzUl7/BkW3t0X8UUFdqpxwG8DPUjAwUKfplWDHV7koG51Ozexd80DCsmW6eWdouAZ1uNXGLYmV3ftE3BmfNRtuv1C5bfTJWrTEIOxbF6g2uYOFZTlIgrQgd7/2PsAYwQQXNz8Q8CYl4OxqCv4pXJxaLWPbR5tqZu9og5kn32C9aHW/NlU1y39vzz+4ef81yPAqUV9oHlSMSPrMmw=="
}
```

**响应示例**

```json theme={null}
{
  "status": "1",
  "error": "00000000",
  "msg": "",
  "data": {
    "orderId": "M233323000059",
    "orderNo": "6023071013539074",
    "payUrl": "",
    "clientToken": "",
    "sign": "YEoA8Y2JzQFGVzwJSqmemm1Kfv/bfyIfCqv2dp7RNzT5B72AQvdD+nt2nR4sL1HWscvmNHyVt5ovAi7MMhy3ziih/sMph+wPx4YjH3W1h5DyBvSlWvaKfKrK5ViomZ0pPYWydwRHnnRnicxToHK9S6qtSy7Q73O0hdz4hJ9p41Th3ycBl2Q9SeqSZYSY1ohcPDhdyRf2y0prb8rHgpBKzxZ5BKX/1bsE9OmsSEHAEYT8OGgko6aNe8XPAhr4G48cpWTftvnGQuzh0O65nuZRI/PF+Axt2zJCVbFHDDSREI9NlAT82ebDqhlVdxQzKE67D1nxgjb3dPmDUYHOBpmwxQ=="
  }
}
```

返回data参数说明

| 参数名 | 类型 | 说明 |
| :- | :- | :- |
| orderId | String | 商户订单号(必须保证唯一性) |
| orderNo | String | 平台订单号 |
| payUrl | String | 支付链接 |
| clientToken | String | 在JavaScript Web SDK中使用的客户端令牌(见[HaiPaySDK.js](#haipaycdn)) |
| sign | String | 签名 |

### **3.代收查询**

**简要描述：**

* 查询代收订单

**URL：**

美元: `/usd/collect/query`

**参数：**

| 参数名 | 必选 | 类型 | 说明 |
| :- | :- | :- | :- |
| appId | 是 | Long | 业务ID（后台获取，需要根据URL中的币种传递对应的业务ID） |
| orderId | 是 | String | 商户订单号 |
| orderNo | 否 | String | 平台订单号（响应快） |
| sign | 是 | String | 签名 |

**请求示例**

```json theme={null}
{
  "appId": 1054,
  "orderId": "M22222000028",
  "sign": "EmyJGm3ELzG4FsOd0Krs9ncbSjo4oTGuXWML+7djYla3+VAwd9wS17z38p/7U2ZAjroO04XrE7YXcB1o76Dtyipj3h3bJzs7FYma1QNkMUdt9hh7m8U6hMsMQX7vIWHtXNwz4pbTSC75+kQWXaCew7KoE6LXECdJU8AISgNgeki2TK9R0pCfshr0Z2SZBPeuT6OvIH5LdmqgdZhuqnffGU2qnXk4KMkO848e6/WALLBR+LE1wyKHfPnYVcuKSMVYxkvKyyIL5JIPEgW0o5bh4RCbaUn3NZtyYwrU1uQ3ZDFRThm9j6XAQP+LBlmq3nOePqBtp/VDVarRaV+7FbQg3A=="
}
```

**响应示例**

```json theme={null}
{
  "status": "1",
  "error": "00000000",
  "msg": "",
  "data": {
    "orderId": "M22222000028",
    "orderNo": "6023042811314347",
    "amount": "299.99",
    "actualAmount": "0.00",
    "fee": "0.00",
    "status": 1,
    "sign": "fP433ygWVDLVGxYkVnIJj7riGq0U3vyVX+MbBAImxfGLZkZcEAHVEoVYuULZSmXAAXKRSyd67WlDNm+24pougM54ofAoH4HMtCL2tfCoBReFyz3z02AGKkrKE2xWhSpWoqfQoBvzwuN5iGMMu0s9Q1YvqiwJ8WDVIENnmiIyD8qDJN7caHTW2US14/faG+69AvnuIgJ/nu7/jogOlgEYdZdVYU7gcRDE+d47KjlFGswQkJ/h/uzV7cWtUqrtOO7ZnZ3/z33Xx8awokX36QoYcPSWAU0h+Ij9O9402HNhm1eTbYcLU0uI/z8xCAtyAI/tTyiFijpiNlxUKQj+zKsILw=="
  }
}
```

返回data参数说明

| 参数名 | 类型 | 说明 |
| :- | :- | :- |
| orderId | String | 商户订单号(必须保证唯一性) |
| orderNo | String | 平台订单号 |
| amount | String | 交易金额 |
| actualAmount | String | 收到金额 |
| fee | String | 手续费 |
| status | Integer | 状态(0未开始，1支付中，2成功（终态），3失败（终态）, -1异常待确认) |
| payTime | String | 支付成功时间（当status=2时有值）(本地时间), 格式: yyyy-MM-dd HH:mm:ss |
| errorMsg | String | 支付失败原因（当status=3时有值） |
| sign | String | 签名 |

### **4.退款申请**

**简要描述：**

* 发起原信用卡交易订单的退款操作，同步返回的退款状态请注意状态值，建议以查询接口为主。

**URL：**

美元: `/usd/refund/apply`

**参数：**

| 参数名 | 必选 | 类型 | 说明 |
| :- | :- | :- | :- |
| appId | 是 | Long | 业务ID（后台获取，需要根据URL中的币种传递对应的业务ID） |
| orderId | 是 | String | 商户申请退款订单号（商户新的订单号，不能使用原代收的商户订单号） |
| orderNo | 是 | String | 平台订单号（原代收返回的平台单号） |
| refundAmount | 否 | String | 可选，不传则全额退款 |
| sign | 是 | String | 签名 |

返回data参数说明

| 参数名 | 类型 | 说明 |
| :- | :- | :- |
| appId | String | 业务ID |
| orderNo | String | 平台订单号 （原代收返回的平台单号） |
| orderId | String | 商户退款申请订单号 |
| refundNo | String | 本次退款平台单号 |
| status | String | 退款状态，1表示退款申请成功，0表示处理中，2表示失败，正常下发起就是返回处理中，后续需要调用查询接口查询状态 |
| errorMsg | String | 错误信息，不一定有值 |
| sign | String | 签名 |

### **5.退款查询**

**简要描述：**

* 发起退款的订单的结果查询。

**URL：**

美元: `/usd/refund/refundQuery`

**参数：**

| 参数名 | 必选 | 类型 | 说明 |
| :- | :- | :- | :- |
| appId | 是 | Long | 业务ID（后台获取，需要根据URL中的币种传递对应的业务ID） |
| orderId | 否 | String | 商户退款申请订单号 |
| refundNo | 否 | String | 平台退款单号（申请退款返回的平台单号，如果有值优先查询此字段） |
| sign | 是 | String | 签名 |

返回data参数说明

| 参数名 | 类型 | 说明 |
| :- | :- | :- |
| appId | String | 商户订单号(必须保证唯一性) |
| orderNo | String | 平台订单号(原代收返回的平台单号） |
| orderId | String | 商户申请订单号 |
| refundNo | String | 平台退款单号 |
| status | String | 退款状态，1表示退款申请成功，0表示处理中，2表示失败，退款结果以此状态为准 |
| errorMsg | String | 错误信息，不一定有值 |
| refundAmount | String | 退款金额 |
| sign | String | 签名 |

### **6.支付方式**&#x20;

| 币种 | 支付类型(payType) | 支付编码(inBankCode) | 限额 | 状态 | 说明 |
| :- | :- | :- | :- | :- | :- |
| USD | BANK\_TRANSFER | CREDIT\_CARD | 0.99-1000 | 可用 | VISA |
| USD | BANK\_TRANSFER | CREDIT\_CARD | 0.99-1000 | 可用 | MasterCard |
| USD | BANK\_TRANSFER | CREDIT\_CARD | 0.99-1000 | 可用 | JCB |
| USD | EWALLET | GOOGLE\_PAY | 0.99-1000 | 可用 | Google Pay |
| USD | EWALLET | APPLE\_PAY | 0.99-1000 | 可用 | Apple Pay |

### 7.测试卡号

> [!WARNING]
>
> **只能在测试环境使用**

#### 模拟成功支付

使用以下测试卡号，输入任意 CVC（3位数字）和有效期（未来日期）来模拟支付成功：

* 卡号 1：4242424242424242

#### 模拟支付失败

使用以下测试卡号、无效数据来模拟支付失败：

* 卡号 1：4000000000009995
* 无效月份：13
* 无效 CVV：99

### 8.MIT（Merchant Initiated Transaction）模式说明&#x20;

**MIT（Merchant Initiated Transaction，商户发起交易）**
指在用户完成一次性支付授权后，商户可在用户不在场的情况下主动发起的扣款。
该模式广泛应用于 **订阅支付、分期付款、会员续费、延迟扣款** 等业务场景。

#### 基本流程

1. **用户授权**
   * 用户在首次支付时输入支付信息，并完成必要的身份验证。
   * 商户保存用户的支付凭证，用于后续的扣款请求。

2. **商户发起扣款**
   * 商户根据约定的周期或条件，直接使用已保存的支付凭证发起扣款请求。
   * 由于交易为 **离线场景（off-session）**，即用户不参与交易，系统会依据用户授权和合规要求完成处理。

3. **认证要求**
   * 在大多数情况下，交易会直接完成。
   * 若发卡行或风控系统要求再次验证，交易可能进入待用户确认的状态，需要用户补充验证才能完成。

#### 模式特点

* **提升体验**：用户无需每次手动输入支付信息。
* **合规安全**：符合国际支付法规和强客户认证（SCA）等要求。
* **应用广泛**：适用于订阅收费、自动续费、分期扣款、延迟结算等场景。

#### MIT流程图

```mermaid theme={null}
flowchart TD
    A[用户：在商户平台下单] --> B{交易类型判断}
    N[支付回调]
    O[商户：提供服务/发货]
    P[商户：通知用户支付失败]

    subgraph S2 [场景二：后续交易]
        direction TB
        I[后续交易] --> J[商户：向Haipay发送<br>交易请求与“令牌”]
        J --> K{Haipay：验证“令牌”}
        K -->|有效| L[Haipay：执行自动扣款]
        L --> N
        K -->|无效/失败| M[支付失败]
        M --> P
    end

    subgraph S1 [场景一：首次交易]
        direction TB
        C[首次交易] --> D[Haipay：提供支付链接]
        D --> E[用户：确认支付]
        E --> F[支付成功]
        F --> G[Haipay：生成安全“令牌”<br>（绑定用户与商户）]
        G --> N
        N --> O
    end

    B --> C
    B --> I
```

## 相关主题

* [公共接口](https://doc.haipay.net/docs/zh/api/version2/CommonApi.md)
* [HaiPay 接口说明与公共规则](https://doc.haipay.net/docs/zh/guide/api_description_guide.md)
* [PCI支付接口](https://doc.haipay.net/docs/zh/api/version2/creditcard-pci)


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