Skip to main content
This guide explains the full card issuance flow: what needs to be true before issuance, what data you provide, and what you should do after a card is created.
For request parameters, examples, and response shapes, use the Cards API reference.

​
Before you issue a card

Some card programs require a customer to be created before you can issue a card.In those cases:
  • You create and verify the customer first
  • Then you pass the customer’s ID (customerId) when issuing the card
Start here:
Depending on your setup, the customer may need product access granted before you can proceed.
typeId identifies the card program/BIN available to your account. If typeId is invalid or inactive, issuance fails.

​
Issuance flow (high level)

1

Choose the card model

You typically issue one of these models:
  • Card: a standalone reloadable virtual card
  • Budget card: a card linked to a budget (spend is controlled by that budget)
The model determines what else you must provide (for example, a budget card requires a budget).
2

Provide cardholder identity

There are two common ways to identify the cardholder:
  • Preferred (when required by the program): pass customerId
  • Fallback: if you do not pass customerId, you must provide firstName and lastName
Some card programs require customerId and will not allow name-only issuance.
3

Provide card configuration

You typically provide:
  • typeId (card program/BIN)
  • For Card: initialBalance is required
  • For Budget card: budgetId is required
Optional fields commonly used for your own systems:
  • label
  • externalId
4

Issue the card and store the result

On success, you receive identifiers and card details needed for downstream operations, including:
  • Card ID
  • Masked card number
  • Status
  • Provider IDs (when applicable)
Treat PAN/CVC/expiry as sensitive. Never log or store them unencrypted.

​
After issuance

Set or change the PIN

PIN must always be chosen by the cardholder and must follow strict anti-guessing rules.

Top up or withdraw funds

Move funds between your organization balance and the card balance.

Change card status

Freeze, unfreeze, or delete a card based on the user’s lifecycle and risk signals.

Handle disputes

Collect evidence, track dispute progress, and communicate outcomes to the cardholder.

​
Troubleshooting

Common causes:
  • typeId is invalid or not active for your account
  • the customer is not verified yet (still pending / needs information / rejected)
  • compliance restrictions (for example, nationality rules)
  • missing required linkage (for example, customerId or budgetId for certain programs)
Use the API error message for the exact reason and surface an actionable message to the end user.
Check the card status and program rules. A card may be created but blocked by compliance or program configuration.