Core data model
FINCI records connect the customer, funding account, individual cardholder and card. Webhooks then connect authorization activity and clearing to that card. Keep setup identifiers and transaction identifiers in separate fields.
Setup records at a glance
| Record | Purpose and identifier |
|---|---|
Person | Individual customer. Use person_id for personal account setup and personal card issuance; keep external_id for your own mapping. Person operations use client endpoint names in the API. |
Corporate | Company customer. Use corporate_id for the corporate account and its employee records; keep external_id for your own mapping. |
Account | Funding and currency context. Account setup uses person_id or corporate_id; your numeric-string reference is external_number. The Account response exposes external_number and currency_code. |
Employee | Individual cardholder under a corporate. Use its employee_id when creating the corporate card. |
Product | Issuance configuration provided by FINCI. Use the provisioned integer product_id. |
Card | Payment instrument issued within the account setup. Use returned token_id for card operations and webhook card linkage. Store status and stage separately. |
For the first account, both initial client and corporate requests include a required account object. The relationship order below describes dependencies, not one API call per box. Follow Issuing cards for the request sequence.
Transaction records at a glance
| Record or reference | What it identifies |
|---|---|
Authorization id | Identifier of the authorization record. Its decision request and outcome confirmation share this ID. |
Reversal id | Identifier of the reversal itself, sent on the authorization webhook with authtype: "Reversal". Keep this separately from the authorization it reverses. |
original_authorization_id | Earlier authorization referenced by a related authorization, advice or reversal. The related message has its own id. |
original_authorization_nrn | Earlier authorization's nrn where this original reference is supplied. |
Presentment id | A distinct financial event to post once. Usually one presentment relates to an approval; several can occur rarely. The first matched presentment releases the full hold. |
Presentment authorization_id | Authorization referenced by that clearing. It can identify a related authorization or a return authorization; it can also be empty. |
Local account entry | accounts_local[].account_id plus currency in the configured card/account mapping. Account identity and authorization linkage are separate checks. |
Preserve numeric IDs losslessly and string references exactly. Webhook IDs can exceed JavaScript's safe integer range; converting to Number can break matching. token_id is a string, not a UUID in these examples.
See decision versus confirmation for the authorization phases, and Webhook amounts for the local hold and posting values.
Relationship model
The model connects the account owner, cardholder, card and its funding account, then the authorization and presentment records. The card/account relationship comes from the configured account mapping; the create-card request has no account_id field.
Personal setup: person_id identifies the account owner and cardholder. Corporate setup: corporate_id links the account and employee; employee_id identifies the cardholder. Webhook token_id identifies the card; presentment authorization_id links a clearing to an authorization.
Select personal setup, corporate setup, transaction links, related authorizations, or reversal links. Select a field or the funding-account link to follow the relationship. The API Reference defines the full request and response schemas.
external_id maps a person, corporate or employee to your own records. The Account response exposes external_number and currency_code; resolve webhook accounts_local[].account_id through the program’s configured card/account mapping. It is not a global customer-account key.
Authorization and reversal links
| Message | Link to keep |
|---|---|
Outcome confirmation | The same authorization id; response_code supplies the outcome. |
Related authorization or advice | Its own id, plus original_authorization_id referencing the earlier authorization. original_authorization_nrn references the earlier authorization's nrn when supplied. |
Reversal | Keep its own id and authtype: "Reversal".Match original_authorization_id to the earlier authorization's id; if empty, match original_authorization_nrn to its nrn.Only when both references are empty, use a supported unique rrn match in the same card/account context. |
Presentment | Its own id, plus authorization_id referencing the authorization where supplied. |
Read the three fields separately: advice: true identifies an authorization advice message; response_code reports the outcome; original_authorization_id links the earlier authorization. The EUR 0.40 example is an additional authorization with advice: false, not an advice. The amount-update example is an advice with advice: true. Use the configured flow rule to interpret an increment or replacement total. See matching rules.
The reversal uses id for its own identifier; there is no separate reversal_id field. The reversal's id is not the ID of the earlier approval. Keep unresolved or conflicting original references for reconciliation.
The model uses the following complete message flows:
Complete messages: additional authorization
Download these complete messages (JSON)
Identifiers, merchant names, approval codes, dates and locations are fictional. Financial values, field types and references are preserved.
Complete messages: authorization amount update
Download these complete messages (JSON)
Identifiers, merchant names, approval codes, dates and locations are fictional. Financial values, field types and references are preserved.
Complete messages: partial reversal
Download these complete messages (JSON)
Identifiers, merchant names, approval codes, dates and locations are fictional. Financial values, field types and references are preserved.