Skip to main content

Manage Cards

Overview​

Prepaid and debit cards must have a PIN set after they are issued, and the card must be ACTIVE to set the PIN.

Change a PIN​

Change a 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:

SetPinForPaymentCard​
Query
mutation SetPinForPaymentCard($input: SetPinForPaymentCardInput!) {
  setPinForPaymentCard(input: $input) {
    __typename
    ... on PaymentCard {
      id
    }
    ... on UserError {
      errors {
        errorPath
        code
      }
    }
  }
}
Variables
{
  "input": {
    "paymentCardId": "PAYMENT_CARD_ID",
    "newPin": "1234"
  }
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
  "data": {
    "setPinForPaymentCard": {
      "__typename": "PaymentCard",
      "id": "PAYMENT_CARD_ID"
    }
  },
  "extensions": {
    "requestId": "REQUEST_ID"
  }
}

Lock a card​

Lock 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:

SuspendPaymentCard​
Query
mutation SuspendPaymentCard($input: SuspendPaymentCardInput!) {
  suspendPaymentCard(input: $input) {
    ... on PaymentCard {
      __typename
      id
      status
    }
  }
}
Variables
{
  "input": {
    "paymentCardId": "PAYMENT_CARD_ID"
  }
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
  "data": {
    "suspendPaymentCard": {
      "__typename": "PaymentCard",
      "id": "PAYMENT_CARD_ID",
      "status": "SUSPENDED"
    }
  },
  "extensions": {
    "requestId": "REQUEST_ID"
  }
}

Unlock a card​

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:

ActivatePaymentCard​
Query
mutation ActivatePaymentCard($input: ActivatePaymentCardInput!) {
  activatePaymentCard(input: $input) {
    ... on PaymentCard {
      id
      status
    }
    ... on UserError {
      errors {
        errorPath
        code
        description
      }
    }
  }
}
Variables
{
  "input": {
    "paymentCardId": "PAYMENT_CARD_ID"
  }
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
  "data": {
    "activatePaymentCard": {
      "id": "PAYMENT_CARD_ID",
      "status": "ACTIVE"
    }
  },
  "extensions": {
    "requestId": "REQUEST_ID",
    "rateLimit": {
      "cost": 11,
      "limit": 100000,
      "remaining": 99989
    }
  }
}

Reissue a card​

When you reissue a card, you maintain card lineage by reusing the network-level Payment Account Reference (PAR). And depending on the reissue reason, you can either reuse or recreate the Primary Account Number (PAN) and Personal Identification Number (PIN).

To minimize the risk of fraud, you should only reissue a card that meets the following criteria:

  • The original card is in possession of the cardholder, e.g., expiring/expired, damaged, or virtual.
  • The original card is not subject to fraud or potentially subject to fraud.

Lost and stolen cards​

It is a best practice to treat lost and stolen cards the same, by breaking lineage and issuing a new card, rather than reissuing.

Stolen Cards​

Do not reissue stolen cards

Do not reissue stolen cards under any conditions. Always establish a new card lineage.

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

Lost Cards​

Do not reissue lost cards either

Reissuing a lost card is not a best practice. Consider issuing a new card instead.

Highnote recommends that you do not reissue lost cards as they are no longer in the possession of the cardholder, and like stolen cards, subject to fraud.

If your workflow requires that you maintain lineage for a lost card, you must:

  • Set reissueReason = LOST
  • Create a new PAN: copyNumber = false
  • Force the user to create a new PIN: copyPin = false
  • Populate cardLostDate or an API error is thrown

Contact support@highnote.com for help with lost card workflows.

For preprinted cards, see Reissue lost preprinted card.

How to reissue a card​

When reissuing a card, do not close the original card until you or the cardholder activates the new card. Otherwise, both cards may end up closed if the original card is accidentally closed before the reissued card is activated.

Refer the following table when reissuing a card:

Reissue ScenarioCan Reuse PAN?Can Reuse PIN?Reissue ReasonSpecial Condition
Current card is expiring soonYesYesEXPIREDexpirationDate must be later than that of original card
The current card is damaged, and the cardholder has possession of the cardYesYesOTHER
Current card is virtual only and cardholder wants a physical cardYesYesOTHERexpirationDate must be later than that of original card
Current card is lost and cardholder does not have possession of the card ^NoNoLOSTcardLostDate must be populated. copyNumber must be false or API error is thrown.

