Evento de fondeo

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 (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.
`Content-Type`	`application/json`

Campos del payload

string

ID del endpoint de webhook que entregó este evento.

string

Siempre FUNDING_WEBHOOK para este tipo de evento.

string

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

string

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

string

ID de tu cuenta (usuario) de VelaFi.

string

ID del comercio cuya cuenta Pending Fund se ve afectada.

string

Nombre visible del comercio.

string

Moneda fiat de la transacción.

string

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

string

Monto fiat neto (sin comisiones).

string

Comisión cobrada por esta transacción.

string

Monto reembolsado, si aplica.

string

ID del canal de pago.

string

ID del método de pago del usuario.

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

string

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

string

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

string

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

string

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

string

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

string

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

string

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

string

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

string

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

string

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

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.

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.

string

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

string

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

string

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

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:

MXN (SPEI)

{
  "depositAlias": "alias",
  "sender_account_number": "000000000000000002",
  "description": "Payment",
  "sender_name": "EMPRESA EJEMPLO S.A. DE C.V.",
  "tracking_id": "TRACKING0000000001",
  "sender_id": "XAXX010101000"
}

ARS (CVU/CBU)

{
  "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"
}

COP (PSE/ACH)

{
  "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"
}

BRL (Pix)

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

Ejemplo de payload

Cuerpo del POST entrante

{
  "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:

Tu respuesta

{
  "callbackStatus": "SUCCESS"
}

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.

Descripción general

Cuenta

Configuración

Comercios

Billetera cripto

Beneficiarios

Cotizaciones

Órdenes

Webhooks

Evento de fondeo

Headers de la solicitud

Campos del payload

Detalles de Bank Webhook Info

Ejemplo de payload

Respuesta requerida

​Headers de la solicitud

​Campos del payload

​Detalles de Bank Webhook Info

​Ejemplo de payload

​Respuesta requerida

Headers de la solicitud

Campos del payload

Detalles de Bank Webhook Info

Ejemplo de payload

Respuesta requerida