Skip to main content

Manage physical cards

You manage physical cards with the same APIs as virtual cards. Physical cards also have extra lifecycle steps, such as activation and renewal. This page covers:

Card lifecycle​

ActionAPI
CreatePOST /v1/pba/provision
ActivatePOST /v1/pba/static/{id}/activate
Lock / UnlockPATCH /v1/pba/static/{id}
RenewPOST /v1/pba/static/{id}/renew
DeleteDELETE /v1/pba/static/{id}

A card must be locked before it can be deleted. A card that hasn't been activated yet can also be locked, so you can delete a card the cardholder never received. A locked card stays locked when it is activated. A renewal is applied when the renewed card is activated.

As with virtual cards, there is no separate expired status. The card's expiry date is returned in fpan_expiry.

List all physical cards​

Use the List cards API with type set to physical_card. Pass either tenant_customer_ref or tenant_account_ref to select the customer.

Sample Request
/v1/pba/static?type=physical_card&tenant_customer_ref=customer-00000000000001
Sample Response
{
"data": [
{
"id": "4fbc4775-466c-4d21-bb8c-95f3ef9ffbea",
"tenant_account_ref": "FR00000000000001",
"tenant_customer_ref": "customer-00000000000001",
"tenant_token_ref": "TOK000000000000001",
"account_id": "c6045eed-b5cb-48f0-8321-b924a8e8f808",
"customer_id": "5b3aae19-16b5-4aca-81b5-5d72a168c496",
"type": "physical_card",
"provisioning_status": "completed",
"fpan_redacted_number": "512*********9708",
"fpan_expiry": {
"month": "11",
"year": "29"
},
"instrument": "manual_card_entry",
"status": "active",
"locked": false,
"card_program_id": "3c1e7a52-8f4b-4d2a-9e6f-1b2c3d4e5f60",
"physical_card": {
"printed_name": "JANE DOE",
"fulfilment_status": "created"
},
"created_at": "2026-03-16T07:39:09.317Z",
"updated_at": "2026-03-20T09:12:44.102Z"
}
]
}

To list all cards of a customer, virtual and physical, leave out type.

Get details of a physical card​

Use the Get card API to get the details of a physical card. Physical card responses include a physical_card object with the printed name, shipping address, fulfilment status and any pending renewal.

Sample Request
/v1/pba/static/4fbc4775-466c-4d21-bb8c-95f3ef9ffbea
Sample Response
{
"id": "4fbc4775-466c-4d21-bb8c-95f3ef9ffbea",
"tenant_account_ref": "FR00000000000001",
"tenant_customer_ref": "customer-00000000000001",
"tenant_token_ref": "TOK000000000000001",
"account_id": "c6045eed-b5cb-48f0-8321-b924a8e8f808",
"customer_id": "5b3aae19-16b5-4aca-81b5-5d72a168c496",
"type": "physical_card",
"provisioning_status": "completed",
"fpan_redacted_number": "512*********9708",
"fpan_expiry": {
"month": "11",
"year": "29"
},
"status": "inactive",
"locked": false,
"physical_card": {
"printed_name": "JANE DOE",
"shipping_address": {
"line1": "1 Raffles Place",
"city": "Singapore",
"postal_code": "048616",
"country_code": "SG"
},
"fulfilment_status": "created"
},
"created_at": "2026-03-16T07:39:09.317Z",
"updated_at": "2026-03-16T07:39:09.317Z"
}

Activating a physical card​

Physical cards are created with status inactive and are never activated automatically. Once the cardholder has received the card, call the Activate physical card API to make it usable.

Sample Request
POST /v1/pba/static/4fbc4775-466c-4d21-bb8c-95f3ef9ffbea/activate
  • The card can only be activated once issuance has finished (provisioning_status = completed). Otherwise the API returns 409 physical_card_not_activatable.
  • If a renewal is pending, it is applied when the card is activated, and fpan_expiry is updated.
  • A locked card can be activated. It stays locked after activation.
  • Activating a card that is already active returns 200 and changes nothing.
tip

We recommend asking the cardholder to confirm something only they know before you activate the card, for example the last 4 digits of the card or a one-time password in your app.

Locking/Unlocking a physical card​

Use the Update card API to temporarily lock or unlock a physical card, for example when the cardholder has misplaced it. You receive a v1:card:locked or v1:card:unlocked notification when the lock changes.

A card that hasn't been activated yet can also be locked. The Update card API and the Card SDK change the same lock, so a card locked in your app shows as locked in the API, and the other way round.

Sample Request
/v1/pba/static/4fbc4775-466c-4d21-bb8c-95f3ef9ffbea
{
"lock_status": "locked"
}

Renewing an expiring card​

Before a physical card expires, a renewed card with a new expiry date (and the same card number) must be produced and shipped to the cardholder. Use the Renew physical card API to record the new expiry date. Open Fabric then sends the renewed card for production, the same as a new card.

Cards are not renewed automatically. Call the Renew API for each card before it expires.

Sample Request
POST /v1/pba/static/4fbc4775-466c-4d21-bb8c-95f3ef9ffbea/renew
{
"expiry_month": "11",
"expiry_year": "32"
}

The new expiry date is not applied right away. It is stored as physical_card.pending_renewal, and the current card keeps working. When the cardholder receives the renewed card, activate it to apply the new expiry date.

note

Only active cards can be renewed. Renewing a card that isn't active returns 400. Only one renewal can be pending at a time. If a renewal is already pending, or the card has been deactivated, the API returns 409.

Replacing a lost, stolen or damaged card​

There is no separate replacement API. To replace a lost, stolen or damaged card, close the old card and issue a new one with the existing APIs:

  1. Lock the old card right away, so it can't be used.
  2. Delete the old card with a reason_code that matches the situation, e.g. device_lost, device_stolen or suspected_fraud. Use other for a damaged card.
  3. Create a new physical card for the same customer and account. The new card has a new card number, expiry date and CVV, and is sent to your personalization bureau for production.
  4. Activate the new card once the cardholder has received it.
tip

If the cardholder only misplaced the card, lock it instead of deleting it. You can unlock it if the card is found.

Deleting a physical card​

Use the Delete card API to permanently deactivate a physical card. This cannot be undone. You must lock the card before you can delete it.

Sample Request
/v1/pba/static/4fbc4775-466c-4d21-bb8c-95f3ef9ffbea
{
"reason_text": "Customer closed their account",
"reason_code": "other"
}

Lifecycle notifications​

Open Fabric sends webhook notifications when a card's lifecycle changes, for physical and virtual cards. Every card notification includes form_factor, so you can tell physical cards (physical) apart from virtual cards (virtual).

EventDescription
v1:card:createdA card has been created. Status is inactive for a physical card and active for a virtual card.
v1:card:activatedThe card has been activated and can be used.
v1:card:updatedThe card's expiry date has changed, for example after a renewal.
v1:card:lockedThe card has been locked. Includes status_reason_code with the reason, if one was provided.
v1:card:unlockedThe card has been unlocked.
v1:card:deactivatedThe card has been closed. Includes status_reason_code with the reason, if one was provided.
v1:card:pin:lockedThe card's PIN has been locked, e.g. after too many wrong PIN attempts.
v1:card:pin:unlockedThe card's PIN has been unlocked.

See Notifications for how to receive webhooks, and the Card Lifecycle Notifications API reference for the full payloads.