资金记录事件

当类型为 DEPOSIT、WITHDRAW、BUY_CRYPTO、TRANSFER_IN 或 TRANSFER_OUT 的资金记录达到状态 2（已完成）、3（已取消）或 4（已退款）时，VelaFi 会向您注册的端点发送 FUNDING_WEBHOOK 事件。每个事件都包含完整的交易详情；对于充值，还包含付款方的身份和银行信息。payerName 和 payerAccount 字段在 2025-05-08 版本中新增。此 Webhook 仅涵盖商户待处理资金账户上的法币活动。加密货币钱包提现则通过加密货币提现事件（CRYPTO_WITHDRAW_WEBHOOK）推送。

请求头

请求头	说明
`signature`	对原始请求体的 RSA-SHA256 签名，采用十六进制编码。请使用您 Webhook 的 `publicKey` 进行验证。请参阅 Webhook 设置。
`Content-Type`	`application/json`

推送字段

string

投递此事件的 Webhook 端点 ID。

string

对于此事件类型，始终为 FUNDING_WEBHOOK。

string

此资金事件的唯一交易 ID。

string

您为此交易提供的客户端标识符。未设置时不返回。

string

您的 VelaFi 账户（用户）ID。

string

受影响的待处理资金账户所属商户的 ID。

string

商户的显示名称。

string

交易的法币币种。

string

该记录的法币总金额。对于 WITHDRAW、BUY_CRYPTO 和 TRANSFER_OUT 为负数。

string

法币净额（不含手续费）。

string

此交易收取的手续费。

string

已退款金额（如适用）。

string

支付渠道 ID。

string

用户支付方式 ID。

string

交易类型：

DEPOSIT — 资金存入待处理资金账户
WITHDRAW — 从待处理资金账户提取法币（不是加密货币钱包提现）
BUY_CRYPTO — 资金用于购买加密货币
TRANSFER_IN — 内部转入该账户
TRANSFER_OUT — 从该账户内部转出

string

交易状态：2 = 已完成，3 = 已取消，4 = 已退款。处理中的记录不会推送。

string

交易完成时的 Unix 时间戳（毫秒）。未设置时不返回。

string

发起退款时的 Unix 时间戳（毫秒）。如果该记录未退款则不返回。

string

记录创建时的 Unix 时间戳（毫秒）。

string

记录最后更新时的 Unix 时间戳（毫秒）。

string

汇款方的证件号码。

string

汇款方的税务识别号。

string

汇款方的全名。2025-05-08 新增。

string

汇款方的银行账号（例如 IBAN 或 CBU）。2025-05-08 新增。

string

收到该笔充值的虚拟账户别名。

string

来自底层银行服务商的原始 JSON 字符串，包含服务商特定字段。请参阅下方的银行 Webhook 信息部分。

string

机器可读的失败代码。仅针对记录了失败代码的已取消（3）付款发送。

string

可读的失败描述。仅在发送了 failCode 且记录了描述时发送。

string

关联记录的 ID（如有）。对于 BUY_CRYPTO，此为入金订单的 ID。

string

支付服务商处底层银行转账的参考号（如可用）。

string

本次投递尝试签名时的 Unix 时间戳（毫秒）。

银行 Webhook 信息详情

bankWebhookInfo 字段是一个 JSON 字符串。其结构因支付服务商而异：

MXN (SPEI)

{
  "depositAlias": "alias",
  "sender_account_number": "684180168000000000",
  "description": "Payment",
  "sender_name": "CENTAURE S.A. DE C.V.",
  "tracking_id": "DO1755784299100",
  "sender_id": "CCN2203099WA"
}

ARS (CVU/CBU)

{
  "depositAlias": "alias",
  "id": "98569107",
  "idCoelsa": "86VRPQ2GVJEQE70M2GLY0M",
  "titularOriginante": "Alejandro Samuel Alvarez",
  "cuitCvu": "20000000003",
  "cuitOriginante": "20000000003",
  "cuentaOriginante": "0000000000000000000004",
  "titularCvu": "ALVAREZ ALEJANDRO SAMUEL42911|61",
  "cuitPsp": "30000000002",
  "cvu": "0000000000000000000001",
  "descripcion": "",
  "fechaNegocio": "2025-08-28T00:00:00Z"
}

COP (PSE/ACH)

{
  "description": "Payment In",
  "depositAlias": "alias",
  "sender_name": "SUPEFINE SAS",
  "sender_id": "9017343700",
  "sender_bank_code": "1013",
  "r2p_method": "pse",
  "tracking_key": "1714319140",
  "external_id": "612600442085490688",
  "type": "breb_key",
  "key_type": "phone",
  "key_value": "3000000000"
}

BRL (Pix)

{
  "depositAlias": "alias",
  "payer_tax_id": "00000000000003",
  "payer_name": "Tom",
  "payer_bank_account": "570302",
  "payer_bank_name": "BCO DO BRASIL S.A."
}

推送示例

Incoming POST body

{
  "webhookId": "ebab8a9663704e7cbbebe672c7c67912",
  "eventType": "FUNDING_WEBHOOK",
  "txId": "1123123123",
  "clientId": "client123456",
  "userId": "455472",
  "merchantId": "3",
  "merchantName": "Arturo Tellez",
  "fiat": "ARS",
  "totalAmount": "22",
  "amount": "20",
  "fee": "2",
  "refundedAmount": "0",
  "paymentId": "63",
  "userPaymentId": "91",
  "type": "DEPOSIT",
  "status": "2",
  "completedTime": "1737452344000",
  "createTime": "1737452292000",
  "updateTime": "1737452344000",
  "cardNo": "3067212321",
  "taxId": "5269328432",
  "payerName": "Matias Alva",
  "payerAccount": "CH8508843132556121020",
  "depositAlias": "alias",
  "bankWebhookInfo": "{}",
  "timestamp": "1737452344512"
}

必需的响应

请返回以下 JSON 响应体，HTTP 状态码为 200：

Your response

{
  "callbackStatus": "SUCCESS"
}

payerName 和 payerAccount 字段在 2025-05-08 版本中引入。为保证向后兼容，请确保您的处理程序能够妥善处理这两个字段存在或缺失的情况。

概览

账户

配置

商户

加密钱包

收款人

报价

订单

Webhooks

资金记录事件

请求头

推送字段

银行 Webhook 信息详情

推送示例

必需的响应

​请求头

​推送字段

​银行 Webhook 信息详情

​推送示例

​必需的响应

请求头

推送字段

银行 Webhook 信息详情

推送示例

必需的响应