Issuing and lifecycle

A card is issued inactive, then activated, paused, resumed, reported or closed. This page covers the issue request, the states, the PIN and how a lost card is replaced.

Issuing

POST /cards needs an Idempotency-Key of at most 200 characters. The answer is 201 with the card in status inactive, an expiry three years out and the default controls. The same key with the same terms returns the card again with 200. The same key with other terms is 409 conflict.

networkstringRequired

visa, mastercard or discover.

cardholder_customer_idstringRequired

The person who holds the card: a living person whose customer record is active and KYC-verified. A business cannot be the cardholder.

account_idstringDebit

The deposit account a debit card draws on. It must be open, in USD, free of a debit block, and not a certificate.

facility_idstringCredit

The revolving facility a credit card draws on. It must be active or delinquent. A debit card refuses this field.

kindstringOptional

debit, the default, or credit. A request with a facility_id and no account_id is read as credit.

formstringOptional

virtual, the default, or physical.

cardholder_authority_idstringSometimes

Needed when the cardholder does not own the account: an approved, unexpired cardholder authority that one staff member proposed and another reviewed.

A cardholder who is not eligible is 409 conflict. The same check runs again on activation, on resume and on every authorization.

States

Action	From	To
`POST /cards/{id}/activate`	`inactive`, `paused`	`active`
`POST /cards/{id}/pause`	`active`	`paused`
`POST /cards/{id}/resume`	`paused`	`active`
`POST /cards/{id}/close`	`inactive`, `active`, `paused`	`closed`
`POST /cards/{id}/report`	`inactive`, `active`, `paused`	`lost` or `stolen`

An action the current state does not allow is 422 cards.card_not_active. An action whose target state already holds returns the card unchanged. Nothing returns a lost, stolen or closed card to use. Each change publishes cards.card.issued, cards.card.active, cards.card.paused, cards.card.closed, cards.card.lost or cards.card.stolen.

The report body is {"status": "lost"} or {"status": "stolen"}. With an Idempotency-Key the report is recorded, and the same key returns the recorded card.

POST /cards/{id}/pin sets or changes a PIN from a PIN block that a PIN pad enciphered under a bank zone PIN key. The API never takes or returns a clear PIN. Send zone_key_index (two digits), pin_block_format (ISO-0, ISO-1, ISO-3 or ISO-4) and pin_block in hexadecimal. A change also carries current_pin_block. method is ibm3624_offset, the default, or visa_pvv.

The caller is staff with cards:security:write and a step-up within five minutes. cards:write does not reach this route.
A PIN the selection policy refuses, such as a trivial sequence, is 400 validation_failed.
A wrong current PIN is 422 cards.pin_incorrect. After three wrong PINs in a row the record is locked and the answer is cards.pin_tries_exceeded until staff reset the try counter.
GET /cards/{id}/pin returns the record without the value: status (set or locked), tries and try_limit.

The holder of a physical card ordered with pin_method pin_set can instead open a PIN-set session and complete the PIN with the bureau's PIN service.

Replacing a card

Send POST /cards/production/orders with kind replacement, a reason of lost, stolen, damaged or compromised, and a pin_method of mailer or pin_set. A lost or stolen replacement is refused with 409 until the card has been reported in that status. The order creates a successor card on the same account, with the same cardholder, network, kind and controls. The successor gets a new number unless the reason is damaged. It can be activated once the bureau reports the order shipped, and activating it closes a predecessor that is still inactive, active or paused. Orders need cards:production:write, and only physical cards are produced. Replace a virtual card by issuing a new one.

Network tokens

Issuer network tokenization runs against token service simulators and stays off until it is configured. GET /cards/network-tokens/tokens lists a card's tokens. Moving a card's live tokens to its replacement is a proposal that a second staff member approves.