Issuing cards

Card issuance is performed through the Card API after the required setup records have been created.

The exact issuance flow depends on the agreed record structure, but card creation always sits on top of the required account and setup records.

As described in the Core data model and Definitions, account setup and card creation use different identifiers depending on the structure:

• person_id or corporate_id for account setup
• person_id or employee_id for card creation, where employee_id is linked under the related corporate_id

If the account is set up under a corporate, the card is issued to the linked employee record rather than to the corporate record itself. For the person and client naming used in the API reference, see Definitions.

Card creation prerequisites

Before a card can be created, the required account and cardholder records must already exist in FINCI, together with any supporting setup records needed for that flow.

The account is the financial account the card will operate against. It defines the account-level ownership structure for the card setup and provides the record under which card activity is organized.

That is why the account must exist before card creation. A card is not created as a standalone record and linked later. It is issued within the existing account setup, whether that setup sits under a person or under a corporate.

Use the following sequence as the minimum prerequisite order:

• Person-based issuance: Person -> Account -> Card
• Company-based issuance: Corporate -> Account -> Employee -> Card

In the person flow, the account is set up with person_id, and the card is created with that same person_id.

In the company flow, the account is set up with corporate_id, but the card is created with employee_id because the card is issued to the employee rather than to the corporate record itself.

Where the agreed setup model supports it, company and account setup may be created together during the initial corporate setup step. The required card-creation order still remains Corporate -> Account -> Employee -> Card.

Across account setup and card creation, the main identifiers are:

• person_id for person-based account setup and person-based card issuance
• corporate_id for company-based account setup
• employee_id for company-based card issuance under the related corporate_id
• token_id as the returned FINCI card identifier after successful card creation

Account setup also requires external_number, the integrator-defined account reference. Even though the API represents it as a string, it must contain only digits 0-9, with no letters, spaces, signs, decimal separators, or other symbols. Use 6..20 digits.

The account entity must exist in both models even where balance is not used as the approval control during authorization decisioning. Depending on the agreed program model, balance may be checked against the client-managed account logic or ignored when the client makes the authorization decision through the webhook flow. The account record still remains required because the card is issued within that account structure rather than outside it.

For the record relationships behind these flows, see Core data model and Definitions.

Card creation request

A card creation request is built around three parts:

• the cardholder reference
• the card product and cardholder details
• the issuance and delivery settings

The cardholder reference identifies who the card is issued to. The cardholder details define how that card should be issued.

In practice, the API schema includes fields such as:

• the relevant cardholder identifier, typically employee_id or person_id
• product_id, provided by FINCI as part of the agreed product setup
• embossing_name
• expiration_date
• token_status
• token_stage
• delivery_address
• express_delivery

When card creation succeeds, the API returns the FINCI token identifier. In subsequent card endpoints, that card is identified as token_id.

In the current API schema, delivery fields are required on all card-creation requests, including digital-first issuance.

Use the API Reference for the exact required fields and payload format.

Default issuance profile

In the current API schema, card creation supports:

• token_status: new or active
• token_stage: digital or plastic_not_delivered

The normal commercial flow is:

• token_status = active
• token_stage = digital

That means the card is created in digital stage and active status. The active status, not the stage, is what makes the card usable immediately for transactions unless a different issuance setup is agreed for the program.

Where a card is created with token_status = new, the card may exist but remain unusable for authorization until activation is completed.

Issuance models

The same card creation structure can support different issuance models, depending on the agreed product setup and customer journey.

• digital-first issuance The card is created in digital stage, typically with an active status for immediate use.
• physical issuance pending delivery The card is created with physical fulfillment in progress, while the stage reflects that the plastic card has not yet been delivered.
• inactive issuance pending activation The card is created but remains unusable for transactions until the required activation step or agreed activation condition is completed.

The combination of product_id, token_status, token_stage, and delivery settings should reflect the intended issuance model for the program.

Sensitive card data handling

Any retrieval, storage, transmission, or display of card data must be governed by the applicable compliance model and internal security controls.

At a minimum:

• sensitive card data must not be written to application logs
• access must be restricted to the systems and operators that require it
• internal distribution of card data should be minimized
• decryption keys and related cryptographic material must be stored, managed, and used securely
• downstream handling must follow the agreed compliance and security requirements for the program

This guide does not define the permitted retrieval scope for sensitive card data. That scope must follow the API contract, the agreed product setup, and the applicable compliance obligations.