Get Card Token

get/api/card-tokens/{cardTokenId}

Retrieves a card token: an Apple Pay, Google Pay, or Samsung Pay device token, or a merchant card-on-file token.

Request

Path Parameters

cardTokenIdstringrequired
Card token identifier.

Response

Successful operation.

Body application/json

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.

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/card-tokens/{cardTokenId}' \
  --header 'Authorization: Bearer <access-token>'

Example Response

{
  "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"
}

{
  "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"
}