Saltar al contenido principal
Migo Docs

Ciclo de vida de la tarjeta

Esta página es la referencia canónica de estados y operaciones de la tarjeta: dar de alta (activar) una tarjeta en un usuario, bloquear, actualizar el alias, leer detalles y generar estados de cuenta. Para la secuencia de onboarding de extremo a extremo, consulta el Flujo de emisión de tarjetas; para el registro de usuarios/titulares, consulta Gestión del titular.

Dar de alta una tarjeta en un usuario​

Una tarjeta entregada llega inactiva y no puede transaccionar hasta que se da de alta en un usuario. Hay dos rutas — elige la que se ajuste a tu integración. Solo la Opción B (por API) requiere vincular la tarjeta primero; en la Opción A el webview lo hace por ti.

Opción A — Webview de activación hospedado (autoservicio del titular)​

El titular activa la tarjeta por sí mismo a través del webview de activación hospedado por Migo. Ábrelo con el userId del titular:

https://web.migopayments.com/card-activation?client=migoDeveloper&userId=YOUR_USER_ID
Query paramRequeridoPropósito
userIdSíEl titular dueño de la tarjeta
clientNoPista de marca para la pantalla de activación (el slug de tu cliente)

En el webview el titular ingresa el número de tarjeta y el nombre del titular impreso en el plástico, y confirma. El webview asocia la tarjeta con el usuario y la activa — no se requiere integración por API de tu lado (incluida la vinculación, que el webview realiza internamente).

nota

Usa el host de sandbox para pruebas: https://sandbox.migopayments.com/card-activation?client=migoDeveloper&userId=YOUR_USER_ID.

Opción B — Activación por API (desde tu backend)​

Si activas tarjetas desde tu propio backend, el flujo tiene dos pasos: primero vincula la tarjeta física existente al usuario y luego actívala.

Paso 1 — Vincular la tarjeta al usuario​

POST /users/{userId}/cards vincula una tarjeta física existente al usuario. Requiere un parámetro de consulta clientId y un cuerpo con los siguientes campos:

curl -X POST "https://api.ali.app/rest/users/{userId}/cards?clientId=YOUR_CLIENT_ID" \
-H "Authorization: Bearer <token>" \
-H "x-application-id: YOUR_APP_ID" \
-H "Content-Type: application/json" \
-d '{
"card": "4111111111111111",
"alias": "My Personal Card"
}'
CampoRequeridoNotas
cardsíNúmero de tarjeta a vincular (debe pasar la verificación de tarjeta)
aliasnoAlias legible para la tarjeta

Paso 2 — Activar la tarjeta​

Luego llama al endpoint de activación. No recibe cuerpo de solicitud (solo los parámetros de ruta) y activa la tarjeta indicada para el usuario indicado:

curl -X POST https://api.ali.app/rest/users/{userId}/cards/{cardId}/activate \
-H "Authorization: Bearer <token>" \
-H "x-application-id: YOUR_APP_ID"

Ambas rutas producen el mismo resultado: una tarjeta activa lista para transaccionar. Para ver dónde encaja la activación en la secuencia general de onboarding, consulta el Flujo de emisión de tarjetas.

Bloquear / desbloquear​

El bloqueo es reversible y útil para eventos de tarjeta perdida o pausas temporales. Ambos endpoints no reciben cuerpo — cambian el estado de la tarjeta a BLOCK / UNBLOCK:

# Bloquear
curl -X POST https://api.ali.app/rest/users/{userId}/cards/{cardId}/block \
-H "Authorization: Bearer <token>"

# Desbloquear
curl -X POST https://api.ali.app/rest/users/{userId}/cards/{cardId}/unblock \
-H "Authorization: Bearer <token>"

Una tarjeta bloqueada rechaza todas las autorizaciones hasta que se desbloquee.

El gateway también expone una variante a nivel de tarjeta de bloqueo/desbloqueo identificada por tarjeta más usuario auth (usada por flujos de operador/con permisos en lugar de la propia sesión del titular). Ambos no reciben cuerpo:

# Bloquear / desbloquear una tarjeta para un usuario auth específico
curl -X POST https://api.ali.app/rest/cards/{cardId}/users/{authUserId}/block \
-H "Authorization: Bearer <token>"

curl -X POST https://api.ali.app/rest/cards/{cardId}/users/{authUserId}/unblock \
-H "Authorization: Bearer <token>"

Actualizar alias​

PATCH /cards/{cardId} actualiza únicamente el alias de la tarjeta:

curl -X PATCH https://api.ali.app/rest/cards/{cardId} \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{ "alias": "Groceries" }'

No existe un campo state/reason ni un endpoint dedicado para cerrar la tarjeta. Para descargar el saldo de una tarjeta, usa una operación WITHDRAW_FUNDS — consulta Asignar fondos.

Endpoint de detalles de la tarjeta​

curl "https://api.ali.app/rest/users/{userId}/cards/{cardId}?token=<view-token>" \
-H "Authorization: Bearer <token>"

GET /users/{userId}/cards/{cardId} ("Check Card Details") devuelve detalles sensibles de la tarjeta (p. ej. PAN/CVV) y requiere un view token de un solo uso en el parámetro de consulta token. No es una simple lectura de saldo/movimientos.

Estados de cuenta​

El endpoint de estados de cuenta genera un estado de cuenta mensual para un mes y año dados:

curl -X POST https://api.ali.app/rest/cards/{cardId}/statements \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{ "month": 3, "year": 2026 }'
CampoRequeridoNotas
monthsíMes a generar (1–12)
yearsíAño de cuatro dígitos