代收接口（Payin）
概述
代收接口用于创建代收订单，处理收款业务。商户可以通过此接口向用户发起收款请求，支持多种支付方式。
接口信息
- 接口地址：
POST /api/mx/payin - 请求方式：POST
- Content-Type：application/json
请求头
所有 API 请求都需要在请求头中包含以下参数，详见 API签名规范：
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
| Content-Type | string | Y | application/json，固定值 |
| MerchantId | string | Y | 商户 ID，由 Veloraya 提供 |
| Timestamp | string | Y | 当前时间戳（毫秒），防止重放攻击 |
| Nonce | string | Y | 随机字符串，防重放攻击，每次请求唯一 |
| Signature | string | Y | 请求签名（RSA签名），Base64编码 |
请求参数
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
| merchantOrderId | string | Y | 商户订单号，唯一标识 |
| amount | BigDecimal | Y | 订单金额（最多 2 位小数） |
| currency | string | Y | 货币代码，如：MXN |
| expireSeconds | Integer | N | 过期时间（秒），默认 3 天 |
| payinMethod | string | Y | 支付方式，见支付方式枚举 |
| payerEmail | string | N | 付款人邮箱 |
| payerIdType | string | N | 付款人证件类型，见证件类型枚举 |
| payerIdCard | string | N | 付款人证件号 |
| payerMobile | string | N | 付款人手机号 |
| payerName | string | N | 付款人姓名 |
| redirectUrl | string | N | 重定向地址 |
- amount：订单金额，最多 2 位小数，单位 MXN
- payinMethod：固定 CLABE
- expireSeconds：过期时间（秒），15min～7 天，默认 3 天
- payerIdCard：付款人证件号 / RFC（13 位）
支付方式枚举
| 值 | 说明 |
|---|---|
| CLABE | CLABE 参考号（SPEI 转账入账） |
证件类型枚举
| 值 | 说明 |
|---|---|
| RFC（墨西哥税号） |
请求示例
json
{
"merchantOrderId": "ORDER5187977827671717",
"amount": 100,
"currency": "MXN",
"payinMethod": "PAYMENT_METHOD",
"payerEmail": "user@example.com",
"payerMobile": "09123456789",
"payerName": "Payer Name"
}响应格式
所有接口的响应都采用统一的 JSON 格式，包含以下字段：
| 参数名 | 类型 | 说明 |
|---|---|---|
| code | int | 响应码，200 表示成功，非 200 表示失败 |
| msg | string | 响应消息 |
| data | object | 响应数据，成功时包含订单信息 |
响应参数（data 字段）
| 参数名 | 类型 | 说明 |
|---|---|---|
| orderId | string | 平台订单号 |
| merchantOrderId | string | 商户订单号 |
| amount | BigDecimal | 订单金额 |
| fee | BigDecimal | 手续费 |
| payDeskUrl | string | 收银台地址 |
| orderStatus | string | 订单状态，见订单状态枚举 |
| resultCode | string | 错误码（错误时有值） |
| resultDesc | string | 错误结果描述（错误时有值） |
订单状态枚举
| 值 | 说明 |
|---|---|
| PENDING | 支付中 |
| SUCCESS | 支付成功 |
| FAILED | 支付失败 |
响应示例
成功响应
json
{
"code": 200,
"msg": "SUCCESS",
"data": {
"orderId": "PAYIN1991084006458683392",
"merchantOrderId": "ORDER5187977827671717",
"amount": 100,
"fee": 0,
"payDeskUrl": "https://paydesk.example.com/pay/PAYIN1991084006458683392",
"orderStatus": "PENDING"
}
}业务规则
- 订单号唯一性：商户订单号在同一商户下必须唯一
- 金额限制：单笔订单金额不能超过系统设定的限额
- 过期时间：订单过期后无法继续支付，默认过期时间为 3 天
- 异步通知：订单状态变更会通过 代收回调接口 通知商户（需要商户配置通知地址）
- 风控检测：系统会对订单进行风控检测，检测失败会返回错误
注意事项
- 请求头：必须在请求头中传入所有必需的参数（Content-Type、MerchantId、Timestamp、Nonce、Signature），详见 API签名规范
- 签名验证：所有请求必须包含正确的签名
- 异步通知：订单状态变更会通过异步通知接口通知商户
- 幂等性：相同商户订单号的重复请求会返回相同结果，不会重复创建订单
- 超时处理：建议设置合理的请求超时时间
- 日志记录：建议记录所有请求和响应日志