Reissuing steps​

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

  1. Start with an original payment card that is not in the CLOSED state.

  2. Call reissuePaymentCard to create a new payment card with the same network PAR. By default, new payment cards are virtual cards and attached to the same financial account as the original card. Depending on the reissue reason, you can copy or recreate the PAN and PIN from the original payment card. You can also reissue a physical card if necessary, using an existing or new address for shipping.

  3. Recreate or reuse the PAN: If copyNumber = true, the new payment card will have the same PAN as the original and you can set copyPin = true. If copyNumber = false, the new payment card will have a different PAN from the original and you must (a) set copyPin = false, and (b) update expirationDate to a new date in the future.

    Note: A new CVV is created when the PAN or expiration date changes.

  4. When reissuing physical cards, the card should not be active during printing and shipping, as activateOnCreate is set to false. Even if it has the same card number, it will have a different expiration date and CVV. The virtual card remains active.

    Important: Never ship an active physical card.

  5. 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. When you activate a reissued card, the old card is immediately deactivated and no longer accepts authorizations.

Use the reissuePaymentCard mutation to reissue a card:

ReissuePaymentCard​
Query
mutation ReissuePaymentCard($input: ReissuePaymentCardInput!) {
  reissuePaymentCard(input: $input) {
    ... on PaymentCard {
      id
      last4
      expirationDate
      status
      originalPaymentCard {
        id
      }
    }
    ... on UserError {
      errors {
        errorPath
        code
        description
      }
    }
  }
}
Variables
{
  "input": {
    "originalPaymentCardId": "PAYMENT_CARD_ID",
    "options": {
      "activateOnCreate": false,
      "expirationDate": "2025-01-01T23:59:59Z",
      "reissueFeatures": {
        "copyNumber": true,
        "copyPin": false
      }
    }
  }
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
  "data": {
    "reissuePaymentCard": {
      "id": "PAYMENT_CARD_ID",
      "last4": "4876",
      "expirationDate": "2025-01-01T23:59:59Z",
      "status": "ACTIVATION_REQUIRED",
      "originalPaymentCard": {
        "id": "PAYMENT_CARD_ID"
      }
    }
  }
}

Close a card​

Close Card

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

ClosePaymentCard​
Query
mutation ClosePaymentCard($input: ClosePaymentCardInput!) {
  closePaymentCard(input: $input) {
    ... on PaymentCard {
      __typename
      id
      status
    }
  }
}
Variables
{
  "input": {
    "paymentCardId": "PAYMENT_CARD_ID"
  }
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
  "data": {
    "closePaymentCard": {
      "__typename": "PaymentCard",
      "id": "PAYMENT_CARD_ID",
      "status": "CLOSED"
    }
  },
  "extensions": {
    "requestId": "REQUEST_ID"
  }
}

View card status​

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:

FindPaymentCard​
Query
query FindPaymentCard($id: ID!) {
  node(id: $id) {
    ... on PaymentCard {
      id
      bin
      last4
      expirationDate
      network
      status
      formFactor
      suspensionFlags
      cardProductApplication {
        __typename
        ... on AccountHolderCardProductApplication {
          id
          applicationState {
            status
          }
        }
      }
    }
  }
}
Variables
{
  "input": {
    "paymentCardId": "PAYMENT_CARD_ID"
  }
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
  "data": {
    "node": {
      "id": "PAYMENT_CARD_ID",
      "bin": "510520",
      "last4": "5788",
      "expirationDate": "2025-01-01T23:59:59Z",
      "network": "MASTERCARD",
      "status": "SUSPENDED",
      "formFactor": "VIRTUAL",
      "suspensionFlags": [
        "PROGRAM_OWNER_INITIATED_SUSPENSION",
        "ISSUER_INITIATED_SUSPENSION"
      ],
      "cardProductApplication": {
        "__typename": "AccountHolderCardProductApplication",
        "id": "APPLICATION_ID",
        "applicationState": {
          "status": "APPROVED"
        }
      }
    }
  },
  "extensions": {
    "requestId": "4c036a05-f2a3-9bee-bab6-0f85b89bca00",
    "rateLimit": {
      "cost": 20,
      "limit": 60060,
      "remaining": 60040
    }
  }
}

Map ATM locations​

