Issue Cards to Embedded Devices

Overview

After you issue a virtual payment card, your cardholder can load it onto an embedded device, such as a wristband, for contactless payments. Embedded devices are personalized through a Highnote-certified personalization vendor.

Your personalization vendor retrieves the card details from the Highnote API, prepares the personalization data, and delivers it to the cardholder's device through your application. After successful personalization, you register the order with the Highnote platform.

Prerequisites

• A Highnote account
• An API key or the API Explorer
• A Highnote virtual card
• A card product configured for embedded devices (for example, the WRISTBAND form factor)
• A Highnote-certified personalization vendor.

Contact your Highnote representative for a list of Highnote-certified personalization vendors.

How it works

The following steps outline the embedded device personalization workflow:

1. You, the subscriber, issue a virtual payment card for the cardholder.
2. The cardholder opens your application and selects an embedded device such as a wristband.
3. Your application sends the device serial number and the Highnote payment card ID (cd_) to the personalization vendor.
4. The vendor retrieves the card details, including restricted details, using the Highnote API. See Retrieve card details for personalization.
5. The vendor calls createExternalPhysicalPaymentCardOrder to register the order in Highnote's system. See Create external physical card order.
6. The vendor prepares the personalization data, encrypted for the device serial number.
7. The cardholder taps the device to an NFC-enabled phone to personalize it through your application.

Results:

• On success, you call completeExternalPhysicalPaymentCardOrder to mark the order complete. See Complete external physical card order.
• On failure, you call closePaymentCard to terminate the card. The cardholder must start the process again with a new virtual card.

Retrieve card details for personalization

Vendor action: This step is performed by your personalization vendor, not your application.

Your personalization vendor uses a node query with the payment card ID to retrieve the card details needed for personalization. The query includes the restrictedDetails field, which returns the full card number and CVV.

FindPaymentCard

Query

query FindPaymentCard($id: ID!) {
  node(id: $id) {
    ... on PaymentCard {
      id
      bin
      last4
      expirationDate
      network
      status
      formFactor
      restrictedDetails {
        ... on PaymentCardRestrictedDetails {
          cvv
          number
        }
      }
    }
  }
}

Variables

{
  "id": "cd_6f1a35648d7840959da75df91e292c34"
}

⚠️ Please login to execute queries. Visit the dashboard to authenticate.

Result

{
  "data": {
    "node": {
      "id": "cd_6f1a35648d7840959da75df91e292c34",
      "bin": "547203",
      "last4": "9174",
      "expirationDate": "2026-01-01T23:59:59Z",
      "network": "MASTERCARD",
      "status": "ACTIVE",
      "formFactor": "WRISTBAND",
      "restrictedDetails": {
        "cvv": "714",
        "number": "5472XXXXXXXX9174"
      }
    }
  }
}

Create external physical card order

Vendor action: This step is performed by your personalization vendor, not your application.

The vendor calls the createExternalPhysicalPaymentCardOrder mutation to register the order in Highnote's system. This mutation logs the payment card order and associates the embedded device details with the payment card.

The mutation requires the following input:

Field	Data type	Description
paymentCardId	String	The ID of the Highnote payment card with prefix cd_
idempotencyKey	String	A unique key (e.g., UUIDv4) to prevent duplicate requests. 5–255 characters.
embeddedDevice (optional)	Object	The embedded device details. Contains the fields below.
embeddedDevice.image	String	URL to an image of the embedded device
embeddedDevice.name	String	Descriptor assigned to the embedded device by the user or application
embeddedDevice.serialNumber	String	Alphanumeric unique designator for the embedded device
embeddedDevice.variant	String	A free-form field for additional information about the embedded device

CreateExternalPhysicalPaymentCardOrder

Query

mutation createExternalPhysicalPaymentCardOrder(
  $input: CreateExternalPhysicalPaymentCardOrderInput!
) {
  createExternalPhysicalPaymentCardOrder(input: $input) {
    ... on ExternalPhysicalPaymentCardOrder {
      id
      status
      paymentCard {
        id
        bin
        last4
        expirationDate
        network
        status
      }
      embeddedDevice {
        formFactor
        image
        name
        serialNumber
        variant
      }
    }
    ... on UserError {
      errors {
        errorPath
        code
      }
    }
  }
}

Variables

{
  "input": {
    "paymentCardId": "cd_b253ee020d2f4a01b613d5137bc4b14d",
    "embeddedDevice": {
      "image": "https://example.com/device-image.png",
      "name": "MyDevice",
      "serialNumber": "123abc",
      "variant": "Plastic"
    }
  }
}

