Introducción
Alibanca es una infraestructura de pagos (BaaS, Banking as a Service) para mover dinero por API con seguridad de grado bancario. En criollo: nos conectas una vez y, desde tu código, envías dinero a una persona en Venezuela — a su pago móvil o a su cuenta — sin montar tú un banco, sin integrar cada riel a mano y sin quedarte con la duda de si el dinero salió o no. Esta página es tu punto de partida: qué es Alibanca, cómo está organizada la API, cómo probarla sin arriesgar un centavo y en qué orden conviene aprenderla.
Si nunca has integrado una API de pagos, tranquilo: aquí vamos a ir paso a paso y sin dar nada por sentado. Cada término técnico lo definimos la primera vez que aparece. Al terminar de leer vas a entender el vocabulario del sistema, vas a haber hecho tu primera llamada de verdad (una que no necesita ni siquiera tu llave) y vas a tener un mapa claro de qué leer después.
¿Qué es Alibanca?
Alibanca es una capa de infraestructura que se sienta entre tu producto y los rieles de pago. Un riel es simplemente el "carril" por el que viaja el dinero hasta el destinatario: el pago móvil, la cámara de compensación entre bancos, etc. Normalmente, para mover dinero tendrías que integrarte con cada banco por separado, hablar el "idioma" de cada uno, y construir tú mismo toda la lógica de seguridad que garantiza que un pago no se duplique ni se pierda. Eso es meses de trabajo y un riesgo enorme.
Con Alibanca, en cambio, hablas un solo lenguaje — una API REST moderna — y nosotros nos encargamos de traducirlo a cada riel por debajo. Tú dices "envía 150,00 VES a este número de pago móvil"; nosotros lo ejecutamos, lo vigilamos y te devolvemos un resultado en el que puedes confiar. Piénsalo como el enchufe universal del dinero: un solo tomacorriente para muchas paredes distintas.
El problema que resuelve: mover dinero sin perderlo
Mover dinero es fácil cuando todo sale bien. El problema son los bordes: el banco no responde a tiempo, se cae la red justo después de que enviaste la orden, reintentas por las dudas y — sin querer — pagas dos veces. Ese es el miedo real de cualquiera que mueve dinero de terceros. Alibanca está diseñada, de raíz, para que eses casos borde no te cuesten dinero.
La pieza central es que un pago no tiene solo dos finales ("salió bien" / "salió mal"). Tiene tres, y el tercero es de primera clase:
completed es que el dinero se movió. failed es que no se movió — y eso está garantizado: no hubo débito, así que puedes reintentar con tranquilidad. Y unknown — el que casi ninguna API modela bien — significa "todavía no sabemos": el banco no respondió (un timeout, una caída) y estamos reconciliando para averiguar la verdad. La regla de oro es sencilla: sobre un pago en unknown nunca creas un pago nuevo; se resuelve solo, por conciliación de saldo. Reintentar sobre un unknown es exactamente cómo la gente termina pagando doble.
Además, por debajo Alibanca corre una conciliación (recon) continua: cuadra el saldo real del banco contra su propio ledger de doble partida (un libro contable donde cada movimiento tiene su contrapartida, como en contabilidad clásica). Eso le permite cazar anomalías — un débito sin dueño, un doble-débito idéntico, un crédito inesperado — antes de que tú te enteres. No profundizamos aquí; solo queremos que sepas que la red de seguridad existe y trabaja sola. Los detalles vienen en Estados de un pago →, Idempotencia → y Conciliación →.
Cómo está organizada la API
Alibanca es una API REST. Si vienes de otras APIs modernas (Stripe, por ejemplo), ya la conoces sin saberlo. REST quiere decir, en la práctica, cuatro cosas:
1. Recursos con URL propia. Cada "cosa" del sistema — un pago, un beneficiario, tu cuenta — es un recurso y vive en una dirección clara: /v2/payments son los pagos, /v2/beneficiaries son los beneficiarios, /v2/balance es tu saldo. Todo cuelga de /v2, que indica la versión de la API.
2. Cuerpos en JSON. Cuando envías datos (por ejemplo, para crear un pago), los mandas como JSON — el formato de texto estándar de la web, pares "clave: valor". Cuando te respondemos, también recibes JSON.
3. Verbos HTTP estándar. El "qué quieres hacer" lo dice el método HTTP, no la URL:
| Verbo | Significa | Ejemplo |
|---|---|---|
| GET | leer | Consultar sin cambiar nada. GET /v2/payments/:id lee el estado de un pago. |
| POST | crear | Crear un recurso nuevo. POST /v2/payments emite un pago. |
| PUT | reemplazar | Fijar una configuración completa. PUT /v2/webhook configura tu URL de webhook. |
| PATCH | editar | Cambiar parte de un recurso. PATCH /v2/beneficiaries/:id edita el alias. |
| DELETE | archivar | Retirar de uso (nunca borrado duro). DELETE /v2/beneficiaries/:id archiva. |
4. Códigos HTTP estándar. Cada respuesta trae un número que resume qué pasó a nivel de transporte: 2xx salió bien, 4xx hiciste algo mal (falta un campo, la firma no cuadra), 5xx el problema fue nuestro. Este número es tu primera pista; el detalle viene siempre en el cuerpo JSON.
El catálogo completo, de un vistazo
La superficie actual son 16 endpoints (un endpoint es cada combinación de verbo + ruta). Aquí los tienes agrupados para que sepas dónde vive cada cosa; cada uno tiene su página propia con ejemplos.
Pagos
Beneficiarios
Webhooks
Cuenta y sistema
Sandbox y producción
Toda API seria tiene dos mundos, y Alibanca no es la excepción. El sandbox es un ambiente de prueba idéntico al real por fuera, pero donde no se mueve un solo centavo de verdad: por debajo corre un proveedor simulado (lo llamamos MockProvider). Ahí puedes equivocarte, reintentar, provocar fallas a propósito y aprender sin riesgo. Producción es el mundo real, donde el dinero sí se mueve.
Cada mundo tiene su propia dirección base (base URL) — el prefijo que va delante de cada ruta — y su propio tipo de llave:
| Ambiente | Base URL | Tu llave empieza por |
|---|---|---|
| Sandbox | https://alibanca-api-production.up.railway.app | sk_test_… |
| Producción | https://api.alibanca.com | sk_live_… |
Fíjate que el prefijo de la llave te dice, de un vistazo, en qué mundo estás. Una llave sk_test_ jamás mueve dinero real; una sk_live_ siempre lo hace. Nunca mezcles las dos.
.02 queda en unknown; uno que termina en .03 mueve el dinero pero igual devuelve unknown (la trampa del doble-pago, para que verifiques que tu integración no re-emite); cualquier otro monto termina en completed. Así ensayas los casos difíciles antes de tocar producción. Detalle en Montos mágicos →.Tu primera llamada: GET /v2/version
Antes de firmar nada ni de sacar tu llave, hagamos la llamada más simple de todas. GET /v2/version es pública: no lleva autenticación. Sirve para dos cosas — confirmar que tienes conexión con Alibanca, y descubrir las capacidades vigentes (versión, ambiente, qué rieles están activos, dónde está el contrato). Es el "hola, ¿estás ahí?" del sistema, y siempre conviene llamarla antes de empezar a firmar peticiones.
curl https://alibanca-api-production.up.railway.app/v2/version
La respuesta te dice todo lo que necesitas para orientarte:
{ "version": "2.1.0", // versión del servicio "apiVersion": "v2", // versión de la API (la del /v2) "environment": "sandbox", "rails": ["PM", "CCE"], // rieles activos "links": { "openapi": "https://alibanca-api-production.up.railway.app/v2/openapi.json", "jwks": "https://alibanca-api-production.up.railway.app/v2/webhook/keys" } }
| Campo | Tipo | Descripción |
|---|---|---|
| version | string | La versión del servicio desplegado. Útil para reportar incidencias. |
| apiVersion | string | La versión del contrato de la API — siempre v2 mientras uses las rutas /v2. |
| environment | string | En qué mundo estás: sandbox o production. Confírmalo antes de mover dinero. |
| rails | array | Los rieles disponibles ahora mismo, por ejemplo ["PM", "CCE"]. |
| links | object | Enlaces útiles: openapi (el contrato completo de la API) y jwks (las llaves públicas para verificar webhooks). |
/v2/openapi.json. Ese enlace apunta a la especificación OpenAPI completa y pública: la fuente de verdad, campo por campo, de toda la API. Muchas herramientas (generadores de clientes, Postman, editores) la leen directo. Si alguna vez dudas de un tipo o un nombre de campo, ese archivo manda.El sobre de respuesta: éxito y error
Alibanca responde con una estructura predecible, para que tu código no tenga que adivinar dónde está cada cosa. Piénsalo como un sobre: siempre el mismo formato por fuera, con el contenido variable adentro. Hay exactamente dos sobres.
Cuando todo sale bien
Una respuesta exitosa trae tres campos fijos: status (siempre "success"), traceId (un identificador único de esa petición) y payload (los datos que pediste). El traceId es tu mejor amigo cuando algo se pone raro: si escribes a soporte, ese código nos deja encontrar tu petición exacta en los registros en segundos. Guárdalo en tus logs.
{ "status": "success", "traceId": "trc_9f3ab21c7d", "payload": { "id": "pay_01HZ...4TK", "state": "completed", "amountMinor": "150000", "currency": "VES" } }
La regla mental es: lee siempre payload para los datos, y usa status nada más para confirmar que fue éxito. Lo que hay dentro de payload cambia según el endpoint (un pago, un saldo, un beneficiario), pero el sobre por fuera es siempre igual.
Cuando algo falla
El sobre de error es a propósito minimalista: un solo campo error con un mensaje legible, acompañado del código HTTP que ya viste en la cabecera. Sin ambigüedad.
{ "error": "amountMinor es obligatorio" }
2xx, espera el sobre { status, traceId, payload }. Si es 4xx o 5xx, espera { error }. No busques payload en una respuesta de error ni error en una de éxito: cada sobre trae solo sus campos.El dinero se cuenta en céntimos, como texto
Esta es, quizás, la regla más importante para no equivocarte con las cantidades. En Alibanca el dinero nunca se representa con decimales ni con números "de coma flotante". Se usa la unidad menor de la moneda — el céntimo — y siempre como string (texto), en el campo amountMinor.
¿Por qué? Porque los números decimales en las computadoras (los float) mienten un poquito: 0.1 + 0.2 no da exactamente 0.3 en muchos lenguajes. Con dinero, ese "poquito" es inaceptable. Trabajando en céntimos y como texto, nunca hay redondeos traicioneros. Así que si quieres mover 150 bolívares con 00, no escribes 150.00: escribes la cantidad de céntimos, "150000" (150.000 céntimos), como cadena.
| Quieres mover | amountMinor |
|---|---|
| Bs. 1,00 | "100" |
| Bs. 25,50 | "2550" |
| Bs. 1.500,00 | "150000" |
"150000" entre comillas, no 150000 pelado. Y recuerda que ese último céntimo, en sandbox, dispara los montos mágicos →: un "150002" queda en unknown a propósito. Ten cuidado de no elegir esos finales por accidente cuando lo que quieres es un pago normal.Monedas y rieles
Cada monto viaja con dos datos que definen "en qué" y "por dónde". La moneda va en el campo currency: hoy el valor es "VES" (bolívares); vienen más próximamente. El riel (campo rail) es el carril por el que sale el dinero:
| rail | Es | El destino es |
|---|---|---|
| PM | Pago móvil | Un número de teléfono asociado a una cuenta. |
| CCE | Transferencia / CCE | Un número de cuenta bancaria (cámara de compensación). |
Cuando emites un pago tienes dos maneras de decir a dónde va, y son excluyentes (una u otra, nunca las dos): o apuntas a un beneficiaryId — un destino que ya guardaste antes — o especificas el destino "en línea" con rail + beneficiary (el teléfono o la cuenta) en la misma petición. Guardar beneficiarios tiene una ventaja de seguridad grande: al crearse, el destino queda congelado (riel, cuenta y documento son inmutables), así nadie puede desviar un pago editando un destino después. Eso lo cubrimos a fondo en Beneficiarios →.
El mapa: por dónde empezar
Ya tienes el vocabulario. Este es el orden que recomendamos para pasar de cero a mover dinero de verdad, sin saltarte los pasos que te protegen.
Confirma la conexión
Llama GET /v2/version (la que ya hiciste arriba). Sin llaves, sin firmas. Si te responde, tienes línea con Alibanca y sabes qué rieles están activos. Es el chequeo de humo.
Aprende a autenticar y firmar
Cada petición privada lleva tu llave en el header x-api-key y una firma en x-signature. La firma es RSA-SHA256 sobre un "sobre canónico" — método, ruta, llave, idempotency-key, cuerpo crudo y un nonce, en ese orden — y tu llave privada nunca sale de tu lado. Suena denso; en Autenticación y firma → lo desglosamos con código listo para copiar.
Guarda un beneficiario (opcional pero recomendado)
Con POST /v2/beneficiaries guardas un destino y lo congelas. Después pagas apuntando a su beneficiaryId, más seguro y más limpio que repetir la cuenta en cada pago.
Emite tu primer pago
POST /v2/payments con amountMinor, currency y el destino. Usa siempre un header idempotency-key (una clave única por operación) para que reintentar nunca pague doble. En sandbox, juega con los montos mágicos para ver completed, unknown y failed con tu propio código.
Recibe eventos con webhooks
En vez de preguntar el estado a cada rato (poll), configura un PUT /v2/webhook con tu URL y Alibanca te avisará cuando un pago cambie de estado. Los webhooks van firmados con criptografía asimétrica: los verificas con la llave pública del JWKS →, sin secretos compartidos.
GET /v2/payments/:id) siempre está disponible para consultar cuando quieras. La buena práctica es usar los dos: el webhook para reaccionar rápido, el poll como red de respaldo. Y recuerda la regla de oro — un pago en unknown se resuelve por conciliación, tú no lo reintentas.Siguientes pasos
Con esto ya tienes el panorama completo: qué es Alibanca, cómo está armada la API, la diferencia entre sandbox y producción, los dos sobres de respuesta, el dinero en céntimos y el mapa de aprendizaje. De aquí en adelante, sigue el orden del mapa: empieza por Autenticación y firma →, luego Emitir un pago →, y ten a mano Estados de un pago → e Idempotencia →, que son el corazón del money-safety. Cuando dudes de un campo, la verdad final está en el contrato público de /v2/openapi.json. Bienvenido a Alibanca.