Instrument Eligibility

Use checkInstrumentEligibilityDetails to learn, before you move any money, whether the card network permits a card to receive funds (OCT) or send funds (AFT), and how the card is classified. Use it when a card is added, to set pricing or to show which cards can receive a withdrawal. You can also use it to classify an existing portfolio in batches.

The lookup does not store (vault) the card and does not run Account Name Inquiry (ANI). Visa and Mastercard cards are supported.

Network eligibility is not Highnote's decision

ELIGIBLE means the card network permits the transfer. It does not mean Highnote will accept it. Highnote's own requirements still apply when you make the transfer, so a transfer to an ELIGIBLE card can still be declined. For Highnote's decision on a card you have vaulted, read its Instant Network Transfer capabilities.

Check eligibility

Check Instrument Eligibility Details

Query

mutation CheckInstrumentEligibilityDetails(
  $input: CheckInstrumentEligibilityDetailsInput!
) {
  checkInstrumentEligibilityDetails(input: $input) {
    __typename
    ... on InstrumentEligibilityDetails {
      results {
        referenceIdentifier
        detail {
          __typename
          ... on CardEligibilityDetail {
            brand
            designation
            fundingSources
            issuingCountry
            currency
            networkProductCode
            networkMoneyMovementEligibility {
              originalCreditTransaction {
                domestic
                crossBorder
              }
              fastFunds {
                domestic
                crossBorder
              }
              accountFundingTransaction {
                domestic
                crossBorder
              }
            }
          }
          ... on UserError {
            errors {
              code
              description
            }
          }
          ... on AccessDeniedError {
            message
          }
        }
      }
    }
    ... on UserError {
      errors {
        code
        description
        errorPath
      }
    }
    ... on AccessDeniedError {
      message
    }
  }
}

Variables

{
  "input": {
    "instruments": [
      {
        "referenceIdentifier": "card-001",
        "instrument": {
          "paymentCard": {
            "cardNumber": "<CARD_NUMBER>"
          }
        }
      },
      {
        "referenceIdentifier": "bin-001",
        "instrument": {
          "paymentCardBin": {
            "bin": "<FIRST_9_DIGITS>"
          }
        }
      },
      {
        "referenceIdentifier": "card-002",
        "instrument": {
          "paymentCard": {
            "cardNumber": "<UNSUPPORTED_CARD_NUMBER>"
          }
        }
      }
    ]
  }
}

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

Result

{
  "data": {
    "checkInstrumentEligibilityDetails": {
      "__typename": "InstrumentEligibilityDetails",
      "results": [
        {
          "referenceIdentifier": "card-001",
          "detail": {
            "__typename": "CardEligibilityDetail",
            "brand": "VISA",
            "designation": "CONSUMER",
            "fundingSources": [
              "DEBIT"
            ],
            "issuingCountry": "USA",
            "currency": "USD",
            "networkProductCode": "F",
            "networkMoneyMovementEligibility": {
              "originalCreditTransaction": {
                "domestic": "ELIGIBLE",
                "crossBorder": "ELIGIBLE"
              },
              "fastFunds": {
                "domestic": "ELIGIBLE",
                "crossBorder": "NOT_ELIGIBLE"
              },
              "accountFundingTransaction": {
                "domestic": "ELIGIBLE",
                "crossBorder": "NOT_ELIGIBLE"
              }
            }
          }
        },
        {
          "referenceIdentifier": "bin-001",
          "detail": {
            "__typename": "CardEligibilityDetail",
            "brand": "VISA",
            "designation": "CONSUMER",
            "fundingSources": [
              "DEBIT"
            ],
            "issuingCountry": "USA",
            "currency": "USD",
            "networkProductCode": "F",
            "networkMoneyMovementEligibility": {
              "originalCreditTransaction": {
                "domestic": "ELIGIBLE",
                "crossBorder": "ELIGIBLE"
              },
              "fastFunds": {
                "domestic": "ELIGIBLE",
                "crossBorder": "NOT_ELIGIBLE"
              },
              "accountFundingTransaction": {
                "domestic": "ELIGIBLE",
                "crossBorder": "NOT_ELIGIBLE"
              }
            }
          }
        },
        {
          "referenceIdentifier": "card-002",
          "detail": {
            "__typename": "UserError",
            "errors": [
              {
                "code": "UNSUPPORTED_CARD_BRAND",
                "description": "Only Visa and Mastercard payment cards are supported"
              }
            ]
          }
        }
      ]
    }
  },
  "extensions": {
    "requestId": "REQUEST_ID"
  }
}

