Card Programme Integration: What Engineering Teams Should Know Before They Start
August 6, 2026
Card programmes look like an API integration and behave like a distributed systems problem. The provider documentation describes endpoints for creating cards, setting limits, and retrieving transactions, and a team can get a test card issued in an afternoon. The difficulty arrives later, in the areas the documentation covers lightly: what your ledger does when an authorisation is approved but never settles, how you reconcile against a provider statement that disagrees with your own records, and what your support team can actually see when a customer’s card is declined at a hotel check-in.
We built and maintain the engineering side of the KimlCards programme, which runs on a white-label issuing provider, and the notes below reflect the integration problems that consistently take longer than teams expect.
Know Which Role You Are Actually Playing
Card programmes involve several parties and it is worth being precise about which one you are. The issuer is a licensed bank or e-money institution that carries the regulatory relationship with the card scheme. The issuer-processor operates the authorisation infrastructure. The programme manager owns the customer relationship, the product, and usually the compliance obligations attached to onboarding. The card scheme — Visa or Mastercard — sets the rules everyone operates under.
Most crypto card products are built on a white-label arrangement in which a provider supplies issuing, processing, and often programme-management services, and the client supplies the product and the users. That arrangement determines what you can control. Card design, spending limits, and notification behaviour are usually yours. Authorisation logic, decline reasons, and dispute handling usually are not. Establishing this boundary before design begins prevents the most common category of wasted work: building a feature the provider will not permit.
Dapplication Tech’s role in this work is software engineering. We are not an issuer, a payment institution, or a programme manager, and we do not hold client funds.
Authorisation and Settlement Are Different Events
This is the single distinction that causes the most ledger bugs. When a card is presented, the merchant requests an authorisation, which places a hold against available balance. Settlement — the actual movement of funds — happens later, typically one to three business days afterwards, and the settled amount need not match the authorised amount.
The divergences are routine rather than exceptional. A restaurant authorises an estimated total and settles a higher figure once a tip is added. A hotel or car rental firm places a substantial hold at check-in and settles a different amount at checkout, sometimes days later. A merchant authorises and never settles at all, leaving a hold that expires on the scheme’s timetable rather than yours. A single authorisation can also produce multiple partial settlements.
A ledger that treats authorisation as a completed debit will drift out of alignment with reality within days. The correct model tracks available balance and settled balance separately, holds authorisations as pending entries with their own expiry, and reconciles each settlement against its originating authorisation where a link exists — while handling the cases where it does not. Getting this wrong is also the leading cause of support tickets, because customers see money that is neither spent nor available and no one internally can explain where it sits.
Design the Ledger Before Writing the Integration
The most consequential decision in a card programme build is made before any provider API is called: how you represent money internally. Double-entry accounting, with every movement recorded as balanced debits and credits against defined accounts, is the correct approach and teams routinely skip it in favour of a mutable balance column that is faster to build and impossible to audit.
Three properties are worth insisting on. Entries are append-only, so a correction is a new entry rather than an edit. Every entry carries an idempotency key derived from the provider’s event identifier, so a replayed webhook cannot double-count. Balances are derived from the entry history rather than stored as an independently mutable field, so a discrepancy is a computation error you can trace rather than a corruption you cannot.
Providers deliver events by webhook, which means out-of-order delivery, duplicate delivery, and occasional non-delivery are all normal conditions to design for rather than faults to be surprised by. Any integration that depends on webhooks alone will eventually miss an event. A scheduled reconciliation job that pulls provider-side transaction state and compares it against your ledger catches those gaps, and it should run daily from the first week rather than being added after the first incident.
PCI Scope Is Something You Design Away
Full card numbers, magnetic stripe data, and CVV values attract the heaviest compliance obligations under PCI DSS. Where you are integrating as a programme manager on a third party’s issuing platform — as distinct from operating a gateway or processor, where storing account data is inherent to the role — the practical objective is to ensure that data never reaches your systems at all. Providers support this through hosted fields, iframes, or SDK components that render sensitive values directly from provider infrastructure into the user’s client, so that your application displays a card without ever transmitting or storing its number.
Where card data must be referenced, work with provider-issued tokens rather than the underlying values. And treat this as a genuine boundary rather than a convention: a single well-meaning debug log that captures a full request body can pull a system into scope it was designed to stay outside of. Log redaction belongs in the shared logging layer, enforced by default, not applied endpoint by endpoint.
Crypto-Funded Cards Add a Currency Problem
When the funding source is a crypto balance rather than a fiat account, an additional layer appears. Every authorisation needs a conversion from crypto balance to the transaction currency, at a rate valid at that moment, fast enough not to time out the authorisation.
Several questions follow, and they are product decisions with engineering consequences. Is the rate locked at authorisation or applied at settlement, and who absorbs the movement in between? What happens when a settlement exceeds the authorised amount and the crypto balance has since fallen in value? How is the spread disclosed to the user — as an explicit fee, or built into the quoted rate? What happens to a partially settled authorisation when the funding asset has moved significantly?
There is no universally correct set of answers, but they must be answered deliberately and documented, because they determine both your risk exposure and what you can accurately tell customers. Fee and rate disclosure in particular is an area where regulators across jurisdictions have shown sustained interest, and the disclosure needs to match what the code actually does.
Interchange Terms Deserve Engineering Attention
Card programme economics rest on interchange, and provider agreements differ in ways that materially change revenue. One term worth reading carefully is whether your share is calculated on gross or net interchange — that is, before or after scheme fees and other deductions. The headline percentage can look identical between two agreements while the actual revenue differs substantially. Whoever builds the revenue reporting should read the commercial agreement rather than working from a summary, because reporting that does not match the contract’s calculation basis will produce forecasts nobody can reconcile.
What to Budget For
The provider integration itself is a modest piece of work. The ledger, the reconciliation pipeline, the webhook handling with proper idempotency, the support tooling that lets a human answer “why was this declined,” and the dispute workflow are the substance of the project, and they are where the schedule goes if they were not scoped at the start.
The most useful early step is a written walk-through of the full transaction lifecycle — authorisation, partial settlement, reversal, expiry, refund, chargeback — with the provider’s documentation open and your ledger design on the table. Every case that cannot be answered in that session is a defect you would otherwise find in production.