Home / Issuing / Issue Cards

Print Physical Cards

Prerequisites

  1. A Highnote account
  2. An API key or the API Explorer
  3. A virtual card

Overview

Note: This guide provides an overview of printing personalized physical cards using the Highnote API. For instructions on printing physical cards using the dashboard, see Order physical cards.

After you issue a virtual card, you can order physical cards for eligible, multi-use card products. The Highnote platform supports two kinds of physical cards:

  • Personalized physical cards: Payment cards that are personalized for the account holder
  • Preprinted physical cards: Generic cards that are not personalized for the account holder

This guide provides an overview of printing personalized physical cards. For an overview of preprinted cards, see Issue Preprinted Physical Cards.

Individual card orders

Individual physical card orders allow you to print a single physical card. Physical card orders are:

  • Packaged with a card carrier
  • Shipped to a single location
  • Not connected to other orders at any time in the physical card order lifecycle

Individual physical card orders are the most common order type across card products. For example, when issuing a card to a single account holder for a consumer debit product, you will use this order type.

Group card orders

Group physical card orders allow you to request several physical cards at once. Note the following about group physical card orders:

  • Packaged individually with a card carrier
  • Shipped in bulk as a single shipment to one location

Group physical card orders are essentially a set of individual card orders that are packaged into a single shipment during the last step of the physical card order lifecycle. For information on group card orders, see Print Cards in Bulk.

Card personalization

Card personalization is dynamic information printed on a physical card that is unique to the cardholder. Line 1 and Line 2 represent the card personalization on a payment card:

  • Line 1 is required and used for the cardholder's name. Examples of cardholders include account holders and authorized users.
  • Line 2 is optional and can be used for any additional information. For example, a business account holder may use line 2 for the business name.

Card order lifecycle

Warning: You can't cancel a card order after it has been sent to the printer.

The following graphic shows the standard card order lifecycle, beginning with an order for a physical card and ending with a shipment received by the account holder: fulfillment-process.svg

Each step in the card order lifecycle corresponds with a status. Refer to the following table for a description of each status in the card order lifecycle:

StatusDescription
NEWA request for a physical card has been made. This is the only stage at which an order may be canceled.
PENDINGThe group order is ready to ship but has not yet been sent to the printer. This status is only applicable to group orders.
SENT_TO_PRINTERThe order has successfully been sent to the printer.
APPROVEDThe printer has approved the order.
SHIPPEDThe order has been shipped. All shipment methods besides USPS Ground return a tracking number.
CANCELEDYou requested to cancel the order.
SHIP_FAILEDThe order failed to reach the account holder. Failed orders are returned to the return address on file.

Fulfillment

Highnote sends physical card fulfillment requests to the printer several times a day. The following fulfillment options are available as requestedShipDate input variables:

  • Select a custom shipping date in the future, in YYYY-MM-DD format
  • Select SHIPPED_IMMEDIATELY

When you request a card to be SHIPPED IMMEDIATELY, the order will be fulfilled within 72 hours and shipped via the courier of your choice.

Shipping method

Note: Tracking numbers are unavailable for cards shipped via USPS Ground.

USPS is the only supported carrier for shipments to PO Boxes.

You can choose various shipping methods for individual and group card orders. Shipping cost is based on the price outlined in your Highnote Master Services Agreement.

For a general overview of the PaymentCardShippingMethod enum, see the API Reference.

Individual card orders

Warning: USPS Priority Mail Express includes Signature Confirmation at no additional cost. If you do not wish to require Signature Confirmation, we recommend using another shipping method.

The following table outlines the available couriers, shipping options, and expected shipping times for individual card orders:

CourierShipment OptionExpected TimeOn-demand CardPremium Card
USPSGroundTwo to eight business daysapproved-icon.svgapproved-icon.svg
Priority Mail ®One to three business daysapproved-icon.svgapproved-icon.svg
Priority Mail Express ®Next business day to two daysapproved-icon.svg✖️
UPSGround ShippingOne to five business daysapproved-icon.svg✖️
Second Day AirTwo business daysapproved-icon.svg✖️
Next Day AirNext business dayapproved-icon.svg✖️
FedExOne RateTwo to three business days✖️approved-icon.svg
Standard OvernightNext day by 6 PM✖️approved-icon.svg

