Ciclo de Vida de la Tarjeta

Esta página es la referencia canónica de estados y operaciones de la tarjeta: emitir una tarjeta física de Migo, vincular una tarjeta existente, activar, 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.

Emitir una tarjeta

Este es el endpoint de emisión de tarjetas físicas emitidas por Migo. No recibe cuerpo de solicitud — la tarjeta se crea para el usuario identificado en la ruta:

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

Los identificadores de tarjeta son numéricos. La tarjeta recién creada necesita un PIN antes de poder autorizar transacciones — consulta Gestión de PIN.

Vincular una tarjeta existente a un usuario

POST /users/{userId}/cards vincula una tarjeta existente al usuario (no es un endpoint de emisión de tarjetas físicas). Requiere un parámetro de consulta clientId y un cuerpo ExternalLinkCardUserDto:

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"
  }'

Campo	Requerido	Notas
card	sí	Número de tarjeta a vincular (debe pasar la verificación de tarjeta)
alias	no	Alias legible para la tarjeta

Activar una tarjeta

Una tarjeta entregada llega inactiva y no puede transaccionar hasta que se activa. Hay dos rutas de activación — elige la que se ajuste a tu integración:

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 param	Requerido	Propósito
userId	Sí	El titular dueño de la tarjeta
client	No	Pista 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.

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, 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 (UpdateCardDto):

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 (CreateStatementDto):

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 }'

Campo	Requerido	Notas
month	sí	Mes a generar (1–12)
year	sí	Año de cuatro dígitos