代付接口（Payout）

概述

代付接口用于创建代付订单，处理付款业务。商户可以通过此接口向用户发起付款请求，支持多种付款方式。

接口信息

• 接口地址：POST /api/ec/payout
• 请求方式：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	商户订单号，唯一，长度 1-32
amount	BigDecimal	Y	订单金额，必须大于 0.01，最多 2 位小数
currency	string	Y	货币代码，当前固定USD
accountType	string	Y	账户类型，见账户类型枚举
bankCode	string	Y	代付银行编码
payeeAccountNo	string	Y	收款人账号，长度 1-32
payeeName	string	Y	收款人姓名，长度 1-128
payeeIdType	string	Y	收款人证件类型，见证件类型枚举
payeeIdCard	string	Y	收款人证件号
payeeMobile	string	Y	收款人手机号
payeeEmail	string	Y	收款人邮箱（需符合邮箱格式）

账户类型枚举

值	说明
AHORRO	储蓄账户
CORRIENTE	往来 / 支票账户

证件类型枚举

值	说明
CI	厄瓜多尔国民身份证

请求示例

{
  "merchantOrderId": "Order86271446",
  "amount": 115.10,
  "accountType": "BANK",
  "bankCode": "BBL",
  "payeeName": "Beneficiary Name",
  "payeeAccountNo": "45473421954",
  "payeeMobile": "09123456789",
  "payeeEmail": "user@example.com",
  "currency": "USD"
}

响应格式

所有接口的响应都采用统一的 JSON 格式，包含以下字段：

参数名	类型	说明
code	int	响应码，200 表示成功，非 200 表示失败
msg	string	响应消息
data	object	响应数据，成功时包含订单信息

响应参数（data 字段）

参数名	类型	说明
orderId	string	平台订单号
merchantOrderId	string	商户订单号
orderStatus	string	订单状态，见订单状态枚举
amount	BigDecimal	订单金额
currency	string	货币代码
fee	BigDecimal	手续费
errorCode	string	错误码（错误时有值）
errorMsg	string	错误信息（错误时有值）
createDatetime	LocalDateTime	订单创建时间
completionDatetime	LocalDateTime	订单完成时间（未完成时为 null）

订单状态枚举

值	说明
PENDING	支付中
FAILED	支付失败

响应示例

成功响应

{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "orderId": "PAYOUT1991086732408156160",
    "merchantOrderId": "Order86271446",
    "orderStatus": "PENDING",
    "amount": 115.10,
    "currency": "USD",
    "fee": 0,
    "createDatetime": "2024-01-01 10:00:00"
  }
}

错误码说明

更多错误码详情请参见 错误码。

注意事项

• 请求头：必须在请求头中传入所有必需的参数（Content-Type、MerchantId、Timestamp、Nonce、Signature），详见 API签名规范
• 签名验证：所有请求必须包含正确的签名（通过网关过滤器验证）
• 异步通知：订单状态变更会通过 代付回调接口 通知商户（需要商户配置通知地址）
• 幂等性：相同商户订单号的重复请求会返回失败，不会重复创建订单
• 订单状态：注意区分 HTTP 响应码（200 表示请求成功）和订单状态（data.orderStatus 表示代付结果）