Asignar Fondos

Como emisor, cargas o descargas fondos sobre el saldo de una tarjeta. La dirección se define con el campo operation — ADD_FUNDS o WITHDRAW_FUNDS — con un amount positivo en ambos casos.

Hay dos endpoints, y reciben cuerpos distintos:

Endpoint	Cuerpo	Úsalo cuando
POST /cards/{cardId}/funds	FundsOperationDto	La operación se origina desde un canal (móvil, web, ATM) y quieres adjuntar el canal + metadata personalizada
PUT /cards/{cardId}/funds	CardAssingFundsDto	Un ajuste del lado del emisor con una nota de texto libre

Ambos mueven dinero — PUT no es una corrección de solo metadata.

POST /cards/{cardId}/funds

curl -X POST https://api.ali.app/rest/cards/{cardId}/funds \
  -H "Authorization: Bearer <token>" \
  -H "x-application-id: YOUR_APP_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "operation": "ADD_FUNDS",
    "channel": "MOBILE",
    "reference": "TOPUP-2026-04-18-001",
    "currency": "GTQ",
    "description": "Loyalty reward"
  }'

Campo	Requerido	Notas
amount	sí	Monto a aplicar (siempre positivo)
operation	sí	ADD_FUNDS o WITHDRAW_FUNDS
channel	sí	Canal de origen de la operación (p. ej. MOBILE, WEB, ATM)
reference	sí	Referencia externa de la operación de fondos
description	no	Descripción corta (máx. 50 caracteres)
currency	no	Código ISO 4217; por defecto la moneda de la tarjeta si se omite
customKeys	no	Objeto de metadata personalizada clave/valor

PUT /cards/{cardId}/funds

curl -X PUT https://api.ali.app/rest/cards/{cardId}/funds \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50.00,
    "operation": "WITHDRAW_FUNDS",
    "reference": "WD-2026-04-18-001",
    "currency": "GTQ",
    "observations": "Ajuste manual"
  }'

Campo	Requerido	Notas
amount	sí	Monto a aplicar (siempre positivo)
operation	sí	ADD_FUNDS o WITHDRAW_FUNDS
reference	sí	Referencia externa de la operación de fondos
observations	no	Nota de texto libre para auditoría o conciliación
currency	no	Código ISO 4217; por defecto la moneda de la tarjeta si se omite

Una operación WITHDRAW_FUNDS no puede dejar la tarjeta con saldo negativo.

Conciliación

Usa el feed mensual de movimientos para conciliar las operaciones de fondos contra tu propio libro mayor:

curl "https://api.ali.app/rest/cards/{cardId}/transfers/4/2026" \
  -H "Authorization: Bearer <token>"

La ruta recibe {month}/{year} y devuelve los movimientos de la tarjeta de ese período — útil para detectar ajustes manuales fuera de banda, reembolsos, etc.

Errores

Código	Nombre	Significado
7303	INSUFFICIENT_FUNDS	La operación dejaría la tarjeta por debajo de su saldo disponible

Consulta el Catálogo de errores completo para la lista total.