独立CVU入金回调接口

概述

独立 CVU 模式下，商户拥有专属绑定的收款 CVU。终端用户直接向该 CVU 转账后，Veloraya 收到款项后，会自动生成代收订单，随后通过本接口向商户推送通知（含付款人 CUIT、银行流水号等），商户凭以给用户加值。

与订单模式代收回调的区别：

对比项	订单模式代收回调	独立CVU入金回调
是否需要先下单	是，商户先调创建代收订单接口	否，平台自动建单
回调地址	在商户后台配置代收回调地址	在商户后台配置 VA 入金回调地址
订单号来源	商户传入的 `merchantOrderId`	平台自动生成，`merchantOrderId` = 平台订单号
核心匹配依据	证件号 + 金额 + 过期时间	由商户自行操作
付款人证件	DNI（去前后缀）	完整 CUIT（11 位）

两种模式互斥、不可共存：生产环境每个商户只能使用一种代收模式，商户需在开通前确认使用哪种模式；如需同时使用两种方式，请联系商务开通两个商户。

回调地址配置

独立 CVU 入金回调使用独立的回调地址，与代收回调地址互不影响：

由运营在商户后台接入配置页面填写（与代收回调地址同一页面、同一保存方式）；
请确保上线前已完成配置。

回调机制

回调触发条件

平台收到 CVU 入金款项且命中商户专属绑定的 CVU；
自动建单并完成入账/结算后触发推送。

回调重试机制

项目	说明
重试次数	最多重试 11 次（包含首次推送）
重试间隔	30 秒（前 6 次）
重试间隔	3 分钟（后 5 次）
超时时间	30 秒
重试条件	HTTP 状态码非 200、业务响应码非 10000、或网络异常
成功判定	HTTP 状态码 200 且业务响应 `{"code": 10000, "message": "Success"}`

回调请求

请求方式

方法：POST
Content-Type：application/json
字符编码：UTF-8

请求头

参数名	类型	必选	说明
Content-Type	string	Y	application/json
Timestamp	string	Y	时间戳（毫秒）
Nonce	string	Y	随机字符串（UUID，去除横线）
Signature	string	Y	签名，使用 Veloraya 私钥生成，用于验证回调的合法性

回调参数（请求体）

参数名	类型	必选	说明
merchantId	string	Y	商户 ID
orderId	string	Y	平台订单号（自动生成）
merchantOrderId	string	Y	商户订单号，独立CVU模式下等于平台订单号
orderStatus	string	Y	订单状态，见订单状态枚举
amount	BigDecimal	Y	订单金额
payAmount	BigDecimal	Y	实际支付金额
currency	string	Y	货币代码，固定 ARS
fee	BigDecimal	Y	手续费（按 VA_DIRECT 产品费率计算）
createDatetime	string	Y	订单创建时间（阿根廷时区 UTC-3），格式：yyyy-MM-dd HH:mm:ss
completionDatetime	string	N	订单完成时间（阿根廷时区 UTC-3），格式：yyyy-MM-dd HH:mm:ss
notifyType	string	Y	通知类型，固定 `VA_DIRECT`，用于区分订单模式回调
payerCuit	string	Y	付款人完整 CUIT（11 位），商户给用户加值的核心依据
payerAccount	string	N	付款人转出账号，手动补单场景可能为空
receiveAccount	string	N	收款账号（即绑定的 CVU），手动补单场景可能为空
bankTxnId	string	Y	Coelsa 银行流水号，用于银行侧交易追溯

订单状态枚举

值	说明
SUCCESS	成功

回调示例

入金成功回调（自动建单）

json

{
  "merchantId": "206092",
  "orderId": "AU2102293964635131904",
  "merchantOrderId": "AU2102293964635131904",
  "orderStatus": "SUCCESS",
  "amount": 100.00,
  "payAmount": 100.00,
  "currency": "ARS",
  "fee": 2.00,
  "createDatetime": "2026-09-22 04:08:34",
  "completionDatetime": "2026-09-22 04:08:36",
  "notifyType": "VA_DIRECT",
  "payerCuit": "20234567890",
  "payerAccount": "0000003100000000000001",
  "receiveAccount": "0000003100000000000099",
  "bankTxnId": "COELSA1234567890",
  "errorCode": null,
  "errorMsg": null
}

手动补单回调（payerAccount/receiveAccount 为空）

json

