Core data model

The integration relies on a small set of records that define the setup structure, card issuance, and transaction activity. For short term definitions, see Definitions.

Core setup records

Account and customer structure

The account record represents the financial account used for card issuance and transaction activity.

In the current API schema, account setup links the account to either:

• person_id
• corporate_id

A person is the person-side customer record. A corporate is the company-side customer record.

For person, corporate, and employee records, the API also uses external_id as the partner-defined identifier used to map the FINCI record back to the partner's internal record.

Cardholder

The cardholder is the individual the card is issued to.

In the current API schema, card creation identifies the cardholder through:

• person_id, when the card is issued directly to a person
• employee_id, when the card is issued to an employee linked under the related corporate_id

Where account setup uses corporate_id, card creation uses the linked employee_id, because the card is still issued to an individual employee rather than to the corporate record itself.

For the person and client naming used in the API reference, see Definitions.

For the meaning of external_id, see Definitions.

Card

The card record is the payment instrument used for transactions.

A card is created within the required account and setup structure, and issued to the relevant cardholder record.

In card endpoints, the card is identified by token_id.

A card has both:

• a status for operational usability
• a stage for physical fulfillment state

These are separate card attributes and should be handled separately.

Transaction records

Authorization

The authorization record represents a real-time authorization message, including transaction authorization requests and authorization reversals depending on the authorization type.

This is an operational decision point rather than a final financial posting.

Transaction

The transaction record represents the posted financial event used for clearing, posting, and reconciliation.

For lifecycle sequencing, use Transaction lifecycle.

Relationship model

The following conceptual model shows how the main records connect across record setup, card issuance, and transaction processing.

Use this diagram as a relationship map rather than as a strict field-by-field contract. The API Reference remains the source of truth for exact schemas and payload formats.

At a high level:

• account and related setup records define how the card is funded and organized
• employee or person records define who the card is issued to
• product and card records define the issuance setup and payment instrument
• authorization and transaction records represent the transaction lifecycle
• delivery details are part of the card-creation payload and become operationally relevant for physical fulfillment

Common relationship patterns

Common relationship patterns include:

• the account sits under a corporate, and the card is issued to an employee
• the account sits under a person, and the card is issued to that same person

One agreed setup may use one or both patterns, depending on the product and customer structure.