Replace <CARD_NUMBER> with your own card number and <FIRST_9_DIGITS> with the first 6 to 9 digits of a card number. Replace <UNSUPPORTED_CARD_NUMBER> with a card number that is not Visa or Mastercard, such as a Discover card, to see how a per-instrument error looks.

Request

checkInstrumentEligibilityDetails takes an instruments list.

• instruments accepts 1 to 100 entries. A request with none, or with more than 100, returns a UserError, and no instruments are checked.
• Each entry has an optional referenceIdentifier, which Highnote returns with that instrument's result, and exactly one instrument:
  • paymentCard.cardNumber: the full card number, 13 to 19 digits.
  • paymentCardBin.bin: the first 6 to 9 digits of the card number. Use it to check a card without sending the full card number.
• Eligibility is set per 9-digit range, so send all 9 digits when you have them.

Response

• The response has one result per instrument, in the same order as the request. Each result carries its referenceIdentifier.
• An instrument that cannot be checked has a UserError as its detail. Highnote still checks the other instruments.
• Handle detail types you do not recognize. New instrument types may be added over time.
• The response never includes the card number.

Card fields

A CardEligibilityDetail result has these fields.

Field	What it tells you
networkMoneyMovementEligibility.originalCreditTransaction	Whether the card can receive funds (push, OCT).
networkMoneyMovementEligibility.accountFundingTransaction	Whether the card can send funds (pull, AFT).
networkMoneyMovementEligibility.fastFunds	Whether OCT funds reach the cardholder within minutes. It describes the speed of an OCT, not a separate type of transfer. It applies only when originalCreditTransaction is ELIGIBLE for the same region.
brand	The card brand.
designation	How the card is classified. See Designation values.
fundingSources	How the card is funded. A card can have more than one, for example a combined debit and credit card. See Funding source values.
issuingCountry	The country that issued the card, as an ISO 3166-1 alpha-3 code.
currency	The issuer's billing currency for the card range, as an ISO 4217 alpha-3 code.
networkProductCode	The card network's product code for the card range.

Domestic and cross-border

Each eligibility field has a domestic status and a crossBorder status. A transfer is domestic when your business is in the same country as the card's issuingCountry. It is cross-border when it is not. Read the status for the case that applies to you.

Status values

Each domestic and crossBorder field returns a NetworkMoneyMovementEligibilityStatus.

Value	Meaning
ELIGIBLE	The card network permits the transfer. Highnote's own requirements still apply.
NOT_ELIGIBLE	The card network does not permit the transfer.
UNKNOWN	The card network does not report a value. This says nothing about whether Highnote will accept or decline a transfer.

Designation values

Value	Meaning
CONSUMER	A consumer card.
COMMERCIAL	A commercial card.
BUSINESS	A business card.
GOVERNMENT	A government card.
UNKNOWN	The designation could not be determined.

Funding source values

Value	Meaning
PREPAID	A prepaid card.
DEBIT	A debit card.
CREDIT	A credit card.
CHARGE	A charge card.
DEFERRED_DEBIT	A deferred debit card.

When a value is missing

Fields with a fixed set of values, such as designation and the eligibility statuses, return UNKNOWN when the card network does not report a value. They are null only when the value could not be retrieved.

Other fields, such as currency, are null when the card network does not report a value. In that case fundingSources is an empty list.

Errors

Errors reach you in two places.

• One instrument: the instrument's detail is a UserError, and Highnote still checks the other instruments. Each error has a code and a description. The errorPath is null, so use the instrument's referenceIdentifier to tell which one failed.
• The whole request: a request with no instruments, or more than 100, returns a UserError as the mutation's own result with the code INSTRUMENT_COUNT_OUT_OF_RANGE, and nothing is checked. Split larger sets into requests of up to 100.

These code values come back on an instrument's detail.

Code	When	What to do
INVALID_CARD_NUMBER	The card number is not 13 to 19 digits.	Correct the card number.
INVALID_BIN	The bin is not 6 to 9 digits, or contains a character that is not a digit.	Send the first 6 to 9 digits of the card number, digits only.
UNSUPPORTED_CARD_BRAND	The card is not a Visa or Mastercard card, for example Discover or American Express.	Check only Visa and Mastercard cards.
CARD_RANGE_NOT_FOUND	No known card range matches the card.	Treat the card as not found. This does not mean the card is not eligible.

Related

• Instant Network Transfers: Highnote's capabilities and decline reasons for a vaulted card.