Funding Event

VelaFi sends a FUNDING_WEBHOOK event to your registered endpoint when a funding record of type DEPOSIT, WITHDRAW, BUY_CRYPTO, TRANSFER_IN, or TRANSFER_OUT reaches status 2 (completed), 3 (canceled), or 4 (refunded). Each event contains full transaction details and, for deposits, identity and banking information about the payer. The payerName and payerAccount fields were added in the 2025-05-08 release. This webhook covers only fiat activity on the merchant’s Pending Fund account. Crypto wallet withdrawals are sent through Crypto Withdrawal Event (CRYPTO_WITHDRAW_WEBHOOK) instead.

Request Headers

Header	Description
`signature`	RSA-SHA256 signature of the raw request body, hex-encoded. Use your webhook’s `publicKey` to verify. See Webhook Setup.
`Content-Type`	`application/json`

Payload Fields

string

The ID of the webhook endpoint that delivered this event.

string

Always FUNDING_WEBHOOK for this event type.

string

Unique transaction ID for this funding event.

string

Your client-supplied identifier for this transaction. Omitted if not set.

string

Your VelaFi account (user) ID.

string

ID of the merchant whose Pending Fund account is affected.

string

Display name of the merchant.

string

Fiat currency of the transaction.

string

Total fiat amount of the record. Negative for WITHDRAW, BUY_CRYPTO, and TRANSFER_OUT.

string

Net fiat amount (excluding fees).

string

Fee charged for this transaction.

string

Amount refunded, if applicable.

string

ID of the payment channel.

string

ID of the user’s payment method.

string

Transaction type:

DEPOSIT — funds added to the Pending Fund account
WITHDRAW — a fiat withdrawal from the Pending Fund account (not a crypto wallet withdrawal)
BUY_CRYPTO — funds used for a crypto purchase
TRANSFER_IN — internal transfer into the account
TRANSFER_OUT — internal transfer out of the account

string

Transaction status: 2 = completed, 3 = canceled, 4 = refunded. Pending records are not sent.

string

Unix timestamp (milliseconds) when the transaction completed. Omitted if not set.

string

Unix timestamp (milliseconds) when a refund was issued. Omitted if the record has not been refunded.

string

Unix timestamp (milliseconds) when the record was created.

string

Unix timestamp (milliseconds) when the record was last updated.

string

ID number of the entity sending funds.

string

Tax identifier of the entity sending funds.

string

Full name of the entity sending funds. Added 2025-05-08.

string

Bank account number of the entity sending funds (e.g., IBAN or CBU). Added 2025-05-08.

string

Alias of the virtual account that received the deposit.

string

Raw JSON string from the underlying banking provider with provider-specific fields. See the Bank Webhook Info section below.

string

Machine-readable failure code. Sent only for canceled (3) payouts that have a recorded failure code.

string

Human-readable failure description. Sent only when failCode is sent and a description is recorded.

string

ID of the related record, when there is one. For BUY_CRYPTO, this is the ID of the on-ramp order.

string

Reference of the underlying bank transfer at the payment provider, when available.

string

Unix timestamp (milliseconds) at which this delivery attempt was signed.

Bank Webhook Info Details

The bankWebhookInfo field is a JSON string. Its structure varies by payment provider:

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

Example Payload

Incoming POST body

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

Required Response

Return the following JSON body with HTTP status 200:

Your response

{
  "callbackStatus": "SUCCESS"
}

The payerName and payerAccount fields were introduced in the 2025-05-08 release. Ensure your handler gracefully handles both their presence and absence for backwards compatibility.

Overview

Account

Configuration

Merchants

Crypto Wallet

Beneficiaries

Quotes

Orders

Webhooks

Request Headers

Payload Fields

Bank Webhook Info Details

Example Payload

Required Response

​Request Headers

​Payload Fields

​Bank Webhook Info Details

​Example Payload

​Required Response

Request Headers

Payload Fields

Bank Webhook Info Details

Example Payload

Required Response