Dispersar moneda local desde el saldo

​

Cómo funciona

​

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 con una cuenta de moneda activa en un canal que admita pagos (consulta abajo). Consulta Activar la cuenta de un comercio.
• Saldo en esa cuenta de moneda, proveniente de depósitos en el mismo canal. Consulta Cobrar pagos locales con cuentas virtuales.
• Un endpoint de FUNDING_WEBHOOK registrado y que devuelva la confirmación requerida. Consulta Configuración de webhooks.

​

Canales que admiten pagos desde el saldo

1. Mismo canal. El pago sale por el canal de la cuenta de moneda que tiene el saldo. Solo el saldo que entró por ese canal (o por VelaFi Pending Fund) se puede pagar por él.
2. Misma cuenta de moneda del comercio. El beneficiario debe estar guardado bajo el mismo comercio, para la misma moneda y el mismo canal que esa cuenta. Un beneficiario guardado bajo otro comercio, o para otro canal (por ejemplo, un beneficiario de Tesored contra un saldo de Finco Pay), se rechaza.
3. Monto más comisión. El saldo debe cubrir amount más la comisión del pago.

​

Paso a paso

curl -X POST https://api.velafi.com/v2/payments \
  -H "X-BH-TOKEN: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": 100001,
    "paymentId": 105,
    "country": "Mexico",
    "fiat": "MXN",
    "fieldJson": {
      "Account Type": "clabe",
      "Account Number": "000000000000000001",
      "Beneficiary Name": "Example Beneficiary",
      "Bank Code": ""
    }
  }'

curl -X POST https://api.velafi.com/v2/merchant/claimfunds \
  -H "X-BH-TOKEN: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": 100001,
    "clientId": "payout-0001",
    "fiat": "MXN",
    "amount": 1000,
    "userPaymentId": 456
  }'

{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "txId": 1123123123,
    "merchantId": 100001,
    "clientId": "payout-0001",
    "fiat": "MXN",
    "totalAmount": 1010,
    "amount": 1000,
    "fee": 10,
    "userPaymentId": 456,
    "createTime": "1737452292000"
  }
}

​

Estados del pago

​

Webhooks que debes manejar

{
  "eventType": "FUNDING_WEBHOOK",
  "txId": "1123123123",
  "clientId": "payout-0001",
  "merchantId": "100001",
  "fiat": "MXN",
  "totalAmount": "-1010",
  "amount": "1000",
  "fee": "10",
  "userPaymentId": "456",
  "type": "WITHDRAW",
  "status": "3",
  "failCode": "...",
  "failReason": "...",
  "bankOrderId": "...",
  "createTime": "1737452292000",
  "updateTime": "1737452350000",
  "timestamp": "1737452350512"
}

• Relaciona el evento con tu pago por clientId o txId.
• Haz que el handler sea idempotente sobre eventType + txId + status. El mismo evento puede llegar más de una vez, y un pago puede pasar de 2 a 4 más tarde, así que maneja un reembolso después de una finalización.
• failCode y failReason se envían solo para pagos cancelados que tienen un motivo registrado. Muchas fallas llegan sin motivo; no dependas de ellos para decidir qué hacer.
• bankOrderId es la referencia de la transferencia en el proveedor de pagos, cuando está disponible. Guárdala para las solicitudes de soporte.
• Devuelve HTTP 200 con {"callbackStatus":"SUCCESS"} rápidamente. VelaFi espera como máximo 60 segundos; un timeout o cualquier otra respuesta cuenta como entrega fallida. Consulta Entrega y reintentos.

​

Maneja las fallas

​

Errores al crear el pago

​

Timeouts y reintentos

1. Si la llamada excede el tiempo de espera o devuelve un error de red, no crees un nuevo clientId. Busca el pago con GET /v2/merchant/funding/records?clientId=....
2. Si existe un registro, el pago se creó: sigue su estado.
3. Si no existe ninguno, envía la misma solicitud otra vez con el mismo clientId. Si la primera solicitud sí se procesó, recibes -1174 en lugar de un segundo pago.

​

Pagos fallidos

1. Revisa los datos del beneficiario (número de cuenta, tipo de llave, nombre del titular) y corrige o vuelve a guardar el beneficiario si es necesario.
2. Crea un nuevo pago con un clientId nuevo, por ejemplo payout-0001-r1, y vincúlalo al original en tu sistema.

​

Mueve saldo entre comercios

curl -X POST https://api.velafi.com/v2/merchant/transfer \
  -H "X-BH-TOKEN: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "transfer-0001",
    "fromMerchantId": 100001,
    "toMerchantId": 100002,
    "fiat": "MXN",
    "paymentId": 105,
    "fiatAmount": 1000
  }'

​

Concilia

• GET /v2/merchant/funding/records es la fuente de verdad de cada pago y transferencia. Filtra por type=WITHDRAW (o TRANSFER_OUT, TRANSFER_IN), fiat y una ventana de tiempo, y verifica que cada pago que creaste tenga un estado final (2, 3 o 4). Investiga los que sigan pendientes.
• GET /v2/merchant/fiat/flows muestra cada movimiento del saldo: WITHDRAW cuando se crea el pago, WITHDRAW_ROLLBACK cuando un pago cancelado o reembolsado se abona de vuelta, y TRANSFER_OUT / TRANSFER_IN para las transferencias. El total de cada línea es el saldo acumulado después de ese movimiento.

​

Prueba en el sandbox

• Los webhooks no se disparan en el sandbox. Da seguimiento a cada pago con Listar registros de fondeo, y prueba tu handler de webhooks con payloads de ejemplo, incluidos retiros cancelados (3) y reembolsados (4).
• Los simuladores no pueden producir un depósito fallido o devuelto.

​

Lista de verificación para salir a producción

• Cada pago y cada transferencia envía un clientId único que guardas antes de hacer la llamada.
• Ante un timeout, buscas el clientId antes de reintentar y reenvías con el mismo clientId.
• Un pago fallido se reintenta solo con un clientId nuevo, después de revisar los datos del beneficiario.
• Los beneficiarios se guardan bajo el mismo comercio y el mismo canal que el saldo, y solo se usan beneficiarios con status 1.
• La revisión del saldo incluye la comisión.
• El handler de FUNDING_WEBHOOK maneja WITHDRAW con status 2, 3 y 4, y funciona cuando falta failReason.
• Un proceso programado marca los pagos que siguen pendientes después de tu tiempo de liquidación esperado.