⚠️ Please login to execute queries. Visit the dashboard to authenticate.

Result

{
  "data": {
    "createExternalPhysicalPaymentCardOrder": {
      "id": "ffext_227c8ef9d7037e4c26b87471cc10865cc1",
      "status": "NEW",
      "paymentCard": {
        "id": "cd_b253ee020d2f4a01b613d5137bc4b14d",
        "bin": "547203",
        "last4": "9232",
        "expirationDate": "2026-01-01T23:59:59Z",
        "network": "MASTERCARD",
        "status": "ACTIVE"
      },
      "embeddedDevice": {
        "formFactor": "WRISTBAND",
        "image": "https://example.com/device-image.png",
        "name": "MyDevice",
        "serialNumber": "123abc",
        "variant": "Plastic"
      }
    }
  }
}

Complete external physical card order

Subscriber action: This step is performed by your application.

After the cardholder successfully personalizes the embedded device, call the completeExternalPhysicalPaymentCardOrder mutation to mark the order as COMPLETED. This confirms that the device is ready for contactless payments.

CompleteExternalPhysicalPaymentCardOrder

Query

mutation completeExternalPhysicalPaymentCardOrder(
  $input: CompleteExternalPhysicalPaymentCardOrderInput!
) {
  completeExternalPhysicalPaymentCardOrder(input: $input) {
    ... on ExternalPhysicalPaymentCardOrder {
      id
      status
      paymentCard {
        id
        bin
        last4
        expirationDate
        network
        status
      }
      embeddedDevice {
        formFactor
        image
        name
        serialNumber
        variant
      }
    }
    ... on UserError {
      errors {
        code
      }
    }
  }
}

Variables

{
  "input": {
    "externalPhysicalPaymentCardOrderId": "ffext_1a4b2c1b3c5748279654c45e6181a7d7"
  }
}

⚠️ Please login to execute queries. Visit the dashboard to authenticate.

Result

{
  "data": {
    "completeExternalPhysicalPaymentCardOrder": {
      "id": "ffext_1a4b2c1b3c5748279654c45e6181a7d7",
      "status": "COMPLETED",
      "paymentCard": {
        "id": "cd_4643d1f06b6717a081f7ee79f4d2fab8",
        "bin": "547203",
        "last4": "5856",
        "expirationDate": "2026-01-01T23:59:59Z",
        "network": "MASTERCARD",
        "status": "ACTIVE"
      },
      "embeddedDevice": {
        "formFactor": "WRISTBAND",
        "image": "https://example.com/device-image.png",
        "name": "MyDevice",
        "serialNumber": "123abc",
        "variant": "Plastic"
      }
    }
  }
}

Handle personalization failures

Subscriber action: This step is performed by your application.

If device personalization fails, the payment card should be terminated to prevent unauthorized use. Call the closePaymentCard mutation to close the card. The cardholder must issue a new virtual card and restart the personalization process.

Do not call createExternalPhysicalPaymentCardOrder for failed personalizations.

Query embedded device cards

Use the following query to find details from an external physical card order for a specific payment card, including the embedded device information:

FindPaymentCard

Query

query FindPaymentCard($id: ID!) {
  node(id: $id) {
    ... on PaymentCard {
      id
      bin
      last4
      expirationDate
      network
      status
      formFactor
      externalPhysicalPaymentCardOrders {
        id
        embeddedDevice {
          formFactor
          image
          name
          serialNumber
          variant
        }
      }
    }
  }
}

Variables

{
  "id": "cd_6f1a35648d7840959da75df91e292c34"
}

⚠️ Please login to execute queries. Visit the dashboard to authenticate.

Result

{
  "data": {
    "node": {
      "id": "cd_6f1a35648d7840959da75df91e292c34",
      "bin": "547203",
      "last4": "9174",
      "expirationDate": "2026-01-01T23:59:59Z",
      "network": "MASTERCARD",
      "status": "ACTIVE",
      "formFactor": "PHYSICAL",
      "externalPhysicalPaymentCardOrders": [
        {
          "id": "ffext_227c8ef9d7037e4c26b87471cc10865cc1",
          "embeddedDevice": {
            "formFactor": "WRISTBAND",
            "image": "https://example.com/device-image.png",
            "name": "MyDevice",
            "serialNumber": "123abc",
            "variant": "Plastic"
          }
        }
      ]
    }
  },
  "extensions": {
    "requestId": "3a31dd25-aa8d-9b58-9393-64b8da6450c0",
    "rateLimit": {
      "cost": 2,
      "limit": 60060,
      "remaining": 60056
    }
  }
}