How it works
Card issuing involves several different parties. Understanding who is responsible for each part makes it easier to know where a decision comes from and what your integration needs to handle.
The parties
Who owns what
| Concern | Owner | Notes |
|---|---|---|
| Your users, your product, your UI | You | We don't interact with your end users directly, other than the cardholder records you provide |
| Identity verification decision | You or us, by program | This is agreed during program setup |
| Cardholder, account, and card records | AletaPlanet | These are authoritative. Any copy you keep is a cache |
| Customer funds | Issuing bank | Funds are held in a segregated account, with the ledger maintained by us |
| Balance and available funds | AletaPlanet | See balances: ledger vs available |
| Approve or decline an authorization | AletaPlanet | Real-time decisioning by your platform is planned, but isn't available yet. See real-time decisioning |
| Card number, expiry, CVV, PIN | AletaPlanet, inside PCI scope | These details are never returned to your servers in clear text |
| Card manufacture and delivery | Fulfillment partner, coordinated by us | Tracking through the API is planned |
| Clearing and settlement with the network | AletaPlanet and issuing bank | You see the results through transactions and reconciliation files |
| Disputes and chargebacks | AletaPlanet, with evidence from you | Scheme deadlines still apply |
What happens when a card is used
A card payment usually shows up as at least two separate events, often hours or days apart. Your integration needs to handle both.
- Authorization. The merchant asks the network whether the payment can be approved. The network routes the request to us. We check the card state, spend controls, and available balance, then approve or decline within the network's timeout window, which is measured in seconds. If approved, the amount is held rather than moved.
- Clearing. Usually the next day, the merchant submits the transaction for processing. The hold is released and the debit is posted. The cleared amount can be different from the original authorized amount, such as when a restaurant adds a tip.
- Settlement. Money moves between the acquiring and issuing banks. You won't see this as part of the real-time API flow, but the results are included in reconciliation files.
The important part for your integration is that an authorization isn't the same as money movement. If you calculate balances using only settled transactions, the balance will be wrong for much of the day. That's why the API exposes separate figures for the ledger and available balance. See balances: ledger vs available.
Where you plug in
There are two main integration points:
- The REST API at
api.aletaplanet.com— for actions you initiate. - Webhooks — for events we send to you asynchronously.
Card issuing is event-driven, so your integration should be built to handle webhooks as well as API responses. A synchronous-only integration will miss important changes.