Group card orders

Warning: USPS Priority Mail Express includes Signature Confirmation at no additional cost. If you do not wish to require Signature Confirmation, we recommend using another shipping method.

At this time, group card orders are only available for on-demand cards. The following table outlines the available couriers, shipping options, and expected shipping times for group card orders:

CourierShipment OptionExpected Time
USPSPriority Mail ®One to three business days
Priority Mail ® - Processed Same DayNext business day to two days
Priority Mail Express ®Next business day to two days
UPSGround ShippingOne to five business days
Ground Shipping - Processed Same DayOne to five business days
Second Day AirTwo business days
Second Day Air - Processed Same DayTwo business days
Next Day AirNext business day
Next Day Air - Processed Same DayNext business day

Return address

Your return address is configured by the Highnote team when your card product is set up. To view or update your return address, send a request to support@highnote.com.

Orders that cannot be delivered are returned to the return address on file with Highnote.

Validate shipping address

Note: Validated address tokens are cached for 24 hours. If they are not used, they go away. If they are used, they are converted to a permanent validated address record which can be reused anytime.

Before submitting a physical card order, you can validate the card order's shipping address using the validateAddress mutation. This mutation validates addresses using a CASS-certified service to ensure it is properly formatted to reduce possible shipping delays or returns.

The Highnote API returns an AddressValidationResult response with the following results:

  • A validated address token
  • An error message explaining why the address is invalid

Address validation responses

When validating an address, the API will return a response that indicates whether the address is valid, incomplete, or invalid. Each response type has a corresponding "next step" to create a physical card order or re-validate a new address.

Refer to the following table for an overview of address validation responses and their corresponding follow-up actions:

Response typeDescriptionNext step
AddressValidatedResultThe address passed in is properly formatted and CASS-certified.Use the returned address token to submit a physical card order for the validated address.
AddressValidatedWithChangesResultThe address passed in has been modified to be properly formatted and CASS-certified.Use the returned address token to submit a physical card order for the modified validated address. Alternatively, you may adjust the address and resubmit an address validation request to generate a new validated address token.
AddressIncompleteResultThe address is missing critical components and cannot be CASS-certified.You must adjust the address and resubmit an address validation request to generate a new validated address token.
AddressInvalidResultThe address passed in cannot be CASS-certified.You must adjust the address and resubmit an address validation request to generate a new validated address token.

Address components and attributes

Components

The Highnote API uses the following components to validate an address:

ComponentDescription
STREET_ADDRESSThe street number and street name of the address, including directionals.
EXTENDED_ADDRESSAdditional information such as suite and apartment numbers.
LOCALITYTypically refers to the city or town portion of the address.
REGIONThe CLDR region code of the country or region of the address. For US addresses, this is the 2-character state code.
POSTAL_CODEThe zip or postal code of the address.
COUNTRY_CODE_ALPHA_3The three-character country code of the address.

Attributes

When an address is validated, the API returns a list of attributes that you can use to determine whether to use the address for a shipment:

Response codeDescription
PO_BOXIndicates the address of a PO box.
BUSINESSIndicates the address of a business.
RESIDENTIALIndicates the address of a residence.
CMRAIndicates the address of a Commercial Mail Receiving Agency, which is a private business receiving mail for customers.
VACANTIndicates the address is currently vacant.
INACTIVEIndicates the address is considered inactive.
UNSECURED_LOCATIONIndicates that a door is accessible, but a package may not be left due to security concerns.
UNCONFIRMED_EXTENDED_ADDRESSIndicates that the primary address is confirmed but the secondary address is not confirmed.

Example 1: Valid address

Note: The query provided in this section is intended for use in the live environment. To simulate address validation responses, see Simulate Address Validation.

In the following example, the address passed to the API is valid as is. The API returns the address and a valid address token:

Example 2: Address with missing components

Note: The query provided in this section is intended for use in the live environment. To simulate address validation responses, see Simulate Address Validation.

