Introducción y Arquitectura
Las Transferencias (Pay-Outs) permiten mover fondos desde tu saldo disponible en Vendis hacia cuentas bancarias externas u otras billeteras, de forma programática.
Dada la naturaleza crítica del movimiento de dinero saliente, la API de transferencias de Vendis está diseñada basándose en dos estándares: Idempotencia y Asincronía.
1. Idempotencia Obligatoria
En sistemas distribuidos, una falla de red puede dejar en duda si una petición de transferencia fue recibida o no por el servidor. Para evitar que el dinero se deduzca dos veces ante un reintento del cliente, Vendis exige el envío de una llave de idempotencia.
¿Cómo funciona?
Debes enviar el encabezado HTTP Idempotency-Key con un identificador único (preferentemente un UUID v4) en cada petición POST.
Si envías dos peticiones con exactamente el mismo Idempotency-Key y el mismo payload, Vendis procesará la transferencia solo la primera vez. En el segundo intento, interceptará la petición y devolverá la misma respuesta almacenada en caché del primer intento, sin afectar el saldo nuevamente.
POST /api/v2/transfers
X-API-KEY: <TU_API_KEY>
Idempotency-Key: e1a50a12-872f-4b08-8e6d-5a8b79c2356c
Content-Type: application/json
2. Flujo Asíncrono
Para el cliente integrador, realizar una transferencia consiste en un único paso: Hacer la petición POST.
Vendis responderá inmediatamente con un HTTP 201 Created y el estado de la transferencia como PENDING (Pendiente). Internamente, nuestros servidores se encargarán de orquestar toda la lógica de manera asíncrona.
Una vez que la entidad financiera finalice la operación (aprobando o rechazando la transacción), Vendis emitirá un evento mediante Webhooks notificándote del estado final.
Ciclo de Vida de una Transferencia
PENDING: Solicitud recibida. Los fondos se retienen de tu saldo disponible de manera precautoria.IN_TRANSIT: Vendis está negociando la transferencia con la red bancaria.COMPLETED(Estado Final): El dinero fue depositado exitosamente en el destino.ERROR(Estado Final): La transferencia fue rechazada (ej. cuenta bloqueada, error del banco). Los fondos retenidos son devueltos automáticamente a tu saldo disponible.