Issuing cards

Cards and data

Issuing cards

Create the customer and account records, identify the individual cardholder, then call POST /v1/create-card. Save the returned token_id for later card operations and webhook linkage.

Choose the cardholder path

Person → Account → Card

Create the person through the client endpoint, including its required account object. Save person_id and your account mapping.
Supply that person_id and your FINCI-provided product_id to create the card.
Save the returned token_id against the person and account in your application.

Use person_id for both person-owned account setup and the cardholder reference.

Corporate → Account → Employee → Card

Create the corporate, including its required account object. Save corporate_id and your account mapping.
Create the employee under that corporate_id. Save employee_id.
Supply employee_id and your FINCI-provided product_id to create the card. Save the returned token_id against the employee and account.

The account belongs to the corporate; the card is issued to the employee. corporate_id is not a cardholder field in the create-card request.

These are record dependencies. Initial client and corporate requests include an account; they do not require a separate account call for that first account. Use the account endpoint for additional account setup where supported by your program.

Identifier	Where to use it
`person_id`	Personal account owner and personal cardholder.
`corporate_id`	Corporate account owner and parent of an employee.
`employee_id`	Cardholder on a corporate card request.
`product_id`	FINCI-provided product configuration for issuance.
`token_id`	Returned card identifier; use for card operations and matching webhook card activity.
`external_id`	Your mapping for a person, corporate or employee record.
`external_number`	Your numeric account reference, supplied during account setup: a string containing 6–20 digits.

See Core data model for the relationships and Card API for each setup endpoint.

Build the card request

Field	What to supply
`person_id` or `employee_id`	The existing individual cardholder for your chosen path. The card API defines each as a 20-digit string.
`product_id`	Product ID supplied by FINCI for the program; JSON integer.
`embossing_name`	Name to emboss, following the schema character rules; required string, 1–100 characters.
`expiration_date`	Required string in `YYYY-MM` format, using an expiration permitted for the product.
`token_status`	Required: `new` or `active`. `new` awaits activation; `active` enables use subject to transaction controls.
`token_stage`	Required: `digital` for digital issuance, or `plastic_not_delivered` to order the physical card with delivery pending. Status remains a separate field.
`delivery_address`	Required object, including on a digital-first request. Fields are `country`, `city`, `zip`, `address`, and optional additional line `address2`; follow the object schema and your delivery requirements.
`express_delivery`	Required string: `"true"` or `"false"`. Do not send a JSON boolean.

There is no account_id or corporate_id field on this request. Use the cardholder and existing account setup for the relevant path.

Complete request examples

These are fictional request templates. Replace the holder ID, product ID, name, expiration and address with your provisioned setup. Product 123 illustrates the integer type; it is not a provisioned FINCI product.

POST /v1/create-card

{
  "person_id": "99000000000000000101",
  "product_id": 123,
  "embossing_name": "Example Cardholder",
  "expiration_date": "2030-12",
  "token_status": "active",
  "token_stage": "digital",
  "delivery_address": {
    "country": "LV",
    "city": "Example City",
    "zip": "1000",
    "address": "Example Street 1"
  },
  "express_delivery": "false"
}

Save token_id from a successful response. An active digital card is eligible for use under its product and authorization controls.

POST /v1/create-card

{
  "employee_id": "99000000000000000201",
  "product_id": 123,
  "embossing_name": "Example Employee",
  "expiration_date": "2030-12",
  "token_status": "new",
  "token_stage": "plastic_not_delivered",
  "delivery_address": {
    "country": "LV",
    "city": "Example City",
    "zip": "1000",
    "address": "Example Street 2"
  },
  "express_delivery": "false"
}

The card is created in new status and the physical card is ordered through plastic_not_delivered. Delivery and activation are separate steps; activate through the supported status flow when appropriate for your product.

Select the initial state

Use case	`token_status`	`token_stage`	Result
Active digital issuance	`active`	`digital`	Eligible for digital use under the product and normal transaction controls.
Order a physical card	`active`	`plastic_not_delivered`	Physical card ordered, with delivery pending. Active status remains subject to normal transaction controls.
Activation required first	`new`	`digital` or `plastic_not_delivered`	Card exists and awaits activation.

For allowed create, read and update values, continue to Card state model.

After issuance

Save token_id exactly as returned. Link incoming webhook token_id to that card, then resolve its account entries using the configured account mapping. Implement authorization decisions and confirmations and presentment posting before enabling transaction activity.

Keep sensitive card data out of logs and examples. Retrieve, decrypt and display it only through the permitted product flow and security controls.

Core data model Card state model

Built with