Assign Funds

As the issuer, you load or unload funds against a card's balance. The direction is set by the operation field — ADD_FUNDS or WITHDRAW_FUNDS — with a positive amount in both cases.

There are two endpoints, and they take different bodies:

Endpoint	Body	Use it when
POST /cards/{cardId}/funds	FundsOperationDto	The operation originates from a channel (mobile, web, ATM) and you want to attach channel + custom metadata
PUT /cards/{cardId}/funds	CardAssingFundsDto	An issuer-side adjustment with a free-text note

Both move money — PUT is not a metadata-only amendment.

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

Field	Required	Notes
amount	yes	Monetary amount to apply (always positive)
operation	yes	ADD_FUNDS or WITHDRAW_FUNDS
channel	yes	Origin channel of the operation (e.g. MOBILE, WEB, ATM)
reference	yes	External reference for the funds operation
description	no	Short description (max 50 characters)
currency	no	ISO 4217 code; defaults to the card currency when omitted
customKeys	no	Object of custom key/value metadata

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": "Manual adjustment"
  }'

Field	Required	Notes
amount	yes	Monetary amount to apply (always positive)
operation	yes	ADD_FUNDS or WITHDRAW_FUNDS
reference	yes	External reference for the funds operation
observations	no	Free-text note for auditing or reconciliation
currency	no	ISO 4217 code; defaults to the card currency when omitted

A WITHDRAW_FUNDS operation cannot leave the card with a negative balance.

Reconciliation

Use the monthly movement feed to reconcile funds operations against your own ledger:

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

The path takes {month}/{year} and returns the card's movements for that period — useful for spotting out-of-band manual adjustments, refunds, etc.

Errors

Code	Name	Meaning
7303	INSUFFICIENT_FUNDS	Operation would leave the card below its available balance

See the full Error Catalog for the complete list.