代付接口（Payout）

概述

代付接口用于创建代付订单，处理付款业务。商户可以通过此接口向用户发起付款请求，支持银行和电子钱包账户。

接口信息

• 接口地址：POST /api/ar/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	商户订单号，唯一标识
amount	BigDecimal	Y	订单金额
currency	string	Y	货币代码，当前固定 ARS
accountType	string	Y	账户类型，见账户类型枚举
payeeAccountNo	string	Y	收款账号
payeeName	string	N	收款人姓名，长度 1-128
payeeLastName	string	N	收款人姓氏，长度 1-128
payeeFullName	string	N	收款人全称（与 payeeName+payeeLastName 二选一必填，请优先使用payerFirstName+payerLastName）
payeeIdType	string	Y	收款人证件类型，见证件类型枚举
payeeIdCard	string	Y	收款人证件号
payeeMobile	string	Y	收款人手机号
payeeEmail	string	Y	收款人邮箱（需符合邮箱格式）

账户类型枚举

值	说明
CVU	CVU 账户
CBU	CBU 账户

证件类型枚举

值	说明
CUIT	阿根廷税号

请求示例

{
  "merchantOrderId": "Order33666279",
  "amount": 5100,
  "currency": "ARS",
  "accountType": "CVU",
  "payeeName": "Beneficiary Name",
  "payeeAccountNo": "8692634925111",
  "payeeIdType": "DNI",
  "payeeIdCard": "2071871354",
  "payeeMobile": "13851585444",
  "payeeEmail": "test@gmail.com"
}

响应格式

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

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

响应参数（data 字段）

参数名	类型	说明
merchantId	string	商户 ID
orderId	string	平台订单号
merchantOrderId	string	商户订单号
orderStatus	string	订单状态，PENDING-支付中，FAILED-失败
amount	BigDecimal	订单金额
currency	string	货币代码，默认 ARS
fee	BigDecimal	交易手续费
errorCode	string	错误码（错误时有值）
errorMsg	string	错误结果描述（错误时有值）
createDatetime	string	订单创建时间
completionDatetime	string	订单完成时间（未完成时为 null）

订单状态枚举

值	说明
PENDING	支付中
FAILED	失败

响应示例

建单成功

{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "merchantId": "602255",
    "orderId": "PAYOUT2059898253450452992",
    "merchantOrderId": "Order33666279",
    "orderStatus": "PENDING",
    "amount": 5100,
    "currency": "ARS",
    "fee": 51.00,
    "errorCode": null,
    "errorMsg": null,
    "createDatetime": "2026-05-28 14:23:09",
    "completionDatetime": null
  }
}

建单失败

{
  "msg": "amount must be an integer without decimal places",
  "code": 1001
}

错误码说明

详见 错误码 文档中的完整错误码列表。

注意事项

1. 请求头：必须在请求头中传递所有必需的请求头（Content-Type、MerchantId、Timestamp、Nonce、Signature），详见 API签名规范
2. 签名验证：所有请求必须包含正确的签名（由网关过滤器验证）
3. 异步通知：订单状态变更会通过 代付回调接口 通知商户（商户需配置通知 URL）
4. 幂等性：相同商户订单号的重复请求会失败，系统不会创建重复订单
5. 订单状态：需区分 HTTP 响应码（200 表示请求成功）与最终代付结果（以 data.orderStatus 为准）