> ## 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.

# Evento de fondeo

> Referencia del payload FUNDING_WEBHOOK que VelaFi envía por actividad fiat en la cuenta Pending Fund de un comercio, como un depósito fiat, un retiro fiat o un reembolso.

VelaFi envía un evento `FUNDING_WEBHOOK` a tu endpoint registrado cuando un registro de fondeo de tipo `DEPOSIT`, `WITHDRAW`, `BUY_CRYPTO`, `TRANSFER_IN` o `TRANSFER_OUT` llega al estado `2` (completado), `3` (cancelado) o `4` (reembolsado). Cada evento contiene los detalles completos de la transacción y, en el caso de los depósitos, información de identidad y bancaria del pagador. Los campos `payerName` y `payerAccount` se agregaron en la versión del 2025-05-08.

Este webhook solo cubre la actividad fiat en la cuenta Pending Fund del comercio. Los retiros de la billetera de cripto se envían mediante el [Evento de retiro de cripto](https://docs.velafi.com/es/api-reference/webhooks/crypto-withdraw-message-push.md) (`CRYPTO_WITHDRAW_WEBHOOK`).

## Headers de la solicitud

| Header | Descripción |
| - | - |
| `signature` | Firma RSA-SHA256 del cuerpo sin procesar de la solicitud, codificada en hexadecimal. Usa la `publicKey` de tu webhook para verificarla. Consulta [Configuración de webhooks](https://docs.velafi.com/es/api-reference/webhooks/webhook-setup.md). |
| `Content-Type` | `application/json` |

## Campos del payload

**webhookId** `string`

ID del endpoint de webhook que entregó este evento.

**eventType** `string`

Siempre `FUNDING_WEBHOOK` para este tipo de evento.

**txId** `string`

ID único de la transacción de este evento de fondeo.

**clientId** `string`

Identificador que proporcionaste para esta transacción. Se omite si no se estableció.

**userId** `string`

ID de tu cuenta (usuario) de VelaFi.

**merchantId** `string`

ID del comercio cuya cuenta Pending Fund se ve afectada.

**merchantName** `string`

Nombre visible del comercio.

**fiat** `string`

Moneda fiat de la transacción.

**totalAmount** `string`

Monto fiat total del registro. Negativo para `WITHDRAW`, `BUY_CRYPTO` y `TRANSFER_OUT`.

**amount** `string`

Monto fiat neto (sin comisiones).

**fee** `string`

Comisión cobrada por esta transacción.

**refundedAmount** `string`

Monto reembolsado, si aplica.

**paymentId** `string`

ID del canal de pago.

**userPaymentId** `string`

ID del método de pago del usuario.

**type** `string`

Tipo de transacción:

* `DEPOSIT`: fondos agregados a la cuenta Pending Fund
* `WITHDRAW`: un retiro fiat de la cuenta Pending Fund (no un retiro de la billetera de cripto)
* `BUY_CRYPTO`: fondos usados para una compra de cripto
* `TRANSFER_IN`: transferencia interna hacia la cuenta
* `TRANSFER_OUT`: transferencia interna desde la cuenta

**status** `string`

Estado de la transacción: `2` = completado, `3` = cancelado, `4` = reembolsado. Los registros pendientes no se envían.

**completedTime** `string`

Marca de tiempo Unix (milisegundos) en que se completó la transacción. Se omite si no se estableció.

**refundedTime** `string`

Marca de tiempo Unix (milisegundos) en que se emitió un reembolso. Se omite si el registro no se ha reembolsado.

**createTime** `string`

Marca de tiempo Unix (milisegundos) en que se creó el registro.

**updateTime** `string`

Marca de tiempo Unix (milisegundos) de la última actualización del registro.

**cardNo** `string`

Número de identificación de la entidad que envía los fondos.

**taxId** `string`

Identificación fiscal de la entidad que envía los fondos.

**payerName** `string`

Nombre completo de la entidad que envía los fondos. Agregado el 2025-05-08.

**payerAccount** `string`

Número de cuenta bancaria de la entidad que envía los fondos (p. ej., IBAN o CBU). Agregado el 2025-05-08.

**depositAlias** `string`

Alias de la cuenta virtual que recibió el depósito.

**bankWebhookInfo** `string`

Cadena JSON sin procesar del proveedor bancario subyacente, con campos específicos de cada proveedor. Consulta la sección Detalles de Bank Webhook Info más abajo.

**failCode** `string`

Código de falla legible por máquina. Solo se envía para pagos cancelados (`3`) que tienen un código de falla registrado.

**failReason** `string`

Descripción legible de la falla. Solo se envía cuando se envía `failCode` y hay una descripción registrada.

**extId** `string`

ID del registro relacionado, cuando existe. Para `BUY_CRYPTO`, es el ID de la orden de on-ramp.

**bankOrderId** `string`

Referencia de la transferencia bancaria subyacente en el proveedor de pagos, cuando está disponible.

**timestamp** `string`

Marca de tiempo Unix (milisegundos) en que se firmó este intento de entrega.

## Detalles de Bank Webhook Info

El campo `bankWebhookInfo` es una cadena JSON. Su estructura varía según el proveedor de pagos:

> [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."
> }
> ```

## Ejemplo de payload

```json Cuerpo del POST entrante 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"
}
```

## Respuesta requerida

Devuelve el siguiente cuerpo JSON con el estado HTTP `200`:

```json Tu respuesta theme={null}
{
  "callbackStatus": "SUCCESS"
}
```

> [!NOTE]
>
> Los campos `payerName` y `payerAccount` se introdujeron en la versión del 2025-05-08. Asegúrate de que tu handler maneje correctamente tanto su presencia como su ausencia, por compatibilidad con versiones anteriores.


## Related topics

- [Webhooks](https://docs.velafi.com/es/docs/guides/webhooks.md)
- [Listar registros de fondeo](https://docs.velafi.com/es/api-reference/merchant/retrieve-funding-records.md)
- [Configuración de webhooks](https://docs.velafi.com/es/api-reference/webhooks/webhook-setup.md)
- [Evento de orden](https://docs.velafi.com/es/api-reference/webhooks/fiat-crypto-order-message-push.md)
- [Evento de retiro cripto](https://docs.velafi.com/es/api-reference/webhooks/crypto-withdraw-message-push.md)


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