Core concepts

This is the card issuing model, used throughout these guides and the API reference. Other products have their own objects and their own sections.

The object model

Program

A program is your card product as configured with the network and issuing bank. It defines things such as the BIN range cards are issued from, supported currencies, card designs, and fee schedule.

Programs are configured during onboarding and attached to your organization. You do not create or configure them through the API.

An account belongs to exactly one program, and cards issued against that account inherit the same program.

Cardholders are separate from programs. A cardholder represents a legal person, so the same person can have an account under your consumer program and another under your corporate program while remaining a single cardholder record.

When you create an account, specify the program with program_id on POST /v1/accounts. You don't need to provide the program again when working with the account's cards, spend controls, or reporting.

Your client ID determines your organization and environment, but not the program. See authentication.

The two list endpoints that can return objects across programs, GET /v1/accounts and GET /v1/cards, accept an optional ?program_id= filter. If you leave the filter out, they return objects from every program available to you.

GET /v1/programs returns the programs available to the current client, including their IDs and names. It only requires a valid token and no additional scope.

You can also see the same programs in Cockpit under Settings → Programs. Each row represents a program attached to your organization in the current environment.

Cardholder

A cardholder (chd_) is the person a card belongs to. It is the base identity record in the model: accounts and cards both reference the cardholder, and a card cannot be issued without one.

A cardholder represents a legal person and is not tied to a particular program. Their identity and verification status are therefore established once and can be used across your programs.

For example, the same cardholder can have accounts under two different programs at the same time.

The most important field is kyc_status. KYC must be approved before a card can be activated.

kyc_status	Meaning	Can a card be issued?
not_started	Record created; verification has not started	No
pending	Verification submitted and under review	No
approved	Verification completed successfully	Yes
rejected	Verification failed	No
review_required	Additional evidence is needed	No

See KYC lifecycle and statuses for the full set of transitions.

Two other fields are required for issuance regardless of kyc_status:

• address — the address the card is registered to
• identity_document — the identity document associated with the cardholder

If either is missing, issuance fails with address_required or identity_document_required.

You handle the actual identity verification and report the result to the API. Cardholders submit their documents to your identity provider, and you send us an attestation containing who performed the verification, when it happened, and the result.

Identity documents do not pass through this API. See identity documents.

Account

An account (acct_) holds value. Each account has one currency, belongs to one cardholder, and has three balances:

Balance	Meaning
ledger_balance	Money that has settled
held_balance	Money reserved by approved authorizations that have not cleared
available_balance	ledger_balance − held_balance. This is the spendable balance

Use available_balance when showing customers how much they can spend. Use ledger_balance for reconciliation.

If you display ledger_balance as the spendable amount, you'll include funds that may already be held by authorizations.

A cardholder with multiple currencies will have a separate account for each currency. See balances: ledger vs available for more detail.

Card

A card (card_) is the payment instrument. Its form_factor is either virtual or physical, and each card spends from exactly one account.

The relationship between the card and account is explicit: a card without an account cannot authorize a transaction.

The status field describes the card's lifecycle:

status	Meaning
pending	Accepted; the processor has not issued the card yet
inactive	Issued and waiting for you to activate it
active	Activated and ready to use
frozen	Temporarily blocked; can be unfrozen
expired	Past its expiry date
closed	Permanently terminated and cannot be reopened

See the card lifecycle guide for the complete set of transitions.

Authorization

An authorization (auth_) is a merchant asking whether a card has enough available funds for a purchase. It is created by card activity, not directly by you.

When an authorization is approved, the API places a hold on the funds rather than moving the money immediately. The hold reduces available_balance and remains until the transaction clears, the authorization is reversed, or the hold expires.

status	Meaning
pending	Approved and holding funds; not yet cleared
approved	Authorization has cleared
declined	Authorization was refused by us or by you
reversed	Merchant released the authorization before it cleared
expired	The hold expired without clearing

Transaction

A transaction (txn_) represents settled money movement. It is what appears on a statement and what reconciliation files are based on.

The final transaction amount can differ from the original authorization amount. Some transactions, such as force posts and merchant-originated refunds, do not have an authorization at all.

Because of this, don't assume every transaction maps one-to-one to an authorization.

Naming rules

• IDs are opaque. Don't parse them, sort by them, or rely on anything beyond the documented format.
• The prefix identifies the object type: prog_, chd_, acct_, card_, auth_, txn_, disp_, tok_, whk_, evt_.
• Every object includes an object field identifying its type. Use that field when you need to determine how to handle a response rather than inspecting the ID.

See ID prefixes for the complete list.