## 平台简介与对接说明

### 平台定位与能力描述

易宝开放平台（YOP，Yeepay Open Platform）是易宝支付精心打造的一站式金融科技能力开放平台。平台秉承"合作、互利、共赢"的服务理念，基于易宝在支付领域数十余年的深厚技术积累，将支付处理、账户管理、资金清算等核心金融能力以标准化接口形式开放给合作伙伴，助力开发者高效构建安全可靠的金融级应用。

**技术特性**
- 严格采用 RESTful 架构风格设计，遵循业界最佳实践和规范
- 全面支持 JSON 数据交换格式，便于跨平台、跨语言集成和数据处理
- 提供详尽的接口文档和错误码说明，大幅简化问题定位和排查流程
- 实施接口版本化管理机制，确保系统平滑升级和向下兼容

### 对接流程说明

易宝开放平台的完整接入流程包含以下关键步骤：

**1. 商户入网并签约产品**
- 未入网商户：联系易宝销售团队签约，完成商户注册和资质审核
- 已入网商户：登录商户后台申请开通开发者权限
- 查看产品开通情况：确认已开通的产品和权限，核对产品功能与业务需求匹配
- 检查应用配置：确认应用标识（AppKey）和应用名称，验证应用是否具备所需产品的访问权限

**2. 密钥配置**
- 密钥制备：下载并安装密钥工具，根据安全需求选择密钥类型
  - 商密密钥(SM)：符合国家密码局安全标准，推荐 Java 语言开发者使用
  - 国际密钥(RSA)：国际通用加密算法，适用于更多开发语言，兼容性更好
- 密钥配置：登录开发者中心完成配置，上传公钥并下载平台公钥
- 安全提示：妥善保管私钥，避免泄露，将私钥存储在安全的环境中，并限制访问权限

**3. SDK 集成**
- 选择合适的 SDK：根据开发语言选择对应 SDK，确认版本兼容性，检查环境依赖
- 引入 SDK：使用包管理器安装或手动下载集成，配置依赖关系
- 配置客户端参数：设置应用参数，配置密钥信息，设置环境参数

**4. 开发与接口调用**
- 了解业务场景和模型：明确业务需求与平台能力的匹配点，设计合理的业务流程
- 实现接口调用逻辑：按照示例代码实现核心功能，处理请求响应
- 实现异步通知接收接口：开发稳定可靠的回调接口，确保能够接收并处理平台的异步通知

**5. 测试验证**
- 使用沙箱环境：在测试环境下进行功能验证和压力测试
- 全流程测试：对主要业务流程进行端到端测试，验证功能正确性和系统稳定性
- 处理异常情况：测试各类异常场景和边界条件，确保系统健壮性

**6. 正式上线**
- 验证系统稳定性和业务连续性
- 切换至生产环境配置，准备正式运营和业务开展
- 持续监控系统性能，优化用户体验

### 平台支持的开发工具说明

易宝开放平台提供了丰富的开发工具，帮助开发者高效完成集成开发工作：

**1. 多语言 SDK**
易宝开放平台 SDK 是官方提供的开发工具包，封装了请求处理、签名加密、响应解析等核心功能，显著降低开发成本，提高开发效率。

