Cobrar pagos locales con cuentas virtuales

​

Cómo funciona

​

Una cuenta o una por pagador

​

Antes de empezar

• Acceso a la API. Una clave de API, la IP de tu servidor en la lista blanca y un token de negocio en el header X-BH-TOKEN. Consulta Autenticación.
• Un comercio verificado. Consulta Crear un comercio.
• Una cuenta de moneda activa para la moneda y el canal en los que quieres cobrar (status 2 en Listar cuentas de comercio). Consulta Activar la cuenta de un comercio.
• Un endpoint de FUNDING_WEBHOOK registrado y que devuelva la confirmación requerida. Consulta Webhooks y Configuración de webhooks.

​

Canales que admiten cuentas virtuales

​

Paso a paso

curl -X POST https://api.velafi.com/v2/merchant/virtual/accounts \
  -H "X-BH-TOKEN: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": 100001,
    "fiat": "MXN",
    "paymentId": 105,
    "alias": "CUST0001"
  }'

{ "code": 200, "msg": "SUCCESS", "data": { "fiat": "MXN", "status": 1 } }

curl -G https://api.velafi.com/v2/merchant/virtual/addfunds \
  -H "X-BH-TOKEN: YOUR_TOKEN" \
  --data-urlencode "merchantId=100001" \
  --data-urlencode "fiat=MXN" \
  --data-urlencode "paymentId=105" \
  --data-urlencode "depositAlias=CUST0001"

curl -G https://api.velafi.com/v2/merchant/accounts \
  -H "X-BH-TOKEN: YOUR_TOKEN" \
  --data-urlencode "merchantId=100001" \
  --data-urlencode "fiat=MXN"

​

Webhooks que debes manejar

{
  "webhookId": "ebab8a9663704e7cbbebe672c7c67912",
  "eventType": "FUNDING_WEBHOOK",
  "txId": "1123123123",
  "merchantId": "100001",
  "fiat": "MXN",
  "totalAmount": "1000",
  "amount": "1000",
  "fee": "0",
  "paymentId": "105",
  "type": "DEPOSIT",
  "status": "2",
  "depositAlias": "CUST0001",
  "payerName": "Example Payer",
  "payerAccount": "000000000000000002",
  "bankWebhookInfo": "{...}",
  "completedTime": "1737452344000",
  "createTime": "1737452292000",
  "updateTime": "1737452344000",
  "timestamp": "1737452344512"
}

​

Maneja las fallas

• Eventos duplicados o fuera de orden. El mismo evento puede llegar más de una vez, y un evento cuyo status cambió antes de la entrega se descarta. Haz que tu handler sea idempotente sobre eventType + txId + status, y lee el registro con Listar registros de fondeo cuando necesites su estado más reciente.
• Webhooks perdidos. Si tu endpoint estaba caído o respondió de forma incorrecta, no se reenvía nada. Ejecuta la conciliación de abajo de forma programada para que no se pierda ningún depósito.
• Depósito sin depositAlias. Los pagos a los datos de la cuenta principal del comercio, o los rieles que no reportan el alias, no tienen una cuenta virtual con la cual relacionarse. Retenlos para revisión manual usando los campos del pagador y bankWebhookInfo.
• Falla la creación de la cuenta virtual. status 3 significa que el canal rechazó la cuenta. -5079 significa que la cuenta no está habilitada para esa moneda y ese canal, y -5071 significa que la cuenta de moneda del comercio en ese canal no está activa. Revisa la cuenta del comercio antes de reintentar.
• Alias de COP rechazado. Para 68 y 69, el alias debe tener de 6 a 21 letras mayúsculas o dígitos.

​

Concilia

• GET /v2/merchant/funding/records con type=DEPOSIT, un fiat y una ventana startTime/endTime (la ventana se aplica a la hora de finalización). Compara cada registro con status 2 contra los webhooks que guardaste y procesa los que te hayan faltado. En los depósitos, webhookInfo contiene los mismos detalles del proveedor que bankWebhookInfo, incluido depositAlias.
• GET /v2/merchant/fiat/flows para el historial del saldo línea por línea: cada línea tiene el cambio (changed), el saldo acumulado (total) y el txId relacionado. Úsalo para comprobar que el saldo en Listar cuentas de comercio es igual a la suma de tus movimientos.

​

Prueba en el sandbox

• Los webhooks no se disparan en el sandbox. Prueba tu handler enviándole tú mismo payloads de ejemplo, y revisa el resultado de cada depósito simulado con Listar registros de fondeo.
• El simulador solo produce depósitos exitosos. No puede producir un depósito fallido o devuelto.

​

Lista de verificación para salir a producción

• El endpoint de FUNDING_WEBHOOK verifica la firma y devuelve HTTP 200 con {"callbackStatus":"SUCCESS"} rápidamente, muy por debajo del timeout de 60 segundos.
• El handler es idempotente sobre eventType + txId + status e ignora los eventos que ya procesó.
• Cada pagador tiene su propia cuenta virtual, y el alias corresponde a un solo cliente en tu sistema.
• Tu libro contable lleva los saldos por pagador; no esperas que VelaFi mantenga un saldo por cuenta virtual.
• Los depósitos sin depositAlias van a una cola de revisión.
• Un proceso programado compara los registros de fondeo (type=DEPOSIT) con los webhooks guardados y procesa los faltantes.
• Los códigos QR y los links de pago se obtienen de nuevo antes de mostrarse.