Skip to main content

Simulate Digital Wallet Token Provisioning

Overview​

When an account holder adds a payment card to a digital wallet such as Apple Pay or Google Pay, a digital wallet token is created. This token is a substitute for the card's primary account number (PAN) and is used for transactions instead of the real card number.

In production, token provisioning is initiated by the account holder through their wallet app. In the Test environment, you can use the Highnote simulation to replicate this flow and verify your integration handles token lifecycle events correctly.

The simulation walks through two steps:

  1. Generate a digital wallet token — creates a token in REQUESTED status
  2. Activate the token — transitions the token from REQUESTED to ACTIVE

Prerequisites​

Generate a digital wallet token​

test with dummy data

Do not enter production data in the Test environment. The Highnote Test environment is for exploring features and training. Use only dummy or test data.

Generating a digital wallet token requires using the following SimulateCardDigitalWalletTokenActivation mutation. This mutation creates a digital wallet token with a status of REQUESTED.

The SimulateCardDigitalWalletTokenActivationInput accepts the following optional fields:

  • requesterIdentifier — ID assigned to the token requester by the network. Defaults to Google Pay.
  • tokenType — Digital wallet token type. Defaults to DEVICE_SECURE_ELEMENT.
  • sourceEntryMethod — Method by which the card was added to the digital wallet. Defaults to MANUAL_ENTRY.
SimulateCardDigitalWalletTokenActivation​
Query
mutation SimulateCardDigitalWalletTokenActivation(
  $input: SimulateCardDigitalWalletTokenActivationInput!
) {
  simulateCardDigitalWalletTokenActivation(input: $input) {
    __typename
    ... on CardDigitalWalletToken {
      id
      createdAt
    }
    ... on UserError {
      errors {
        errorPath
        code
        description
      }
    }
    ... on AccessDeniedError {
      __typename
      message
    }
  }
}
Variables
{
  "input": {
    "paymentCardId": "cd_01",
    "requesterIdentifier": "11223344",
    "tokenType": "ECOMMERCE",
    "sourceEntryMethod": "CARD_ON_FILE"
  }
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
  "data": {
    "simulateCardDigitalWalletTokenActivation": {
      "__typename": "CardDigitalWalletToken",
      "id": "dw_01",
      "createdAt": null
    }
  },
  "extensions": {
    "requestId": "REQUEST_ID"
  }
}

Activate a digital wallet token​

Use the following SimulateCardDigitalWalletTokenActivated mutation to update a digital wallet token status from REQUESTED to ACTIVE:

SimulateCardDigitalWalletTokenActivated​
Query
mutation SimulateCardDigitalWalletTokenActivated(
  $input: SimulateCardDigitalWalletTokenActivatedInput!
) {
  simulateCardDigitalWalletTokenActivated(input: $input) {
    __typename
    ... on CardDigitalWalletToken {
      id
      createdAt
    }
    ... on UserError {
      errors {
        errorPath
        code
        description
      }
    }
    ... on AccessDeniedError {
      __typename
      message
    }
  }
}
Variables
{
  "input": {
    "cardDigitalWalletTokenId": "dw_01"
  }
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
  "data": {
    "simulateCardDigitalWalletTokenActivated": {
      "__typename": "CardDigitalWalletToken",
      "id": "dw_01",
      "createdAt": null
    }
  },
  "extensions": {
    "requestId": "REQUEST_ID"
  }
}

View token status and details​

Find the status of a token and its historical state transitions using the following query. The response includes the optional fields listed above, as well as:

  • last4 — The last four digits of the token primary account number (TPAN).
  • expirationDate — The exact date and time in UTC when the token expires.

These two fields are only returned for tokens that have been APPROVED or are in REQUESTED state awaiting identity verification.

FindCardDigitalWalletToken​
Query
query FindCardDigitalWalletToken($id: ID!) {
  node(id: $id) {
    ... on CardDigitalWalletToken {
      __typename
      id
      status
      createdAt
      updatedAt
      requesterName
      requesterIdentifier
      tokenType
      sourceEntryMethod
      last4
      expirationDate
      cardDigitalWalletTokenStateTransitions(first: 10) {
        edges {
          node {
            state
            reason
            createdAt
            updatedAt
          }
        }
      }
    }
  }
}
Variables
{
  "id": "dw_01"
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
  "data": {
    "node": {
      "__typename": "CardDigitalWalletToken",
      "id": "dw_01",
      "status": "TERMINATED",
      "createdAt": "2022-06-12T07:30:18.346Z",
      "updatedAt": "2022-06-12T07:34:20.424Z",
      "requesterName": "Google Pay",
      "requesterIdentifier": "11223344",
      "tokenType": "ECOMMERCE",
      "sourceEntryMethod": "CARD_ON_FILE",
      "last4": "8744",
      "expirationDate": "2028-01-31T23:59:59Z",
      "cardDigitalWalletTokenStateTransitions": {
        "edges": [
          {
            "node": {
              "state": "TERMINATED",
              "reason": "FRAUDULENT_TRANSACTIONS",
              "createdAt": "2022-06-12T07:34:20.420Z",
              "updatedAt": "2022-06-12T07:34:20.433Z"
            }
          },
          {
            "node": {
              "state": "ACTIVE",
              "reason": "NON_FRAUDULENT_TRANSACTIONS",
              "createdAt": "2022-06-12T07:32:41.818Z",
              "updatedAt": "2022-06-12T07:32:41.837Z"
            }
          },
          {
            "node": {
              "state": "SUSPENDED",
              "reason": "DEVICE_LOST",
              "createdAt": "2022-06-12T07:30:46.717Z",
              "updatedAt": "2022-06-12T07:30:46.753Z"
            }
          },
          {
            "node": {
              "state": "ACTIVE",
              "reason": null,
              "createdAt": "2022-06-12T07:30:34.446Z",
              "updatedAt": "2022-06-12T07:30:34.455Z"
            }
          },
          {
            "node": {
              "state": "REQUESTED",
              "reason": null,
              "createdAt": "2022-06-12T07:30:18.362Z",
              "updatedAt": "2022-06-12T07:30:18.729Z"
            }
          }
        ]
      }
    }
  },
  "extensions": {
    "requestId": "REQUEST_ID"
  }
}

Automate your integration​

To automate your integration, subscribe to digital wallet token status notification events.

The details provided in the payloads from digital wallet token status events can be used for the following use cases:

  • Automate your application or website's token provisioning workflows
  • Create account holder notifications and alerts
  • Create status views in your application or website