How prepaid cards issued by CaixaBank work on Truust: what each party does, how a card goes from requested to active, how balance moves on and off the card, and how requests and answers travel between Truust and CaixaBank in batch files.
Overview
M2P Issuing lets a company (the Account) hand out prepaid cards to the people it works with (its customers). The cards are issued by CaixaBank through its card platform (TCR). Truust sits in the middle: it receives the requests through the API, sends them to CaixaBank and keeps the accounting of every card. The key point is where the money lives:- The balance that can be spent with the card is held by CaixaBank. CaixaBank authorises every purchase against that balance, without asking Truust.
- Each card has its own wallet in Truust, of type
M2P_ISSUING. That wallet mirrors the card balance: it goes up when the card is topped up and down when balance is recovered or spent.
The Pieces
Card Lifecycle
1. Requesting a card
Two API calls: create the wallet that will back the card, then create the card on it.POST /wallets creates a new one, so a customer can have as many cards as needed. Cards are issued anonymous by default; cardholder data can be sent in ficha_beneficiario.
The card is returned with confirmed: false. Nothing has been sent to CaixaBank yet.
2. Issuing confirmation
In the next processing window the request travels to CaixaBank. When CaixaBank answers, the card is updated:- Accepted:
confirmed: true, the card token ingateway_reference_idand theactivation_codefor the cardholder. - Rejected: the card stays
confirmed: falseand the rejection is logged for review.
3. Top-ups
A top-up moves money from the Account wallet to the card wallet using a regular order:- Order with the card customer as buyer and seller, and fees set to 0.
- Payin
WALLETfrom the Account wallet. The money is now held in the order. - Payout
WALLETto the card wallet.
IN_PROGRESS and the money remains held in the order. In the next processing window the top-up is sent to CaixaBank:
- Accepted: the payout is executed (
CONFIRMED), the money reaches the card wallet and the custodial wallets record that this amount is now on the card. - Rejected: the payout is
DENIEDand the payin is refunded to the Account wallet.
confirmed: true) are sent; a top-up for a card that is still pending waits until the card is issued.
4. Balance recovery
The reverse movement: order withauto_settle, payin WALLET from the card wallet and payout WALLET to the Account wallet. It follows the same rule — the payout waits IN_PROGRESS until CaixaBank confirms that the balance has been taken off the card.
5. Consumption
What the cardholder spends is authorised by CaixaBank directly. CaixaBank reports it afterwards in a file, and Truust has to reflect it on the card wallet.The consumption file is not processed yet.
Batch Files
All the communication with CaixaBank happens through files exchanged by SFTP. There are three processing windows per day:
The import times are a provisional margin until CaixaBank confirms how long it takes to answer.
Outgoing file
Before each window Truust builds one file with everything that is pending, mixed together:- Issuing requests: cards with
confirmed: falsethat have not been sent yet. - Top-ups and balance recoveries: payouts held
IN_PROGRESSagainst a card that is already issued and that have not been sent yet.
cardIssuing_{ddmmyyyyHH}.txt in production and pruebasSNE_{ddmmyyyyHH}.txt in test.
Answer file
CaixaBank answers through the FB500 return channel. Truust reads every pending answer file and, line by line, finds the request by its request number:- Issuing answer: confirms the card and stores its token and activation code.
- Top-up / recovery answer: executes or denies the held payout, as described above.
Traceability
Every file sent and every file imported is recorded with its window, the number of lines and how many matched, and the result of each run is notified by email and Slack. The process only runs in production.The details of the TCR record layout and the CaixaBank file exchange will be completed in this section.
Sandbox
There is no connection with CaixaBank in sandbox: cards stayconfirmed: false and top-ups stay IN_PROGRESS. The Truust team simulates the answers that CaixaBank sends in production so the full flow can be tested.