支持的语言版本：
- Java SDK (yop-java-sdk)：支持 JDK 1.8 及以上版本，[GitHub](https://github.com/yop-platform/yop-java-sdk)，可能需要安装JCE包，支持多域名路由功能版本：`3.3.10`、`4.1.13`、`4.2.4`、`4.2.5`、`4.4.1`及以上
- PHP SDK (yop-php-sdk)：需要 PHP 5.5 及以上版本，[GitHub](https://github.com/yop-platform/yop-php-sdk)
- .NET SDK (yop-dotnet-sdk)：需要 .NET Framework 2.0 及以上版本，[GitHub](https://github.com/yop-platform/yop-dotnet-sdk)，不支持Windows Phone平台
- TypeScript SDK (yop-typescript-sdk)：需要 Node.js 18.0.0 及以上版本，[GitHub](https://github.com/yop-platform/yop-typescript-sdk)，[NPM](https://www.npmjs.com/package/yop-typescript-sdk)，安装方法：`npm i yop-typescript-sdk`
- Node.js SDK (yop-nodejs-sdk)：需要 Node.js 18.0.0 及以上版本，[GitHub](https://github.com/yop-platform/yop-nodejs-sdk)，[NPM](https://www.npmjs.com/package/yop-nodejs-sdk)，安装方法：`npm i yop-nodejs-sdk`
- Python SDK (yop-python-sdk)：需要 Python 2.7 及以上版本，[GitHub](https://github.com/yop-platform/yop-python-sdk)
- Go SDK (yop-go-sdk)：建议使用 Go 1.18 及以上版本，[GitHub](https://github.com/yop-platform/yop-go-sdk)

**2. 密钥工具**
- 密钥工具 V3.1：最新版本，支持 Windows/Mac/Linux 多平台
- 密钥工具 V2.0：支持常规密钥操作
- 密钥工具 V1.0：旧版本，仅提供基础功能

**3. 开发者服务套件**
- IntelliJ IDEA 插件：提供代码生成、接口调试等功能
- VSCode 插件：提供可视化操作界面，自动生成规范代码，集成测试功能

**4. 其他工具**
- 在线接口测试工具：支持快速验证接口功能和参数配置
- 调试日志实时查看功能：便于问题精准定位和高效排查
- 交易明细自助查询工具：提升运营效率和数据分析能力

### 鉴权认证机制说明

易宝开放平台采用严格的鉴权认证机制，确保API调用的安全性和可靠性：

**1. 鉴权认证串结构**
鉴权认证通过 HTTP 头部的 Authorization 字段实现，格式为：
```
Authorization: securityReq authString/signedHeaders/signature
```

**2. 安全需求(securityReq)**
- YOP-RSA2048-SHA256：使用RSA2048算法和SHA256哈希函数

**3. 认证字符串(authString)**
认证字符串由以下部分组成：
- 协议版本(protocolVersion)：当前为 "yop-auth-v3"
- 应用标识(appKey)：您的应用Key
- 时间戳(timestamp)：请求时间，格式为 ISO8601 标准
- 签名有效时长(expiredSeconds)：签名的有效持续时间，单位为秒

**4. 签名头(signedHeaders)**
由规范标头中的标头名称列表组成，告知平台请求中的哪些标头是签名过程的一部分。标头名称按ASCII顺序排序，多个标头名称以分号分隔。

**5. 签名(signature)**
由商户私钥和规范请求生成，通常使用 SHA256withRSA 算法。签名过程是对规范请求生成摘要，然后用私钥对摘要进行加密。

### 报文加解密机制说明

为保障数据传输安全，易宝开放平台提供了完整的报文加解密机制：

**1. 加密信息传递**
加密信息通过请求头 x-yop-encrypt 传递，格式为：
```
{YOP加密协议版本}/{平台证书序列号}/{密钥类型}_{分组模式}_{填充算法}/{加密密钥值}/{IV}{;}{附加信息}/{客户端支持的大参数加密模式}/{encryptHeaders}/{encryptParams}
```

**2. 加密算法**
- 目前支持的算法：AES_ECB_PKCS5Padding
- 密钥生成：使用随机AES密钥加密请求参数
- 密钥保护：使用平台RSA公钥加密AES密钥

**3. 加密范围**
- 可以对请求参数进行加密，对于JSON格式数据可整体加密
- 支持对请求头进行加密（YOP指定的请求头除外）
- 支持流式加密模式处理大数据

**4. 密钥管理**
- 平台RSA公钥：通过商户后台或API获取
- 为确保安全，建议定期更新密钥

### 结果通知机制说明

为保证数据的一致性，易宝开放平台提供了可靠的结果通知机制：

**1. 通知方式**
- 异步通知：通过POST请求以FORM格式将业务处理结果通知到商户系统
- 通常情况下，只有业务处理成功的订单才会触发异步通知（特殊情况会在具体的异步通知文档中提及）

**2. 通知原则**
- **幂等性**：同样的通知可能会多次发送给商户系统，商户系统必须能够正确处理重复的通知
- **时效性**：在极少情况下可能发生异步通知无法正常通知的情况，商户应对接主动查单接口
- **防抵赖**：商户系统对异步通知的内容一定要做签名验证，并校验通知的信息是否与商户侧的信息一致

**3. 通知频率**
如果商户未按正常处理做出应答，易宝将认为该次通知是失败的，间隔一定时间后会尝试再次通知。一般情况下，24小时以内会完成多次异步通知，通知的间隔频率一般是：5s、10s、15s、30s、240s、600s、2700s、3600s、14400s。

**4. 通知处理要求**
- 商户应在5秒内完成处理并返回结果，否则可能会导致延迟通知或重复通知
- 正确应答格式：HTTP状态码200，报文体为字符串"SUCCESS"
- 根据使用的密钥类型，商户侧收到的报文格式和解密验签方式存在细微差异

### 平台商密证书更新指引

从2021年3月起，凡启用商密算法的商户（RSA算法不受此影响），平台使用CFCA颁发的支持商密算法的平台证书标识易宝开放平台的身份信息。出于合规和安全性考虑，这些证书设置了有效期，商户需在证书过期前进行更新。

**1. 新旧平台证书的平滑切换机制**
- 易宝开放平台兼容使用新旧平台证书
- 旧平台证书过期前5天至过期当天，新证书开始逐步放量用于应答和回调的签名
- 平台在所有API应答的HTTP头部增加了x-yop-serial-no，声明了此次签名所对应的平台证书的序列号

**2. 最佳实践**
- 方式一：使用易宝开放平台提供SDK（建议）
  - SDK默认为"惰性加载"的方式实现平滑切换
  - 当业务逻辑服务上没有证书序列号所对应的证书时，自动调用API获取对应的平台证书
  - 可以主动调用SDK的reload()方法，触发证书加载机制
- 方式二：商户自实现SDK
  - 自行实现平台证书的加载机制
  - 根据报文头部的证书序列号找到对应的平台证书
  - 对证书进行多级缓存，提升服务器性能
  - 缓存中找不到对应证书时，立即调用API获取新的平台证书
  - 系统中已有的易宝开放平台证书在到达有效期后应主动作废

### 平台错误码说明

易宝开放平台提供了详细的错误码体系，帮助开发者准确定位和解决问题：

**1. 主要错误码类型**

| 错误码 | 错误描述 | 典型子错误码 | 解决方案 |
|-------|---------|------------|---------|
| 40020 | 服务不可用 | sys.service.retryable | 联系技术支持，核实失败原因，稍后再试 |
| 40021 | 授权权限不足 | sys.authorization.unauthorized | 找服务提供方授权开通相关产品 |
| 40029 | 访问受限 | sys.limit.rate-limit | 适当降低请求频率或联系服务提供者放宽配额 |
| 40042 | 非法的参数 | isv.check.request-param.miss | 查询API文档，检查必填参数是否缺失 |
| 40044 | 业务处理失败 | isp.code.xxx | 查询API文档，如有疑问请联系技术支持 |
| 40047 | 鉴权认证失败 | isv.authentication.digest.verify-failure | 检查密钥是否正确，检查公私钥是否匹配 |
| 40048 | 加解密异常 | isv.encrypt.param.decrypt-failure | 确认当前调用环境与平台公钥配置是否一致 |

**2. 错误处理建议**
- 根据错误码判断错误类型，采取相应措施
- 临时性错误可以重试，永久性错误需要修正请求内容
- 对于授权或配置类错误，及时联系技术支持
- 参数错误应查阅API文档进行修正
- 频率限制需优化调用策略，必要时申请更高配额 


## 产品能力与API能力汇总

易宝开放平台提供了丰富的产品能力与API接口，帮助开发者高效集成各类支付与金融服务能力。本章节将对平台提供的核心产品及其关联API进行详细介绍，方便开发者根据业务需求选择适合的产品和接口。

### 收单 (acquiring)

#### 产品介绍

收单服务为商家提供协助用户完成在商家的采买行为的资金处理服务，支持单笔支付以及合并支付，同时集成通知、查询等全链路接口交互能力。主要特性包括：

1. **合并支付订单**：将多个独立订单合并为一个支付请求，用户支付一次，支付款项最终结算给多个收单商家。特点：
   - 用户可以一笔支付多个商户商品
   - 各商户收款资金分别入各收款商户账户
   - 每个商户有各自的手续费收费策略
   - 订单区分管理

2. **延迟结算订单**：支付成功后，资金进入商户在易宝开立的分账账户，按照商户在易宝预设的规则，或者商户的请求，清分给其他合作方商户。适用于平台类交易（如淘宝佣金分账）和供应链多级分销场景。

3. **实时分账订单**：支付成功后，资金按接口指定的分账规则实时分配给多个合作商户。适用于商户在下单时即可知晓分账接收方信息、分账金额的商户。

4. **预授权/预消费订单**：支付前先冻结用户账户中的部分资金（如押金），交易完成后再扣除实际消费金额，解冻剩余部分。适用于酒店预订、租车、信用住等场景。

5. **冲正订单**：允许对特定情况下的交易进行冲正操作，确保资金安全。

#### 接入指引

##### 合单接入指引：

**服务简介**：
提供用户一笔支付多个商户的商品，合单支付款项分别进入到合单中收款商户各自的账户。电商平台可跟业务需要，叠加分账服务，从商户的交易资金中收取平台佣金。

**使用场景**：
1. 电商平台购物车：在平台购物车场景，用户将平台上不同商家的商品加入到购物车，提交订单一笔支付。用户支付成功后，合单支付款项分别进入到各商户的账户中。
2. 机票+酒店+保险组合产品搭售：商户在OTA平台购买机票+酒店+保险组合产品，完成一笔支付。用户支付后，合单支付款项分别入给航空公司、酒店及保险公司账户中。

**开发流程**：
1. 先通过[交易下单](/docs-v2/apis/acquiring/post__rest__v1.0__trade__order)接口创建订单，在子单域信息字段中传入子单信息。如子单需要进行分账，需要在subOrderDetail子单域信息中传入分账标识。
2. 订单创建后，易宝返回支付授权token。商户再使用该token调起相应支付。
3. 如需查询合并收款订单主单及对应子单相关信息，可通过[查询合并订单](/docs-v2/apis/acquiring/get__rest__v1.0__trade__order__combine-query)接口进行查询；如需查询合并收款某一子单相关信息，还可通过[查询订单](/docs-v2/apis/acquiring/get__rest__v1.0__trade__order__query)接口进行查询。
4. 如需对合并收款订单进行[关单](/docs-v2/apis/acquiring/post__rest__v1.0__trade__order__close)、退款、分账，可通过调用相应接口进行后续处理。

#### API列表

1. **交易下单** (POST /rest/v1.0/trade/order)
   - 支持标准交易下单（单笔），也支持合单收款交易下单（可以实现多商户订单用户一笔付款）
   - 合单收款请在subOrderDetail里上送订单明细，目前最多一次可支持60笔订单进行合单收款

2. **查询订单** (GET /rest/v1.0/trade/order/query)
   - 商户可以通过查询订单接口主动查询订单状态，完成下一步的业务逻辑

3. **查询合并订单** (GET /rest/v1.0/trade/order/combine-query)
   - 商户通过该接口查询合单收款请求中的订单信息

4. **关闭订单** (POST /rest/v1.0/trade/order/close)
   - 支持商户对未支付的订单进行关单，易宝受理请求后返回关单结果
   - 对合单进行关单时，入参merchantNo字段需为空

5. **查询商户交易服务配置** (GET /rest/v1.0/trade/config/template/query)
   - 查询商户交易服务配置信息

6. **操作商户交易服务配置** (POST /rest/v1.0/trade/config/template/operate)
   - 新增、修改商户交易服务配置

7. **删除商户交易服务配置** (POST /rest/v1.0/trade/config/template/delete)
   - 删除商户交易服务配置

### APP支付 (app-payment)

#### 产品介绍

APP支付是指商家在商家移动端APP中下单，跳转到微信/支付宝/云闪付来完成付款。支持微信、支付宝、银联等多种支付方式，为移动应用提供便捷的支付体验。

当前版本：20250117185822

#### 接入指引

1. 申请开通APP支付产品
2. 根据支付渠道要求配置相应的参数
3. 集成SDK或按照接口文档进行开发
4. 测试验证支付流程
5. 提交上线申请

#### API列表

相关API接口请参考产品详情页的API文档。

### JSAPI支付 (jsapi-payment)

#### 产品介绍

JSAPI支付是一种适用于特定环境下的支付方式，主要包括以下场景：

- **微信公众号支付**：商户拥有微信公众号商城，用户在微信内打开商户的H5页面，并在该页面调起微信支付完成付款。
- **支付宝生活号支付**：商户拥有支付宝生活号商城，用户进入商家的生活号，并在生活号内调用支付宝支付完成下单购买流程。
- **银联JS支付**：用户使用云闪付APP，在银联云闪付环境下扫码或在应用内完成支付。常见场景如商户包装聚合台牌，用户扫码完成支付。

当前版本：20250120140204

#### 接入指引

##### 接入准备

1. 对接公众号支付，需完成appid配置
2. 若商户自行包装台牌，台牌支持银联云闪付扫码，需联系易宝运营向银联申请配置域名，否则用户支付时会弹出提示，影响体验

##### 对接流程

**非合单支付流程**：
1. 商户请求【聚合支付统一下单接口】发起下单
2. 易宝将下单请求转发给微信/支付宝/银联云闪付
3. 支付渠道返回下单结果给易宝
4. 易宝返回预支付标识给商户
5. 商户根据支付场景调起支付：
   - 主扫：展示二维码（微信主扫需预先配置APPID、授权回调地址）
   - 公众号/生活号/小程序/银联SDK：调起支付控件（微信小程序需预先配置APPID；微信公众号需预先配置APPID、支付授权目录、授权回调地址；银联SDK需预先下载并集成）
   - 银联H5：移动端浏览器发起post请求
   - 银联JS：重定向到返回的URL
6. 用户在支付渠道完成支付
7. 支付结果通知流转：支付渠道 → 易宝 → 商户

##### 重点配置说明

商户需按扫码、JSAPI、APP等不同场景生成的交易串调起支付，需特别注意以下配置：
- 微信公众号：需配置APPID、支付授权目录、授权回调地址
- 微信小程序：需配置APPID
- 银联支付：需遵循银联规范配置参数

#### API列表

1. **公众号配置接口（异步）** (POST /rest/v2.0/aggpay/wechat-config/add)
   - 用于配置支付授权目录、支付appid等信息
   - 可配置多个appId及对应类型（公众号/小程序）
   - 支付授权目录最多可配置5条，微信侧有严格的校验规则

2. **公众号配置查询** (GET /rest/v2.0/aggpay/wechat-config/query)
   - 支持商户查询公众号或小程序的支付授权目录、支付appid配置

3. **查询订单** (GET /rest/v1.0/trade/order/query)
   - 商户可以通过查询订单接口主动查询订单状态，完成下一步的业务逻辑

4. **聚合关单** (POST /rest/v1.0/aggpay/close-order)
   - 支持关闭待支付订单，以渠道（微信/支付宝）的关单结果为准
   - 受限于渠道能力，目前仅支持微信、支付宝关单，不支持银联和数字人民币的关单

5. **聚合支付统一下单** (POST /rest/v1.0/aggpay/pre-pay)
   - 统一支付下单接口，支持多种支付方式

6. **退款相关接口**
   - 申请退款 (POST /rest/v1.0/trade/refund)：交易后如需退款，将支付款退还给付款方
   - 查询退款 (GET /rest/v1.0/trade/refund/query)：查询退款状态
   - 申请合单退款 (POST /rest/v1.0/trade/refund/combine)：合并支付订单的退款处理
   - 查询合单退款 (GET /rest/v1.0/trade/refund/combine-query)：查询合单退款状态
   - 申请极速退款 (POST /rest/v1.0/trade/refund/fast)：将退款金额直接退到指定银行卡账户
   - 上传卡信息退款 (POST /rest/v1.0/trade/refund/supply)：原路退款失败时使用
   - 结束退款 (POST /rest/v1.0/trade/refund/end)：结束退款流程，将资金退回商户账户

### H5支付 (h5-payment)

#### 产品介绍

H5支付是指商户在微信/支付宝/银联客户端外的移动端网页展示商品或服务，用户在确认使用微信/支付宝/银联支付时，浏览器跳转网页完成付款。主要应用于触屏版的手机浏览器请求支付的场景，方便从外部浏览器唤起支付。

支持的支付方式：
- 微信H5支付
- 支付宝H5支付
- 银联H5支付

当前版本：20250117184115

#### 接入指引

##### 接入准备

1. **微信支付**：
   - 易宝提供小程序，商户需完成微信侧报备，并进行实名认证
   - 报备成功后，在易宝侧配置appid信息
   - 若使用易宝小程序：商户需要配置appid（由易宝运营处理）
   - 若使用商户小程序：需提供APPID、APPSECRET和小程序入口页URL

2. **支付宝支付**：
   - 商户需完成支付宝侧报备，并进行实名认证

##### 支付流程

1. 商家H5/APP商城内下单
2. 拉起支付环境，进入支付页面
3. 用户确认支付，输入支付密码
4. 完成支付并显示结果
5. 退出支付流程，返回商户页面

#### API列表

H5支付使用与JSAPI支付相同的API接口体系，主要包括：

1. **聚合支付统一下单** (POST /rest/v1.0/aggpay/pre-pay)
   - 统一支付下单接口，支持多种支付方式

2. **查询订单** (GET /rest/v1.0/trade/order/query)
   - 用于查询订单状态

3. **聚合关单** (POST /rest/v1.0/aggpay/close-order)
   - 用于关闭未支付的订单

4. **退款相关接口**
   - 与JSAPI支付共用退款接口体系

### 绑卡支付 (bindcard-payment)

#### 产品介绍

绑卡支付是指用户将银行卡与支付账户进行绑定，之后可以使用已绑定的银行卡进行便捷的支付操作。这种支付方式结合了快捷支付和用户账户体系，提供更安全、便捷的支付体验。

主要特点：
- 首次使用需绑定银行卡并验证身份信息
- 绑定成功后，后续支付只需输入支付密码或验证码即可完成
- 支持借记卡和信用卡绑定
- 提供更高的支付安全性和便捷性

当前版本：20250121103139

#### 接入指引

##### 接入流程

1. **开通绑卡支付产品**
   - 商户需与易宝签约，开通绑卡支付产品权限
   - 完成商户入网审核和配置工作

2. **绑卡流程**
   - 用户首次使用需完成银行卡绑定
   - 商户调用绑卡接口发起请求
   - 用户输入银行卡信息（卡号、持卡人姓名、身份证号、手机号等）
   - 发送短信验证码并完成验证
   - 绑卡成功后获取绑卡ID，可用于后续支付

3. **支付流程**
   - 商户调用支付接口，使用已绑定的卡进行支付
   - 用户完成验证（如输入支付密码或验证码）
   - 支付成功后，商户接收支付结果通知

##### 安全建议

- 敏感信息（如卡号、CVV等）传输必须使用加密通道
- 遵循支付行业PCI-DSS规范，不在商户系统存储完整的银行卡信息
- 建议实施交易风控措施，如设置交易限额、异常交易检测等

#### API列表

1. **绑卡请求** 
   - 用于发起银行卡绑定流程，获取绑卡ID

2. **绑卡确认** 
   - 确认绑卡操作，验证短信验证码，完成绑卡流程

3. **解绑银行卡** 
   - 解除已绑定的银行卡关系

4. **查询绑定卡列表** 
   - 查询用户已绑定的银行卡列表

5. **绑卡支付** 
   - 使用已绑定的银行卡发起支付

6. **支付短信验证** 
   - 验证支付短信码，完成支付流程

7. **支付结果查询** 
   - 查询支付交易的结果状态

8. **退款相关接口**
   - 提供退款申请、退款查询等功能

绑卡支付为商户提供了连接用户银行账户的能力，特别适用于需要重复付款或订阅服务的场景，能够显著提升用户支付体验和成功率。

### 更多产品

易宝开放平台还提供了更多产品和服务，包括但不限于：

1. **JSAPI支付**：支持微信公众号、支付宝生活号等场景下的支付需求
2. **网银支付**：提供PC端网上银行支付服务
3. **H5支付**：适用于移动端浏览器环境下的支付场景
4. **账户体系服务**：提供账户开立、充值、提现、转账等完整功能
5. **分账服务**：支持交易资金的分配与结算
6. **对账服务**：提供交易对账与资金对账能力

每个产品均有详细的接入文档和示例代码，开发者可以根据业务需求选择适合的产品进行集成。详情请参考相关产品的详细文档。

### 网银支付 (e-bank-payment)

#### 产品介绍

网银支付，即网上银行支付，是指消费者在网上银行页面输入其账户信息，通过银行提供的验证方式（如U盾，支付密码等）后完成付款的支付方式，主要适用于PC端。目前已支持20余家银行，覆盖最广泛的企业和个人用户。

网银支付可支持的单笔金额高，适用于以下场景：

- **企业网银支付（B2B）**：应用于商户和机构企业的B2B交易，适用场景包括电子商务行业交易市场、大宗交易电子商务平台、行业供应链、招投标类、公共服务类领域，以及保险、物流等其它行业领域。
- **个人网银支付（B2C）**：应用于商户和消费者的B2C交易，使用场景包括电商平台、保险、租车、O2O商户、教育、航空等。

当前版本：20250117112401

#### 接入指引

##### 接入流程

1. **开通网银支付产品权限**
   - 商户需与易宝签约，开通网银支付产品权限
   - 完成商户入网审核和配置工作

2. **对接流程**
   - 商户系统发起下单请求
   - 易宝接收请求并生成支付订单
   - 用户通过网银界面进行支付
   - 支付完成后，易宝通过异步通知告知商户支付结果
   - 商户可主动查询订单状态

3. **页面跳转**
   - 商户在订单创建成功后，引导用户跳转到银行支付页面
   - 用户完成支付后，根据配置返回到商户指定页面

#### API列表

1. **网银支付订单接口** (POST /rest/v1.0/netpay/order)
   - 通过该接口可以接入网银B2B订单支付
   - 统一下单接口，商户可直接调用该接口，直接推送订单至企业网银
   - 支付完成后，易宝异步通知商户支付结果

### 收银台 (cashier)

#### 产品介绍

收银台是易宝提供的标准化支付页面解决方案。商户在请求易宝完成下单后，可以直接前端页面跳转至易宝收银台页面，用户在收银台页面完成后续支付流程，支付完成会跳转回到商户页面（下单时商户指定的页面地址）。

收银台的主要特点：
- 提供统一、安全、美观的支付界面
- 支持多种支付方式整合，包括网银支付、快捷支付、扫码支付等
- 自适应PC端和移动端
- 可根据商户需求进行定制化配置

当前版本：20250120192442

#### 接入指引

##### 接入流程

1. **交易下单**
   - 商户通过易宝API发起交易下单请求
   - 易宝返回订单token

2. **组装收银台URL**
   - 商户根据API规范，使用订单token组装收银台URL
   - 参数中可指定支付完成后的返回页面地址

3. **跳转收银台**
   - 商户前端页面跳转至易宝收银台
   - 用户在收银台选择支付方式并完成支付

4. **支付结果处理**
   - 易宝通过异步通知告知商户支付结果
   - 支付完成后，用户被重定向回商户指定页面
   - 商户可通过订单查询接口主动查询支付状态

#### API列表

1. **交易下单接口**
   - 用于创建支付订单，获取订单token

2. **收银台URL组装规则**
   - 提供标准化参数拼接规则，生成跳转URL

3. **订单查询接口**
   - 查询交易订单的支付状态

4. **支付结果通知**
   - 接收易宝的支付结果异步通知

### 协议支付 (agreement-payment)

#### 产品介绍

协议支付是指在用户授权同意的情况下，商户可基于签订的支付协议，在后续交易中代用户发起支付指令完成交易的支付方式。它结合了快捷支付和免密支付的特点，简化了支付流程，提高了支付效率。

主要特点：
- 用户首次使用需要签订支付协议并授权
- 后续交易无需用户再次输入银行卡信息或进行验证
- 适用于固定、周期性支付场景
- 提供更便捷的支付体验，提高交易成功率

当前版本：20250121103136

#### 接入指引

##### 接入流程

1. **协议签订**
   - 用户首次使用需完成协议签订和授权
   - 商户调用协议签订接口发起请求
   - 用户输入银行卡信息并进行身份验证
   - 完成支付协议签订，获取协议ID

2. **协议支付**
   - 商户使用已签订的协议ID发起支付
   - 系统根据协议信息完成支付处理
   - 支付结果通过异步通知告知商户

3. **协议管理**
   - 查询用户已签订的协议
   - 解除已签订的协议
   - 更新协议相关信息

#### API列表

1. **协议签订接口**
   - 用于发起支付协议签订流程

2. **协议支付接口**
   - 使用已签订的协议发起支付交易

3. **协议查询接口**
   - 查询协议信息及状态

4. **协议解除接口**
   - 解除已签订的支付协议

5. **支付结果查询接口**
   - 查询协议支付交易的结果状态

### 钱包 (docking-wallet)

#### 产品介绍

钱包服务为商户提供会员账户体系解决方案，支持会员账户充值、支付、提现、注销、查询会员积分等功能；同时支持商户给会员发放营销红包等营销活动。

主要功能：
- 会员账户管理
- 账户充值与提现
- 钱包支付
- 积分管理
- 营销红包发放
- 账户资金明细查询

当前版本：20250117112354

#### 接入指引

##### 接入流程

1. **会员账户开通**
   - 商户调用接口为用户开通钱包账户
   - 完成用户身份认证和绑定

2. **账户充值**
   - 用户通过多种支付方式为钱包账户充值
   - 支持网银、快捷支付等充值渠道

3. **钱包支付**
   - 用户使用钱包余额完成支付
   - 支持密码验证或免密支付

4. **账户提现**
   - 用户将钱包余额提现至银行卡
   - 支持实时提现和批量提现

5. **营销活动**
   - 商户为会员发放红包、优惠券等
   - 支持多种营销策略和规则设置

#### API列表

1. **会员账户管理**
   - 开通会员账户
   - 账户信息查询
   - 账户状态管理

2. **资金操作**
   - 账户充值
   - 账户提现
   - 余额支付
   - 资金冻结/解冻

3. **积分管理**
   - 积分发放
   - 积分查询
   - 积分消费

4. **营销工具**
   - 红包发放
   - 优惠券管理
   - 活动配置

5. **对账服务**
   - 交易记录查询
   - 对账单下载
   - 资金流水查询

钱包服务为商户提供了完整的用户资金账户解决方案，适用于需要建立自有会员体系、提升用户粘性和促进交易的各类商户。 