Manage Cards

Prepaid and debit cards must have a PIN set after they are issued, and the card must be ACTIVE to set the PIN. Cardholders can update their PIN after it has been initially set.

• For web-based integrations, we recommend you change a PIN with the Secure Inputs SDK.
• For native iOS and Android-based integrations, and non-native PCI-compliant environments, you can securely change a PIN from the API with a Client Token.

Use the following mutation to set a PIN for a payment card:

Once a card is active, you can provide an interface for your account holders to lock their payment card. Locking a payment card is useful for scenarios when an account holder loses their card or is not actively using their card.

You can connect the mutation SuspendPaymentCard to a toggle element in your website or application to create the lock card functionality:

You can also provide an interface for your account holders to unlock" their payment cards.

Use the ActivatePaymentCard mutation to create the unlock card functionality for your website or application:

Warning: When reissuing cards, do not close the original card until you or the cardholder activates the new card. Both the original and reissued cards may end up closed if the original card is accidentally closed before the reissued card is activated.

Reissuing a card is the process of creating a new card with the same or a different number. You should only reissue a card that is in the possession of the cardholder (or virtual). Do not reissue lost or stolen cards. And never ship an active physical card.

The following use cases are common for reissuing cards:

Use the following mutation to reissue a card:

Do not reissue lost or stolen cards. When a card is reported lost or stolen, our platform reports it to the payment network; so the card should not be reissued, even with a new PAN. Instead, terminate the old card and issue a new one to establish a new card lineage.

To ensure alignment with payment network policies and minimize cardholder disruption:

• When reissuing a card, always supply the reason.
• Only reissue a card if it is in the cardholder’s possession.
• Only reissue a card if the original is about to expire, is damaged, or is virtual and the cardholder wants a physical card.

If the original card is virtual, reissue the physical card with a new expiration and CVV (but same PAN) so that the cardholder has to activate it. Never ship a card that is already activated.

The following steps outline an example of how you reissue a card:

1. Call reissuePaymentCard to create a new payment card. By default, the new payment card is a virtual card and will be attached to the same financial account as the original payment card. You may choose to copy the card number and/or PIN from the original payment card. You can also choose to reissue a physical card if necessary, using an existing or new address for shipping.
2. If copyNumber is true, the new payment card will have the same card number as the original payment card. You may then also choose to set copyPin to true. If you choose to update the card number, you will not be able to copy the PIN. Note, in this case, the expiration date cannot be in the same month/year as the original payment card. Additionally, the original payment card cannot be in the CLOSED state.
3. If you are reissuing a physical card, while the Physical Card is being printed and shipped to the account holder it is not active, as activateOnCreate is set to false. Note that even if it has the same card number, it will have a different expiration date and CVV. The virtual card remains active.
4. When the physical card is delivered to the account holder, you may want to activate it. You can only maintain one active reissued payment card at a time. As such, when you activate a reissued card, the old card will immediately be deactivated and no longer accept authorizations.

Closing a payment card is permanent and closes both virtual cards and any associated physical cards. Use the following mutation to close a card:

You can view the status of a payment card, including the suspensionFlags. The suspension must be removed by Highnote if an ISSUER_INITIATED_SUSPENSION is on the payment card.

Use the following query to lookup a payment card:

Note: A maximum of 50 ATM locations are returned per request.

If you offer payment cards with cash withdrawal capabilities, you may want to provide your account holders with the ability to locate ATMs that do not have surcharges.

Note the following when using the FindATMLocationsForPaymentCardByRadius query:

• Use a radius search when searching around a specific place (address, postal code, landmark, etc.) to retrieve the locations' latitude and longitude.
• Set a distance to the radius of the search circle. The distance is expected to be in miles unless overridden.

Filters allow you to refine your ATM location search by including or excluding certain ATM features.

By default, the ATM features included are:

• OPEN_24_HOURS
• DEPOSIT_AVAILABLE
• ACCESSIBLE

Use the following query to filter your ATM search results:

When using the include parameter, ATM location search results will be filtered to only the included values of available ATM features.

In the following code snippet example, since the includes field was provided with the value of OPEN_24_HOURS, the results from the API will return only the matching locations.