In the following example, the address is missing a component: the suite number. The API returns a message detailing why the address is invalid:

Example 3: Valid address with changes

Note: The query provided in this section is intended for use in the live environment. To simulate address validation responses, see Simulate Address Validation.

In the following example, the address passed is valid once the street address and postal code were changed. This is an example of an address that is valid with changes. The API returns the updated address and valid address token:

Example 4: Invalid address

Note: The query provided in this section is intended for use in the live environment. To simulate address validation responses, see Simulate Address Validation.

In the following example, the address is invalid. The API returns a message detailing which components are invalid and need updating before re-attempting address validation:

Simulate address validation

To simulate address validation, see the Simulate Address Validation guide.

Create physical card order

Note: You can only submit one order for a given payment card. If the order is canceled or fails, you can retry the order for the same card. However, if an order is successful and you need another physical card, you will need to issue a new payment card.

Once you have issued a payment card, you can create an order for a physical card. When ordering a physical card, you can ship to the account holder's address on file or specify a different shipping address.

Physical card orders require:

  • Card personalization details
  • Shipping address
  • Requested ship date
  • Shipping method and signature requirements

You can create individual physical card orders using the following mutation. To create a group card order, see Print Cards in Bulk.

Create physical card order with validated address

Use the following mutation to create a physical card order with a validated shipping address. For best results, use the validateAddress response token from the validateAddress mutation.

Monitor order status

Note: Orders shipped via USPS Ground do not return a tracking number.

Once you have requested a physical card order you can use a query for updates on the order’s status. When the order has moved to SHIPPED status, you can query the tracking number to share with your customers.

Use the following query to check the status of a physical card order:

Cancel a card order

Orders can only be canceled if they have the NEW status, allowing you to cancel printing and shipment in the event a mistake was made. If you need to edit attributes such as shipping address or make changes after the order passes the NEW status, contact support@highnote.com and create a new physical card order.

Use the following mutation to cancel a physical card order:

Order failures

A SHIPMENT_FAILED status occurs when the physical card can not reach the provided address. When this occurs, you must contact the account holder for more information and create a new orderPhysicalPaymentCard request with updated information.

Use the following query to find the status of a physical card order:

Search physical card orders

You can use the Highnote API to search for physical card orders for status tracking or display order history on your website or application. You can narrow search results using filters for physical card order information or payment card details.

The following sections provide an overview of searching for individual card orders. For information on group orders, see Print Cards in Bulk.

Physical card order filters

Physical card order filters allow you to narrow search results based on information related to individual card orders. These filters include the following:

FilterDescription
physicalPaymentCardOrderIdInput to filter by the ID of the physical payment card order
cardProductIdInput to filter by the ID of your card product
paymentCardOrderStatusInput to filter by the status of the card order; for a list of possible statuses, see the PaymentCardOrderStatus enum
groupOrderIdInput to filter by the ID of the group order the individual payment card is in; not applicable to individual card orders not included in a group order
shippingMethodInput to filter by the shipping method of the group order; for a list of possible statuses, see the PaymentCardShippingMethod enum

Payment card filters

You can also narrow down search results using the paymentCardFilterBy input. These filters return data related to the payment card in the physical card order:

FilterDescription
accountHolderIdInput to filter by the ID of an account holder
paymentCardIdInput to filter by the ID of a payment card
binInput to filter by the BIN of the payment card in the physical card order
last4Input to filter by the last four digits of the payment card in the physical card order
paymentCardPersonalizationLine1Input to filter by line 1 of the payment card's personalization details
paymentCardPersonalizationLine2Input to filter by line 2 of the payment card's personalization details
paymentCardStatusInput to filter by the status of the payment card in the physical card order
paymentCardHolderIdInput to filter by the ID of the cardholder; cardholders include account holders, authorized users, and primary authorized persons
cardProfileSetIdInput to filter by the ID of the card profile set the payment card belongs to

Example search query

The following query is an example search query that returns physical payment card orders for an organization, filtered using physical card order and payment card filters:

Simulate card order fulfillment

To simulate card order fulfillment for individual card orders, see the Simulate card order fulfillment guide.

Provide Feedback

Was this content helpful?