Tema
Lo que espera a una persona
La parte que casi ninguna documentación de API incluye, y la que decide si tus usuarios confían en tus pantallas.
Nada en esta API mueve dinero por su cuenta
Todo cambio y todo retiro es una solicitud que aprueba una persona en Vectrakpital. No hay un umbral por debajo del cual sea automático. Es una decisión de negocio, no una limitación pendiente de levantar, y construir como si fuera temporal produce una interfaz que miente.
Los cuatro momentos de un depósito
- Lo declaras. Recibes el monto exacto a enviar y una dirección.
- Lo envías, exacto.
- Alguien registra la llegada. Hoy no es automático: ningún proceso vigila el mercado. Entre que tu transferencia se confirma en cadena y el depósito aparece en
GET /api/v1/deposits, hay una persona. - Se atribuye. Esta parte sí es automática — la cola rara del monto casa con tu declaración y acredita a tu organización sin que nadie elija.
Así que consulta periódicamente el depósito, no esperes un webhook, y no le digas a tu usuario que llegó hasta que esté en la lista.
Si el monto que enviaste no coincide con la declaración no se rompe nada: el dinero espera a que lo atribuyan a mano. Simplemente deja de ser minutos y pasa a ser horas.
Los dos momentos de un retiro
Es el que más sorprende a quien integra.
venue_settled significa que el dinero salió de la plataforma. paid_out significa que llegó a la cuenta. No son el mismo evento, y entre uno y otro puede haber una noche: un pago cotizado a las cinco de la tarde suele llegar a la mañana siguiente.
Las expectativas de tus usuarios las fija lo que diga tu pantalla. Si dice completado cuando la plataforma dijo el dinero salió, has prometido algo que no puedes ver.
El estado que deberías pintar como «listo» es paid_out
Todo lo anterior es «en curso», y decirlo no cuesta nada.
Tres formas de sacar el dinero, y una cuesta más
Un retiro va a un destino registrado, y hay tres clases:
| Clase | A dónde llega | Qué se descuenta |
|---|---|---|
bank | A una cuenta bancaria tuya | La comisión del mercado y la de la plataforma |
wallet | A una dirección tuya, en la red que elijas | Lo mismo |
cash | En mano, en Bogotá, Medellín o Cali | Lo mismo más el cargo de la entrega |
Un pago en efectivo cuesta más porque alguien tiene que llevar los billetes, y eso se cobra. Verás una sola cifra de coste, no un desglose: es el total que sale de tu monto, y es lo que necesitas para saber qué llega.
Un retiro en efectivo puede repartirse
POST /api/v1/withdrawals recibe siempre una lista de partes, incluso para el caso corriente de un destino. Sólo en efectivo puede tener más de una, hasta tres:
json
{
"legs": [
{ "destinationId": "…bogota", "amountMinor": "2000000000000000000000000" },
{ "destinationId": "…medellin", "amountMinor": "1000000000000000000000000" }
]
}Eso es un retiro con dos entregas, no dos retiros. La diferencia importa para tus pantallas: hay una sola aprobación y un solo coste, y el retiro no está pagado hasta que se entregue la última parte. Cada parte lleva su propio momento de entrega, así que una puede estar entregada y la otra no.
El activo y su escala no van en la petición: se toman del destino, que ya declara por qué activo puede salir dinero.
Por qué un destino no se puede usar de inmediato
Un destino recién registrado es inutilizable hasta que pasen dos cosas: transcurre un período de enfriamiento, y alguien en Vectrakpital responde por él.
El enfriamiento es la única defensa que funciona contra una sesión que no es realmente tuya. Quien entre puede añadir su propia cuenta, y nada más en el flujo puede distinguir eso de que lo pidas tú.
Lo segundo depende de la clase de destino. Para una cuenta o una dirección es registrarla en la lista blanca del mercado. Para un punto en efectivo es una llamada: alguien se comunica con ustedes para confirmar el lugar y quiénes van a recoger, porque nada automático puede saber si es seguro entregar billetes en una dirección. Mientras eso no pase, el destino vuelve con awaitingReview en true.
Para tu integración esto significa una cosa: registra los destinos mucho antes de necesitarlos. Un flujo que registra una cuenta y retira hacia ella en la misma ejecución va a fallar, siempre, por diseño. Lee usable en el destino y construye alrededor de eso — y no lo deduzcas de usableInSeconds: 0, que sólo dice que el enfriamiento terminó.
Un punto de recogida tiene reglas que no son validaciones
Al registrar un cash hay tres límites, y ninguno es una restricción técnica que vaya a ceder:
- Tres ciudades, y no es una lista que vaya a crecer con una configuración: son las únicas donde opera quien entrega.
- Tres puntos por organización, contados al registrar.
- De uno a cinco autorizados, con nombre, cédula y teléfono. Esa lista es todo el control que ocurre en la puerta, así que al recibir hay que ser una de esas personas y llevar el documento.
De qué depende «el precio»
La tasa que te cotizan es la del mercado, menos lo que cuesta ejecutar, menos el margen de Vectrakpital. Se mueve durante el día, y en unos corredores más que en otros.
Si una cotización vuelve rechazada con quotes.quote_below_executable_rate, el precio ofrecido quedaría por debajo del coste de ejecutarla. Es la plataforma negándose a entregarte una pérdida. Se resuelve solo cuando el mercado se mueve.
Una pantalla de estado que envejezca bien
- Consulta con un horario. Aquí nada cambia segundo a segundo, porque hay una persona en el circuito.
- Muestra el estado de la plataforma, traducido una vez, con tus palabras — no un enum crudo, y no un resumen optimista.
- Distingue solicitado de aprobado de hecho. Juntarlos es el atajo que genera tickets de soporte.
- Cuando un paso espera a una persona, dilo. «En revisión» es información; un spinner no.