List Card Tokens

get/api/cards/{cardId}/tokens

Lists the device tokens on a card: Apple Pay, Google Pay, and Samsung Pay. Tokens are returned newest first by provisioningRequestedAt, and canceled tokens are included.

This API uses cursor-based pagination. Start by making a request without a cursor to get the first page. Use the nextCursor from the pageInfo in the response as the cursor for subsequent requests to retrieve further pages. Continue until nextCursor is undefined, indicating no more data.

Request

Path Parameters

cardIdstringrequired
ID of card

Query Parameters

limitintegerminimum: 1maximum: 100default: 50
Number of records to return, from 1 to 100.
cursorstring
Cursor to retrieve the next page of records.
requestorTypestringdefault: "device"
Allowed values:device
Type of token requestor to list tokens for. Defaults to device.

Response

Successful operation.

Body application/json

itemsobject[]
Items
- idstringrequired
  Card token identifier. Stable from the token's provisioning request onwards.
- cardobjectrequired
  The card the token is linked to. When the card is reissued, the token moves to the new card.
  idstringrequired
  Card identifier.
- requestorstringrequired
  The wallet or merchant that requested the token.
  This set is non-exhaustive and may grow over time, so consumers should tolerate unrecognized values. The current options are apple-pay, google-pay, samsung-pay, merchant, and other.
- statusstringrequired
  Allowed values:awaiting-approvalawaiting-verificationactivesuspendedcanceledapprovingsuspendingunsuspendingcanceling
  Token status.
  A token is awaiting-approval when the wallet tells the cardholder to contact the issuer to finish adding the card. Verify the cardholder, then call the Approve Card Token endpoint.
- deviceStatusstring
  Allowed values:presentremoved
  Whether the card is still on the device, as last reported to Immersve. Omitted for merchant tokens and canceled tokens.
- tokenSuffixstring
  Last four digits of the token's device primary account number (DPAN). Omitted until the card network reports it.
- descriptionstring
  Human-readable label for the token, such as the device name or the merchant description.
- provisioningRequestedAtstring<date-time>required
  Time the token was first requested.
pageInfoobject
Page info for paginated results, undefined if no page info
- nextCursorstring
  Cursor for next page, undefined if no more pages

Request fields are invalid.

Body application/json

statusCodeintegerrequired
statusNamestringrequired
errorCodestringrequired
errorsobject[]
Items
- messagestring
- pathstring
  The location of the invalid path param, query param or payload attribute.

No Authorization to access resource.

Body application/json

statusCodeintegerrequired
statusNamestringrequired
errorCodestringrequired
reasonstring

Example

Example Request

ServerAuthentication

curl 'https://api.immersve.com/api/cards/{cardId}/tokens' \
  --header 'Authorization: Bearer <access-token>'

Example Response

{
  "items": [
    {
      "id": "c7f3e2a1b4d94e8f9a0b1c2d3e4f5a6b",
      "card": {
        "id": "b11a6eac773cc13b9669f6bc0caba93a"
      },
      "requestor": "apple-pay",
      "status": "awaiting-approval",
      "deviceStatus": "present",
      "tokenSuffix": "7890",
      "description": "Maria's iPhone",
      "provisioningRequestedAt": "2026-10-15T02:11:40.000Z"
    }
  ],
  "pageInfo": {
    "nextCursor": "dGhlIG5leHQgY3Vyc29yIGdvZXMgaGVyZQ=="
  }
}

{
  "statusCode": 400,
  "statusName": "Bad Request",
  "errorCode": "INVALID_REQUEST_INPUT",
  "errors": [
    {
      "message": "Invalid type",
      "path": "items[1].attributes.invalidField"
    }
  ]
}

{
  "statusCode": 403,
  "statusName": "Forbidden",
  "errorCode": "FORBIDDEN",
  "reason": "Unauthorized"
}