{
  "merchantId": "206092",
  "orderId": "AU2102293964635131904",
  "merchantOrderId": "AU2102293964635131904",
  "orderStatus": "SUCCESS",
  "amount": 100.00,
  "payAmount": 100.00,
  "currency": "ARS",
  "fee": 2.00,
  "createDatetime": "2026-09-22 04:08:34",
  "completionDatetime": "2026-09-22 04:08:36",
  "notifyType": "VA_DIRECT",
  "payerCuit": "20234567890",
  "payerAccount": null,
  "receiveAccount": null,
  "bankTxnId": "COELSA1234567890",
  "errorCode": null,
  "errorMsg": null
}

回调响应

成功响应

商户必须返回 HTTP 200 状态码，且业务响应码为 10000 表示接收成功：

json

{
  "code": 10000,
  "message": "Success"
}

失败响应

如果处理失败，可以返回相应的错误信息（系统会继续重试）：

json

{
  "code": 40001,
  "message": "处理失败"
}

注意

只有返回 {"code": 10000, "message": "Success"} 时，系统才会停止重试。其他任何响应（包括 HTTP 非 200 状态码）都会触发重试机制。

签名验证

验签步骤

提取签名：从请求头中获取 Signature 字段
构建签名内容：按照格式构建签名内容 timestamp={时间戳},nonce={随机数},body={请求体JSON字符串}
- 注意：签名内容不包含 merchantId，只包含 timestamp、nonce 和 body
使用 Veloraya 公钥验签：使用 Veloraya 提供的公钥验证签名
参考统一验签指引：推荐直接复用 API签名规范中的"回调验签指南"及附录 B 示例代码，实现统一的回调验签逻辑

密钥说明

Veloraya 公钥：由 Veloraya 提供，用于验证回调通知的签名
签名算法：SHA256withRSA
编码格式：UTF-8 编码 + Base64 编码

业务规则

免下单：商户无需调用创建代收订单接口，用户直接向专属 CVU 转账即可触发入金回调
专属 CVU 绑定：1 个 CVU 唯一归属 1 个商户，1 个商户可绑定多个 CVU；绑定后永久归属，不可换绑/停用
手续费：按商户 VA_DIRECT 代收产品费率公式计费（fixedFee + amount × rateFee/100，受 minFee 约束）
时间时区：createDatetime、completionDatetime 均为阿根廷本地时间（UTC-3，无夏令时）
用户加值依据：商户凭回调中的 payerCuit（付款人 CUIT）+ bankTxnId（银行流水号）关联自身用户并加值
模式互斥：独立 CVU 模式与订单模式互斥、不可共存，商户需在开通前确认使用哪种模式；如需同时使用两种方式，请联系商务开通两个商户

注意事项

回调地址配置：独立 CVU 入金回调地址 vaNotifyUrl 需在上线前在商户后台接入配置页面填写，与代收回调地址 payinNotifyUrl 相互独立
签名验证：必须验证回调签名的合法性，建议直接按照 API签名规范中的"回调验签指南"实现统一的回调验签逻辑
幂等性：实现幂等性处理避免重复处理，建议根据 orderId 进行去重；同一笔入金可能因重复推送或重试而产生多次回调
字段兼容：notifyType 为 VA_DIRECT 时表示本回调为独立 CVU 入金回调；订单模式代收回调不含 notifyType 字段，可据此区分两类回调
空字段处理：手动补单场景下 payerAccount、receiveAccount 可能为 null，商户应做空值兼容处理，此时可凭 payerCuit + bankTxnId 核对
响应格式：必须返回 {"code": 10000, "message": "Success"} 才能停止重试，其他响应都会触发重试
日志记录：记录所有回调处理日志，包括请求体、响应结果、处理时间等

独立CVU入金回调接口 ​

概述 ​

回调地址配置 ​

回调机制 ​

回调触发条件 ​

回调重试机制 ​

回调请求 ​

请求方式 ​

请求头 ​

回调参数（请求体） ​

订单状态枚举 ​

回调示例 ​

入金成功回调（自动建单） ​

手动补单回调（payerAccount/receiveAccount 为空） ​

回调响应 ​

成功响应 ​

失败响应 ​

签名验证 ​

验签步骤 ​

密钥说明 ​

业务规则 ​

注意事项 ​

独立CVU入金回调接口

概述

回调地址配置

回调机制

回调触发条件

回调重试机制

回调请求

请求方式

请求头

回调参数（请求体）

订单状态枚举

回调示例

入金成功回调（自动建单）

手动补单回调（payerAccount/receiveAccount 为空）

回调响应

成功响应

失败响应

签名验证

验签步骤

密钥说明

业务规则

注意事项