Manage the Card Lifecycle

After a card is issued and activated, day-to-day management covers four areas: updating the card's settings, changing the PIN, toggling between Active and On Hold, and understanding what operations require a support ticket rather than a direct API call.

The card's operational state machine

Only two transitions are possible via the published API:

stateDiagram-v2
    Active : Active (issuerCardStatus = 1)
    OnHold : On Hold (issuerCardStatus = 2)
    Closed : Closed (issuerCardStatus = 3)
    NotActivated : Not Activated (issuerCardStatus = 4)

    [*] --> NotActivated: Physical card issued
    [*] --> Active: Virtual card issued
    NotActivated --> Active: PUT /cards/{cardId}/activate
    Active --> OnHold: PUT /cards/{cardId}/status\nnewStatus = 2
    OnHold --> Active: PUT /cards/{cardId}/status\nnewStatus = 1
    Active --> Closed: Support ticket only
    OnHold --> Closed: Support ticket only

    note right of Closed
        Closed is a terminal state.
        It cannot be reversed and
        is not reachable via the API
        directly — raise a support ticket.
    end note

🚧
PUT /cards/{cardId}/status only accepts newStatus = 1 (Active) or newStatus = 2 (On Hold). It can only be called when the card's current issuerCardStatus is already 1 or 2. It will fail if called on a card in issuerCardStatus = 0 (Pending), 3 (Closed), or 4 (Not Activated).

Updating card settings

PUT /cards/{cardId}/update

This endpoint can be called at any time regardless of the card's status:

Field	Type	Constraints	Notes
`alias`	string	—	Update the card's display alias (e.g., "Travel Card", "Expenses Q3")
`transactionLimit`	integer	Decimal-implied; cannot exceed the cardholder's `transactionLimit`	Reduce or increase the card-level spending ceiling within the inherited limit
`callingCode`	string	1–3 digits	Zero-padded ITU dialing code for `cellNum`
`countryCallingCode`	string	2-char Alpha-2	Country code for `phoneNum`
`phoneNum`	string	10–20 digits	Card-level landline / alternate number
`cellNum`	string	10–20 digits	Card-level mobile number
`emailAdr`	string	6–50 chars	Card-level email address

All fields are optional — pass only those you want to update. The card-level contact details default to the cardholder's contact details if not set, and can be overridden here for per-card notification routing (useful for corporate expense-card scenarios).

Example: updating alias and transaction limit

{
  "alias": "EMEA Travel — Q3 2024",
  "transactionLimit": 150000
}

transactionLimit: 150000 = $1,500.00 in a USD-denominated Program.

Changing the PIN

PUT /cards/{cardId}/pin

PIN changes require the current PIN — this is a change operation, not a reset:

Field	Required	Type	Notes
`oldPIN`	Yes	string (4 digits)	The cardholder's current PIN
`newPIN`	Yes	string (4 digits)	The new PIN the cardholder wants to set

{
  "oldPIN": "1234",
  "newPIN": "5678"
}

❗️
There is no PIN reset endpoint. PUT /cards/{cardId}/pin requires the current oldPIN. If a cardholder has forgotten their PIN and cannot supply the old value, a PIN reset via alternative identity verification must be handled by raising a support ticket — see Raising & Managing Support Tickets.
The initial PIN is set at activation time via PUT /cards/{cardId}/activate. Virtual cards have no PIN and this endpoint does not apply to them.

Blocking and unblocking a card (Active ↔ On Hold)

PUT /cards/{cardId}/status

Toggle between Active and On Hold. This is the only status transition available via the API:

{ "newStatus": 2 }    // Block: Active → On Hold
{ "newStatus": 1 }    // Unblock: On Hold → Active

`newStatus`	Transition	Effect
`2` (On Hold)	Active → On Hold	Card is immediately blocked — all subsequent authorization attempts will be declined. In-flight authorized amounts are unaffected.
`1` (Active)	On Hold → Active	Card is immediately unblocked — authorization attempts proceed normally.

Common reasons to block (On Hold):

Cardholder suspects unauthorized use but wants to verify before reporting lost/stolen
Temporary suspension for compliance or risk management review
The cardholder is travelling and wants to pre-approve specific use windows

📘
On Hold is reversible; Closed is not. If a cardholder reports their card lost or stolen, or a fraudulent transaction is confirmed, the appropriate action is to raise a support ticket for permanent card closure and replacement — not to move the card to On Hold. Closing via the API is not supported. See Raising & Managing Support Tickets.

Checking status and balance

Two lightweight endpoints for status and balance checks:

GET /cards/{cardId}/status   → { "issuerCardStatus": 1 }
GET /cards/{cardId}/balance  → { "ledgerBalance": 50000, "availableBalance": 48500, "currency": 0 }

For the full card object including cryptoAddresses, contact details, and cardStatus/issuerCardStatus together, use GET /cards/{cardId}.

Operations that require a support ticket

The following card management operations have no direct API endpoint — raise a support ticket via POST /support/tickets with the relevant cardId:

Operation	Notes
Permanently close a card	There is no `DELETE /cards/{cardId}` or `issuerCardStatus = 3` transition via the API
Report a lost, stolen, or compromised card	Triggers card blocking, potential replacement, and may initiate a fraud investigation
Replace a card (lost/stolen/damaged)	New card issuance linked to the same cardholder
Report a fraudulent transaction	Include the `transId` and `cardId` in the ticket
Reset a forgotten PIN	Requires identity verification outside the API

For the full ticket process, see Raising & Managing Support Tickets.

The card's operational state machine

Updating card settings

Example: updating alias and transaction limit

Changing the PIN

Blocking and unblocking a card (Active ↔ On Hold)

Checking status and balance

Operations that require a support ticket

What's next