代收接口（Payin）

概述

代收接口用于创建代收订单，处理收款业务。商户可以通过此接口向用户发起收款请求，支付方式为CVU转账，用户填写证件信息下单调用该接口，通过接口返回的链接获取CVU账号，用户转账给该CVU，本系统收到款项后将通过证件号+金额+过期时间来自动进行匹配完成订单。

两种代收模式

阿根廷代收支持两种模式，两种模式互斥、不可共存，商户需在开通前确认使用哪种模式，每个商户仅支持其中一种；如需同时使用两种方式，请联系商务开通两个商户：

订单模式（本接口）：商户先下单，用户通过收银台获取共享 CVU 转账，平台按证件号+金额+过期时间匹配；
独立 CVU 模式（VA_DIRECT）：商户拥有专属绑定 CVU，用户直接转账，平台自动建单并推送入金明细回调。该模式无需调用本接口，详情见独立CVU入金回调。

接口信息

接口地址：POST /api/ar/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	订单金额，校验商户风控配置
currency	string	Y	货币代码，当前固定 ARS
expireSeconds	Integer	N	支付信息页过期时间（秒），范围：300s~86400s，不传则默认 24h
payinMethod	string	Y	支付方式，见支付方式枚举
redirectUrl	string	N	付款成功跳转地址
payerEmail	string	Y	付款人邮箱
payerIdType	string	Y	付款人证件类型，固定 DNI
payerIdCard	string	Y	付款人证件号，必须为真实信息
payerFirstName	string	N	付款人名字
payerLastName	string	N	付款人姓氏
payerFullName	string	N	付款人全称（与 payerFirstName+payerLastName 二选一必填，请优先使用payerFirstName+payerLastName）
payerMobile	string	Y	付款人手机号
needSecondaryConfirmation	boolean	N	是否需要二次确认用户信息,不传则默认为true

如果needSecondaryConfirmation为是，收银台页面首先进入确认用户信息页面，点击确认并继续按钮后显示收款账号页面：

点击确认并继续按钮显示的页面，如果needSecondaryConfirmation为false，收银台页面将直接进入该页面

支付方式枚举

值	说明
CHECKOUT	支付收银台

证件类型枚举

值	说明
DNI	阿根廷国民身份证

请求示例

json

{
  "merchantOrderId": "ORDER46791673",
  "amount": 300,
  "currency": "ARS",
  "expireSeconds": 3600,
  "payinMethod": "CHECKOUT"
}

响应格式

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

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

响应参数（data 字段）

参数名	类型	说明
orderId	string	平台订单号
merchantOrderId	string	商户订单号
amount	BigDecimal	订单金额
fee	BigDecimal	交易手续费
payDeskUrl	string	收银台地址
orderStatus	string	订单状态
vaNumber	string	收款cvu账号,请求参数needSecondaryConfirmation为false时返回
vaName	string	收款cvu户名,请求参数needSecondaryConfirmation为false时返回
resultCode	string	错误码（错误时有值）
resultDesc	string	错误结果描述（错误时有值）

订单状态枚举

值	说明
PENDING	支付中
FAILED	失败

响应示例

成功响应

json

{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "orderId": "PAYIN48973464",
    "merchantOrderId": "ORDER46791673",
    "amount": 30000,
    "fee": 300.00,
    "payDeskUrl": "https://example.com/?orderNo=PAYIN48973464",
    "resultCode": null,
    "resultDesc": null,
    "orderStatus": "PENDING"
  }
}

失败响应

json

{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "orderId": "PAYIN48973464",
    "merchantOrderId": "ORDER46791673",
    "amount": 1,
    "fee": null,
    "payDeskUrl": null,
    "resultCode": "1000",
    "resultDesc": "Unknown error",
    "orderStatus": "FAILED"
  }
}

错误码说明

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

业务规则

订单号唯一性：同一商户下的商户订单号必须唯一
金额限制：单笔订单金额按商户风控配置校验
过期时间：支付信息页在 expireSeconds 后过期，默认 3600 秒
异步通知：订单状态变更会通过代收回调接口通知商户（商户需配置通知 URL）
风控检查：系统会对订单进行风控检查，失败会返回错误

注意事项

请求头：必须在请求头中传递所有必需的请求头（Content-Type、MerchantId、Timestamp、Nonce、Signature），详见 API签名规范
签名验证：所有请求必须包含正确的签名
异步通知：订单状态变更会通过异步通知接口通知商户
幂等性：相同商户订单号的重复请求会返回相同结果，不会创建重复订单
超时处理：建议设置合理的请求超时时间
日志记录：建议记录所有请求和响应日志

代收接口（Payin） ​

概述 ​

接口信息 ​

请求头 ​

请求参数 ​

支付方式枚举 ​

证件类型枚举 ​

请求示例 ​

响应格式 ​

响应参数（data 字段） ​

订单状态枚举 ​

响应示例 ​

成功响应 ​

失败响应 ​

错误码说明 ​

业务规则 ​

注意事项 ​

代收接口（Payin）

概述

接口信息

请求头

请求参数

支付方式枚举

证件类型枚举

请求示例

响应格式

响应参数（data 字段）

订单状态枚举

响应示例

成功响应

失败响应

错误码说明

业务规则

注意事项