info

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.
FindATMLocationsForPaymentCardByRadius​
Query
query FindATMLocationsForPaymentCardByRadius(
  $paymentCardId: ID!
  $radius: ATMLocationRadiusInput!
) {
  node(id: $paymentCardId) {
    __typename
    ... on PaymentCard {
      id
      bin
      last4
      atmLocations(radius: $radius) {
        ... on AtmLocationsResult {
          ... on ATMLocations {
            atmLocations {
              name
              description
              logo {
                brand
              }
              features
              address {
                streetAddress
                extendedAddress
                postalCode
                region
                locality
                countryCodeAlpha3
              }
              coordinates {
                latitude
                longitude
              }
              distance {
                length
                unit
              }
            }
          }
          ... on UserError {
            errors {
              errorPath
              code
              description
            }
          }
        }
      }
    }
  }
}
Variables
{
  "paymentCardId": "PAYMENT_CARD_ID",
  "radius": {
    "coordinates": {
      "latitude": "41.40338",
      "longitude": "2.17403"
    },
    "distance": {
      "length": 10,
      "unit": "MILE"
    }
  }
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
  "data": {
    "node": {
      "__typename": "PaymentCard",
      "id": "PAYMENT_CARD_ID",
      "bin": "547203",
      "last4": "4841",
      "atmLocations": {
        "atmLocations": [
          {
            "name": "7ELEVEN-FCTI",
            "description": "3519 N CLARK STREET, CHICAGO, IL 60657",
            "logo": {
              "brand": "MONEY_PASS"
            },
            "features": [
              "OPEN_24_HOURS"
            ],
            "address": {
              "streetAddress": "3519 N CLARK STREET",
              "extendedAddress": "",
              "postalCode": "60657",
              "region": "IL",
              "locality": "CHICAGO",
              "countryCodeAlpha3": "USA"
            },
            "coordinates": {
              "latitude": "41.9462127640016",
              "longitude": "-87.6555914957832"
            },
            "distance": {
              "length": 0.129139,
              "unit": "MILE"
            }
          },
          {
            "name": "7ELEVEN-FCTI",
            "description": "1027 W ADDISON ST, CHICAGO, IL 60613",
            "logo": {
              "brand": "MONEY_PASS"
            },
            "features": [
              "OPEN_24_HOURS"
            ],
            "address": {
              "streetAddress": "1027 W ADDISON ST",
              "extendedAddress": "",
              "postalCode": "60613",
              "region": "IL",
              "locality": "CHICAGO",
              "countryCodeAlpha3": "USA"
            },
            "coordinates": {
              "latitude": "41.9469968",
              "longitude": "-87.6554665"
            },
            "distance": {
              "length": 0.183594,
              "unit": "MILE"
            }
          }
        ]
      }
    }
  },
  "extensions": {
    "requestId": "REQUEST_ID"
  }
}

Filter ATM search results​

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:

FindATMLocationsForPaymentCardWithFilter​
Query
query FindATMLocationsForPaymentCardWithFilter(
  $paymentCardId: ID!
  $radius: ATMLocationRadiusInput!
  $filter: ATMLocationFilterInput!
) {
  node(id: $paymentCardId) {
    __typename
    ... on PaymentCard {
      id
      bin
      last4
      atmLocations(radius: $radius, atmFilter: $filter) {
        ... on AtmLocationsResult {
          ... on ATMLocations {
            atmLocations {
              name
              description
              logo {
                brand
              }
              features
              address {
                streetAddress
                extendedAddress
                postalCode
                region
                locality
                countryCodeAlpha3
              }
              coordinates {
                latitude
                longitude
              }
              distance {
                length
                unit
              }
            }
          }
          ... on UserError {
            errors {
              errorPath
              code
              description
            }
          }
        }
      }
    }
  }
}
Variables
{
  "paymentCardId": "PAYMENT_CARD_ID",
  "radius": {
    "coordinates": {
      "latitude": "41.40338",
      "longitude": "2.17403"
    },
    "distance": {
      "length": 10,
      "unit": "MILE"
    }
  },
  "filter": {
    "includes": [
      "OPEN_24_HOURS"
    ]
  }
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
  "data": {
    "node": {
      "__typename": "PaymentCard",
      "id": "PAYMENT_CARD_ID",
      "bin": "547203",
      "last4": "4841",
      "atmLocations": {
        "atmLocations": [
          {
            "name": "7ELEVEN-FCTI",
            "description": "3519 N CLARK STREET, CHICAGO, IL 60657",
            "logo": {
              "brand": "MONEY_PASS"
            },
            "features": [
              "OPEN_24_HOURS"
            ],
            "address": {
              "streetAddress": "3519 N CLARK STREET",
              "extendedAddress": "",
              "postalCode": "60657",
              "region": "IL",
              "locality": "CHICAGO",
              "countryCodeAlpha3": "USA"
            },
            "coordinates": {
              "latitude": "41.9462127640016",
              "longitude": "-87.6555914957832"
            },
            "distance": {
              "length": 0.129139,
              "unit": "MILE"
            }
          },
          {
            "name": "7ELEVEN-FCTI",
            "description": "1027 W ADDISON ST, CHICAGO, IL 60613",
            "logo": {
              "brand": "MONEY_PASS"
            },
            "features": [
              "OPEN_24_HOURS"
            ],
            "address": {
              "streetAddress": "1027 W ADDISON ST",
              "extendedAddress": "",
              "postalCode": "60613",
              "region": "IL",
              "locality": "CHICAGO",
              "countryCodeAlpha3": "USA"
            },
            "coordinates": {
              "latitude": "41.9469968",
              "longitude": "-87.6554665"
            },
            "distance": {
              "length": 0.183594,
              "unit": "MILE"
            }
          }
        ]
      }
    }
  },
  "extensions": {
    "requestId": "REQUEST_ID"
  }
}

Inclusive ATM filters​

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.

ATM Filter using includes
{
  "includes": ["OPEN_24_HOURS"]
}