Skip to main content

Manage virtual cards

You can use our APIs to manage your portfolio of virtual cards. In this section, we will cover:

  • List all virtual cards belonging to a customer
  • Get details of a virtual card
  • Locking/Unlocking a virtual card
  • Deleting a virtual card

List all virtual cards​

The List virtual cards API can be used to list all virtual cards belonging to a customer.

Please set the instrument to manual_card_entry and add either the tenant_customer_ref or tenant_account_ref to specify the customer.

warning

This API can also be used to list all virtual cards of all customers (by omitting both tenant_customer_ref and tenant_account_ref in the request parameters). This kind of query should only be used in extreme scenarios.

Sample Request
/v1/pba/static?tenant_customer_ref=customer-00000000000001
Sample Response
{
  "metadata": {
    "page": 1,
    "page_size": 10,
    "total_pages": 1,
    "total": 1
  }
  "data": [
  {
    "id": "c2319421-f0e8-4dd6-a099-124c5a3c6592",
    "customer_id": "24ae8cd0-301d-4b2b-807b-09683f334bdd",
    "instrument": "manual_card_entry",
    "locked": false,
    "status": "active",
    "tenant_account_ref": "FR00000000000001",
    "tenant_customer_ref": "customer-00000000000001",
    "tenant_token_ref": "TOK000000000000001",
    "tsp_token_ref": "DSHRMC1PH0000000038d38f98a6a45b7863199720778380e",
    "account_id": "436605a1-271d-49a7-80f0-bcaf095cdd6a",
    "dpan_redacted_number": "512*********9708",
    "dpan_expiry": { "year": "25", "month": "08"},
    "fpan_redacted_number": "512*********1234",
    "fpan_expiry": { "year": "25", "month": "08"},
    "created_at": "2024-03-20T14:05:14.711+08:00",
    "updated_at": "2024-03-20T14:05:14.711+08:00"
  }
  ]  
}

Get details of a virtual card​

The Get virtual card API can be used to get details of a specific virtual card.

Sample Request
/v1/pba/static/c2319421-f0e8-4dd6-a099-124c5a3c6592
Sample Response
{
    "id": "c2319421-f0e8-4dd6-a099-124c5a3c6592",
    "customer_id": "24ae8cd0-301d-4b2b-807b-09683f334bdd",
    "instrument": "manual_card_entry",
    "locked": false,
    "status": "active",
    "tenant_account_ref": "FR00000000000001",
    "tenant_customer_ref": "customer-00000000000001",
    "tenant_token_ref": "TOK000000000000001",
    "tsp_token_ref": "DSHRMC1PH0000000038d38f98a6a45b7863199720778380e",
    "account_id": "436605a1-271d-49a7-80f0-bcaf095cdd6a",
    "dpan_redacted_number": "512*********9708",
    "dpan_expiry": { "year": "25", "month": "08"},
    "fpan_redacted_number": "512*********1234",
    "fpan_expiry": { "year": "25", "month": "08"},
    "created_at": "2024-03-20T14:05:14.711+08:00",
    "updated_at": "2024-03-20T14:05:14.711+08:00"
}

Locking/Unlocking a virtual card​

The Update virtual card API can be used to lock/unlock a specific virtual card.

Sample Request
/v1/pba/static/c2319421-f0e8-4dd6-a099-124c5a3c6592
{
  "lock_status": "locked"
}
Sample Response
{
    "id": "c2319421-f0e8-4dd6-a099-124c5a3c6592",
    "customer_id": "24ae8cd0-301d-4b2b-807b-09683f334bdd",
    "instrument": "manual_card_entry",
    "locked": true,
    "status": "active",
    "tenant_account_ref": "FR00000000000001",
    "tenant_customer_ref": "customer-00000000000001",
    "tenant_token_ref": "TOK000000000000001",
    "tsp_token_ref": "DSHRMC1PH0000000038d38f98a6a45b7863199720778380e",
    "account_id": "436605a1-271d-49a7-80f0-bcaf095cdd6a",
    "dpan_redacted_number": "512*********9708",
    "dpan_expiry": { "year": "25", "month": "08"},
    "fpan_redacted_number": "512*********1234",
    "fpan_expiry": { "year": "25", "month": "08"},
    "created_at": "2024-03-20T14:05:14.711+08:00",
    "updated_at": "2024-03-20T15:04:23.622+08:00"
}

Deleting a virtual card​

The Delete virtual card API can be used to deactivate a specific virtual card. This action is permanent (cannot be undone) and requires the virtual card to be locked first (see above) before deleting.

Sample Request
/v1/pba/static/c2319421-f0e8-4dd6-a099-124c5a3c6592
{
  "reason_text": "customer reported device is lost",
  "reason_code": "device_lost"
}
Sample Response
{
    "id": "c2319421-f0e8-4dd6-a099-124c5a3c6592",
    "customer_id": "24ae8cd0-301d-4b2b-807b-09683f334bdd",
    "instrument": "manual_card_entry",
    "locked": true,
    "status": "deactivated",
    "tenant_account_ref": "FR00000000000001",
    "tenant_customer_ref": "customer-00000000000001",
    "tenant_token_ref": "TOK000000000000001",
    "tsp_token_ref": "DSHRMC1PH0000000038d38f98a6a45b7863199720778380e",
    "account_id": "436605a1-271d-49a7-80f0-bcaf095cdd6a",
    "dpan_redacted_number": "512*********9708",
    "dpan_expiry": { "year": "25", "month": "08"},
    "fpan_redacted_number": "512*********1234",
    "fpan_expiry": { "year": "25", "month": "08"},
    "created_at": "2024-03-20T14:05:14.711+08:00",
    "updated_at": "2024-03-20T15:13:32.533+08:00"
}