> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velafi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 资金记录事件

> 商户待处理资金 (Pending Fund) 账户发生法币活动（例如法币充值、法币提现或退款）时，VelaFi 发送的 FUNDING_WEBHOOK 推送内容参考。

当类型为 `DEPOSIT`、`WITHDRAW`、`BUY_CRYPTO`、`TRANSFER_IN` 或 `TRANSFER_OUT` 的资金记录达到状态 `2`（已完成）、`3`（已取消）或 `4`（已退款）时，VelaFi 会向您注册的端点发送 `FUNDING_WEBHOOK` 事件。每个事件都包含完整的交易详情；对于充值，还包含付款方的身份和银行信息。`payerName` 和 `payerAccount` 字段在 2025-05-08 版本中新增。

此 Webhook 仅涵盖商户待处理资金账户上的法币活动。加密货币钱包提现则通过[加密货币提现事件](https://docs.velafi.com/cn/api-reference/webhooks/crypto-withdraw-message-push.md)（`CRYPTO_WITHDRAW_WEBHOOK`）推送。

## 请求头

| 请求头 | 说明 |
| - | - |
| `signature` | 对原始请求体的 RSA-SHA256 签名，采用十六进制编码。请使用您 Webhook 的 `publicKey` 进行验证。请参阅 [Webhook 设置](https://docs.velafi.com/cn/api-reference/webhooks/webhook-setup.md)。 |
| `Content-Type` | `application/json` |

## 推送字段

**webhookId** `string`

投递此事件的 Webhook 端点 ID。

**eventType** `string`

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

**txId** `string`

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

**clientId** `string`

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

**userId** `string`

您的 VelaFi 账户（用户）ID。

**merchantId** `string`

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

**merchantName** `string`

商户的显示名称。

**fiat** `string`

交易的法币币种。

**totalAmount** `string`

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

**amount** `string`

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

**fee** `string`

此交易收取的手续费。

**refundedAmount** `string`

已退款金额（如适用）。

**paymentId** `string`

支付渠道 ID。

**userPaymentId** `string`

用户支付方式 ID。

**type** `string`

交易类型：

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

**status** `string`

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

**completedTime** `string`

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

**refundedTime** `string`

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

**createTime** `string`

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

**updateTime** `string`

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

**cardNo** `string`

汇款方的证件号码。

**taxId** `string`

汇款方的税务识别号。

**payerName** `string`

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

**payerAccount** `string`

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

**depositAlias** `string`

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

**bankWebhookInfo** `string`

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

**failCode** `string`

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

**failReason** `string`

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

**extId** `string`

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

**bankOrderId** `string`

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

**timestamp** `string`

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

## 银行 Webhook 信息详情

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

> [accordion] MXN (SPEI)
>
> ```json theme={null}
> {
>   "depositAlias": "alias",
>   "sender_account_number": "000000000000000002",
>   "description": "Payment",
>   "sender_name": "EMPRESA EJEMPLO S.A. DE C.V.",
>   "tracking_id": "TRACKING0000000001",
>   "sender_id": "XAXX010101000"
> }
> ```

> [accordion] ARS (CVU/CBU)
>
> ```json theme={null}
> {
>   "depositAlias": "alias",
>   "id": "10000001",
>   "idCoelsa": "COELSA0000000000000001",
>   "titularOriginante": "Juan Perez",
>   "cuitCvu": "20000000003",
>   "cuitOriginante": "20000000003",
>   "cuentaOriginante": "0000000000000000000004",
>   "titularCvu": "PEREZ JUAN",
>   "cuitPsp": "30000000002",
>   "cvu": "0000000000000000000001",
>   "descripcion": "",
>   "fechaNegocio": "2025-08-28T00:00:00Z"
> }
> ```

> [accordion] COP (PSE/ACH)
>
> ```json theme={null}
> {
>   "description": "Payment In",
>   "depositAlias": "alias",
>   "sender_name": "EMPRESA EJEMPLO SAS",
>   "sender_id": "900000000",
>   "sender_bank_code": "1013",
>   "r2p_method": "pse",
>   "tracking_key": "0000000001",
>   "external_id": "600000000000000001",
>   "type": "breb_key",
>   "key_type": "phone",
>   "key_value": "3000000000"
> }
> ```

> [accordion] BRL (Pix)
>
> ```json theme={null}
> {
>   "depositAlias": "alias",
>   "payer_tax_id": "00000000000003",
>   "payer_name": "Tom",
>   "payer_bank_account": "000001",
>   "payer_bank_name": "BCO DO BRASIL S.A."
> }
> ```

## 推送示例

```json Incoming POST body theme={null}
{
  "webhookId": "ebab8a9663704e7cbbebe672c7c67912",
  "eventType": "FUNDING_WEBHOOK",
  "txId": "1123123123",
  "clientId": "client123456",
  "userId": "455472",
  "merchantId": "3",
  "merchantName": "Example Merchant",
  "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": "0000000001",
  "taxId": "20000000001",
  "payerName": "Jane Doe",
  "payerAccount": "0000000000000000000005",
  "depositAlias": "alias",
  "bankWebhookInfo": "{}",
  "timestamp": "1737452344512"
}
```

## 必需的响应

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

```json Your response theme={null}
{
  "callbackStatus": "SUCCESS"
}
```

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


## Related topics

- [获取资金记录](https://docs.velafi.com/cn/api-reference/merchant/retrieve-funding-records.md)
- [更新日志](https://docs.velafi.com/cn/docs/changelog.md)
- [划转待处理资金](https://docs.velafi.com/cn/api-reference/merchant/transfer-pending-funds.md)
- [获取法币流水](https://docs.velafi.com/cn/api-reference/merchant/get-a-list-merchant-fiat-flow.md)
- [提取待处理资金](https://docs.velafi.com/cn/api-reference/merchant/claim-pending-fund.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.