# Lookup BIN data for a card number or Worldpay token

Returns card metadata for the supplied payment instrument. This is a read-only lookup with no side effects - safe to retry on network errors.

Endpoint: POST /api/cardBin/panLookup
Version: 2
Security: basicAuth

## Header parameters:

  - `WP-Api-Version` (integer, required)
    API major version number. Must be 2.
    Example: 2

## Request fields (application/json):

  - `merchant` (object, required)
    Identifies the merchant entity for request routing. The entity value is assigned during on-boarding.

  - `merchant.entity` (string, required)
    Merchant routing entity name assigned during on-boarding. Supports alphanumeric characters and the following special characters: space (not leading or trailing), hyphen, underscore, and common punctuation.
    Example: "default"

  - `paymentInstrument` (object, required)
    Use the card variant when you have a raw PAN or Network Token Number. Use the token variant when you have a Worldpay token href.

## Response 200 fields (application/json):

  - `type` (string)
    Indicates whether the card belongs to a tokenized issuer range.
    Enum: "pan", "networkToken"

  - `brand` (array)
    Card brand(s). Co-branded cards return multiple values. This list may grow as new schemes are added. Treat unrecognised values as valid strings and handle them gracefully rather than failing.
    Enum: "accel", "affn", "airplus", "allstar", "amex", "argencard", "ath", "aurore", "bc", "cabal", "carnet", "cartesBancaires", "cencosud", "coopeplus", "credimas", "culiance", "dankort", "diners", "discover", "eftposAU", "elo", "gecapital", "hana", "hipercard", "hyundai", "ikea", "interac", "interlink", "italcred", "jaywan", "jcb", "jeanie", "keyfuels", "kookmin", "lotte", "maestro", "mastercard", "naranja", "nativa", "ncp", "nevada", "newday", "nexo", "nonghyup", "nyce", "overdrive", "pavd", "pulse", "samsung", "sears", "shazam", "shinhan", "sorocred", "star", "starAccess", "supercharge", "tarjeta", "troy", "uatp", "unionPay", "visa"

  - `bin` (string)
    Bank Identification Number extracted from the card. Capped at 8 digits to protect PCI-sensitive data where the BIN length exceeds 8 digits. Use binLength to determine the full BIN length for this card.
    Example: "444422"

  - `binLength` (integer)
    Number of digits in the BIN (typically 6 or 8).
    Example: 6

  - `fundingType` (string)
    Funding source of the card. Use to select the correct interchange category, apply surcharging rules, or restrict card acceptance by type.
    Enum: "credit", "debit", "prepaid", "chargeCard", "deferredDebit"

  - `issuerName` (string)
    Name of the card-issuing bank or financial institution.
    Example: "Bank of America"

  - `countryCode` (string)
    ISO 3166-1 alpha-2 country code of the card issuer. Use for cross-border fee logic or geographic restrictions.
    Example: "US"

  - `currency` (string)
    ISO 4217 alpha-3 default currency of the card. Use together with dccAllowed to determine whether to offer Dynamic Currency Conversion.
    Example: "USD"

  - `dccAllowed` (boolean)
    true if Dynamic Currency Conversion may be offered to the cardholder for this card. Always check this flag before presenting a DCC offer.
    Example: true

  - `anonymousPrepaid` (string)
    AMLD5 anonymous prepaid status.
    Enum: "notPrepaidOrNonAnonymous", "anonymousNonCompliant", "anonymousCompliant", "unknown"

  - `category` (string)
    Whether the card is a commercial (business) or consumer card.
    Enum: "commercial", "consumer"

## Response 400 fields (application/json):

  - `errorName` (string, required)
    Machine-readable error code.
- headerIsMissing / headerHasInvalidValue: fix the named header.
- bodyIsEmpty / bodyIsNotJson / bodyDoesNotMatchSchema: fix the request body.
    Enum: "internalErrorOccurred", "headerIsMissing", "headerHasInvalidValue", "bodyIsEmpty", "bodyIsNotJson", "bodyDoesNotMatchSchema"

  - `message` (string, required)
    Human-readable corrective action. Not for machine parsing.
    Example: "A JSON body matching the expected schema must be provided."

  - `validationErrors` (array)
    Present when errorName is bodyDoesNotMatchSchema. Each entry identifies a specific field error with a jsonPath pointer.

  - `validationErrors.errorName` (string, required)
    Machine-readable error code identifying the validation failure.
    Enum: "fieldIsMissing", "fieldMustBeString", "fieldMustBeNumber", "fieldMustBeInteger", "fieldMustBeBoolean", "fieldMustBeObject", "fieldMustBeArray", "fieldIsNull", "fieldIsEmpty", "fieldHasInvalidValue", "fieldIsNotAllowed", "numberIsTooSmall", "integerIsTooLarge", "stringIsTooShort", "stringIsTooLong", "stringFailedRegexCheck"

  - `validationErrors.message` (string, required)
    Human-readable description of the error and corrective action.
    Example: "Field at path must be present."

  - `validationErrors.jsonPath` (string)
    JSON path of the field that caused the validation error.
    Example: "$.merchant.entity"

  - `headerName` (string)
    Present when errorName is headerIsMissing or headerHasInvalidValue. Identifies which header needs to be corrected.
    Example: "Content-Type"

## Response 401 fields (application/json):

  - `errorName` (string, required)
    Machine-readable error code. Always accessDenied for 401 responses.
    Enum: "accessDenied"

  - `message` (string, required)
    Human-readable corrective action.
    Example: "Access to the requested resource has been denied"

## Response 404 fields (application/json):

  - `errorName` (string, required)
    - tokenNotFound: the Worldpay token href is not recognized.
- cardNotFound: the PAN is not in any known BIN range.
    Enum: "cardNotFound", "tokenNotFound"

  - `message` (string, required)
    Human-readable corrective action.
    Example: "The card number cannot be found in any BIN ranges."

## Response 415 fields (application/json):

  - `errorName` (string, required)
    Machine-readable error code. Always headerHasInvalidValue for 415 responses.
    Enum: "headerHasInvalidValue"

  - `message` (string, required)
    Human-readable corrective action.
    Example: "A valid header must be provided."

  - `headerName` (string)
    Identifies which header is incorrect.
    Example: "Content-Type"

## Response 500 fields (application/json):

  - `errorName` (string, required)
    Machine-readable error code. Always internalServerError for 500 responses.
    Enum: "internalServerError"

  - `message` (string, required)
    Human-readable description of the server error.
    Example: "An internal server error occurred"