Skip to main content
Issue payment cards to your customers through a single API, whatever issuer sits underneath. Truust is multi-tenant and issuer-agnostic: every Account chooses which issuer backs its cards, and the same calls create cards, fund them and track what is spent. This guide explains the common model; each issuer has its own guide for the details.

Overview

Card issuing on Truust is built around one idea: your integration should not depend on the issuer. Stripe, CaixaBank or Mastercard each have their own APIs, file formats and rules. Truust absorbs those differences, so that issuing a card, topping it up or reading its movements looks the same no matter who issues it. What changes from one issuer to another is a single parameter, the card type (payin_type): Switching issuer, or running several of them in parallel for different Accounts, does not require changes in your integration beyond that value.

The Pieces

Issuer configuration lives per Account, not per platform. Two Accounts on the same platform can issue through different issuers, or through the same issuer with different programmes.

The Common Contract

Every issuer follows the same three rules.

1. Cards are issued with one endpoint

First create the wallet that will back the card, then issue the card on it:
There are no issuer-specific endpoints. Optional fields that only make sense for one issuer (for instance cardholder data for CaixaBank) are documented in that issuer’s guide and ignored by the rest.

2. The card tells you its status

The wallet only carries the balance; everything about the card itself is on the card.

3. Money moves as regular orders

Loading balance onto a card, or taking it back, is an ordinary order with a WALLET payin and a WALLET payout: You use the same orders, payins and payouts you already use for any other wallet-to-wallet movement, with the same webhooks and the same reporting.

Who Authorises the Purchases

This is the one real difference between issuers, and it decides how fast things happen.

Truust authorises

With STRIPE cards, the wallet balance is the card balance. When the cardholder pays, the issuer asks Truust in real time, and Truust approves or declines against the available balance of the wallet. Card issuing and top-ups are immediate. Every purchase attempt, declines included, is recorded as an order with the Authorization category, so you see each payment the moment it happens.

The issuer authorises

With M2P_ISSUING and M2P_ICCP cards, the spendable balance is held outside Truust, and every purchase is authorised there without asking Truust. The wallet carries the issuer as its type and mirrors that balance. For M2P_ISSUING, operations that touch the card are asynchronous:
  • A new card is returned with confirmed: false and becomes confirmed: true when the issuer confirms it.
  • A top-up or recovery payout stays IN_PROGRESS, with the money held in the order, until the issuer confirms it. It then becomes CONFIRMED, or DENIED with the payin refunded to its origin.
For M2P_ICCP, issuing a virtual card is immediate: it only assigns a limit, so no money has to move. Balance is loaded and recovered on the parent card. In both cases purchases reach Truust after they happen, when the issuer reports them, and are then reflected on the wallet. The wallet balance can therefore lag behind the real one until the next report. Your integration does not need to poll the issuer or know how it communicates: listen to the usual card and payout webhooks, or read the resources, and act on their status.

At a glance


The Issuers

Stripe Issuing — STRIPE

Virtual Visa cards for consumers and businesses, issued in EUR. The cardholder needs a full identity (name, email, phone, date of birth and address). The card number and CVC are revealed in the browser through Stripe’s own secure elements and never pass through Truust. Full details: Stripe Authorization.

CaixaBank prepaid — M2P_ISSUING

Prepaid cards issued by CaixaBank. Cards are anonymous by default, with optional cardholder data. Each card has its own wallet, so a customer can hold as many cards as needed. Requests and answers are exchanged with CaixaBank in several processing windows a day. Full details: M2P Issuing.

Mastercard iCCP — M2P_ICCP

iCCP (In Control for Commercial Payments) is a Mastercard solution for B2B payments, designed for companies that pay many suppliers — for example travel agencies paying hotels, airlines or wholesalers. An M2P_ICCP card is a virtual card with a particularity: it always hangs from a parent card.
  • Parent card. The company’s corporate card. It is the only card that holds money: the company loads funds onto it.
  • M2P_ICCP cards. Created against the parent card, one per payment or use case. They hold no balance of their own: each one has a limit, a spending cap that can be restricted by:
A purchase that breaks any of these controls is declined by Mastercard before it reaches the balance. Issuing a virtual card moves no money. A purchase is authorised against the limit of the virtual card and charged to the balance of the parent card, and only what is actually spent leaves it. The unused limit of a virtual card never left the parent card, so it stays available to the company.
On Truust, M2P_ICCP follows the same contract as the other card types: cards are issued with POST /customers/{uuid}/cards, payin_type: "M2P_ICCP" and the wallet_id of the parent card, plus the controls. Balance is loaded onto the parent card with regular orders, and purchases are reported back as they are charged. The full card number, expiry and CVC are generated by Mastercard and never pass through the Truust API. They are shown to the company through a short-lived secure link, in the same spirit as the Stripe secure elements. Once delivered, keeping them safe is the responsibility of whoever uses the card.

Choosing an Issuer

The choice is made per Account when the issuer gateway is configured. Contact the Truust team to enable an issuer on your Account.

Notes

  • Always send numeric ids (customer_id, wallet_id) in request bodies; UUIDs are only used in URLs.
  • One STRIPE or M2P_ISSUING card per wallet. Issuing another card means creating another wallet. M2P_ICCP cards are the exception: many can be issued against the wallet of the same parent card.
  • A limit is not a balance. The sum of the limits of the M2P_ICCP cards can exceed the parent card balance; each purchase still needs enough balance on the parent card.
  • Truust never stores or returns the full card number. Only the last four digits are exposed in alias.
  • For issuer-authorised cards, treat confirmed and the payout status as the source of truth: an operation is done when the issuer has confirmed it, not when the API accepts it.
  • Cancelling a card cannot be undone. Issue a new one instead.
  • See the Create wallet endpoint and Get card endpoint for the full request schemas.