Home / Issuing / Issue Cards
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:
This guide provides an overview of printing personalized physical cards. For an overview of preprinted cards, see Issue Preprinted Physical Cards.
Individual physical card orders allow you to print a single physical card. Physical card orders are:
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 physical card orders allow you to request several physical cards at once. Note the following about group physical card orders:
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 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:
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:
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:
Status | Description |
---|---|
NEW | A request for a physical card has been made. This is the only stage at which an order may be canceled. |
PENDING | The 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_PRINTER | The order has successfully been sent to the printer. |
APPROVED | The printer has approved the order. |
SHIPPED | The order has been shipped. All shipment methods besides USPS Ground return a tracking number. |
CANCELED | You requested to cancel the order. |
SHIP_FAILED | The order failed to reach the account holder. Failed orders are returned to the return address on file. |
Highnote sends physical card fulfillment requests to the printer several times a day. The following fulfillment options are available as requestedShipDate
input variables:
YYYY-MM-DD
formatSHIPPED_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.
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.
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:
Courier | Shipment Option | Expected Time | On-demand Card | Premium Card |
---|---|---|---|---|
USPS | Ground | Two to eight business days | ||
Priority Mail ® | One to three business days | |||
Priority Mail Express ® | Next business day to two days | ✖️ | ||
UPS | Ground Shipping | One to five business days | ✖️ | |
Second Day Air | Two business days | ✖️ | ||
Next Day Air | Next business day | ✖️ | ||
FedEx | One Rate | Two to three business days | ✖️ | |
Standard Overnight | Next day by 6 PM | ✖️ |
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:
Courier | Shipment Option | Expected Time |
---|---|---|
USPS | Priority Mail ® | One to three business days |
Priority Mail ® - Processed Same Day | Next business day to two days | |
Priority Mail Express ® | Next business day to two days | |
UPS | Ground Shipping | One to five business days |
Ground Shipping - Processed Same Day | One to five business days | |
Second Day Air | Two business days | |
Second Day Air - Processed Same Day | Two business days | |
Next Day Air | Next business day | |
Next Day Air - Processed Same Day | Next business day |
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.
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:
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 type | Description | Next step |
---|---|---|
AddressValidatedResult | The address passed in is properly formatted and CASS-certified. | Use the returned address token to submit a physical card order for the validated address. |
AddressValidatedWithChangesResult | The 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. |
AddressIncompleteResult | The 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. |
AddressInvalidResult | The 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. |
The Highnote API uses the following components to validate an address:
Component | Description |
---|---|
STREET_ADDRESS | The street number and street name of the address, including directionals. |
EXTENDED_ADDRESS | Additional information such as suite and apartment numbers. |
LOCALITY | Typically refers to the city or town portion of the address. |
REGION | The CLDR region code of the country or region of the address. For US addresses, this is the 2-character state code. |
POSTAL_CODE | The zip or postal code of the address. |
COUNTRY_CODE_ALPHA_3 | The three-character country code of the address. |
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 code | Description |
---|---|
PO_BOX | Indicates the address of a PO box. |
BUSINESS | Indicates the address of a business. |
RESIDENTIAL | Indicates the address of a residence. |
CMRA | Indicates the address of a Commercial Mail Receiving Agency, which is a private business receiving mail for customers. |
VACANT | Indicates the address is currently vacant. |
INACTIVE | Indicates the address is considered inactive. |
UNSECURED_LOCATION | Indicates that a door is accessible, but a package may not be left due to security concerns. |
UNCONFIRMED_EXTENDED_ADDRESS | Indicates that the primary address is confirmed but the secondary address is not confirmed. |
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:
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:
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:
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:
To simulate address validation, see the Simulate Address Validation guide.
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:
You can create individual physical card orders using the following mutation. To create a group card order, see Print Cards in Bulk.
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.
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:
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:
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:
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 allow you to narrow search results based on information related to individual card orders. These filters include the following:
Filter | Description |
---|---|
physicalPaymentCardOrderId | Input to filter by the ID of the physical payment card order |
cardProductId | Input to filter by the ID of your card product |
paymentCardOrderStatus | Input to filter by the status of the card order; for a list of possible statuses, see the PaymentCardOrderStatus enum |
groupOrderId | Input 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 |
shippingMethod | Input to filter by the shipping method of the group order; for a list of possible statuses, see the PaymentCardShippingMethod enum |
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:
Filter | Description |
---|---|
accountHolderId | Input to filter by the ID of an account holder |
paymentCardId | Input to filter by the ID of a payment card |
bin | Input to filter by the BIN of the payment card in the physical card order |
last4 | Input to filter by the last four digits of the payment card in the physical card order |
paymentCardPersonalizationLine1 | Input to filter by line 1 of the payment card's personalization details |
paymentCardPersonalizationLine2 | Input to filter by line 2 of the payment card's personalization details |
paymentCardStatus | Input to filter by the status of the payment card in the physical card order |
paymentCardHolderId | Input to filter by the ID of the cardholder; cardholders include account holders, authorized users, and primary authorized persons |
cardProfileSetId | Input to filter by the ID of the card profile set the payment card belongs to |
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:
To simulate card order fulfillment for individual card orders, see the Simulate card order fulfillment guide.