# Lookup BIN data using 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

## Security:

  - `basicAuth` (unknown)
    http basic

## Header parameters:

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

## Request body:

  - `application/json` (unknown)
    Provide a paymentInstrument with type card (PAN or Network Token Number, 12-19 digits) or type token (Worldpay token href). The merchant.entity field identifies your routing entity; use the value assigned during on-boarding.

## 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.

  - `paymentInstrument.type` (string, required)
    Discriminator value identifying this as a card number lookup.
    Enum: "card"

  - `paymentInstrument.number` (string, required)
    Primary Account Number (PAN) or Network Token Number. Must be 12–19 digits. Do not include spaces or dashes.
    Example: 4444333322221111

  - `paymentInstrument.type` (string, required)
    Discriminator value identifying this as a token lookup.
    Enum: "token"

  - `paymentInstrument.href` (string)
    Full Worldpay token href URL, as returned when the token was created. Begins with https://.../tokens/.
    Example: https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0NzI0NE1rdUtjMUFJdjYxVnlibWZuUT0ifQ

## Request examples:

  - `Lookup by card number (PAN)` (unknown)

  - `Lookup by Worldpay token (href)` (unknown)

## Response 200:

  - `200` (unknown)
    BIN lookup succeeded. Response contains card metadata including brand, BIN and BIN length, PAN length, funding type, issuer details, DCC eligibility, AMLD5 status, card category, scheme product ID and sub-type, flexible credential participation, Visa Direct Account Funding Transaction eligibility and Visa (Direct) and Mastercard (Send) payout support.

## 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.
    Example: ["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

  - `panLength` (integer)
    Expected length of the Primary Account Number. A value of 0 indicates the PAN length is variable for this BIN range.
    Example: 16

  - `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"

  - `productId` (string)
    Scheme product identifier assigned by the card scheme. Can be used to determine card product tier and support interchange cost analysis. Values are scheme-defined and subject to change.
    Example: A

  - `productSubType` (string)
    Scheme product sub-type providing further classification within a product, for example agriculture or healthcare segments for Visa. Values are scheme-defined, subject to change, and not consistent across schemes.
    Example: HC

  - `flexibleCredential` (object)
    Visa Flexible Credential and Mastercard One Credential participation.

  - `flexibleCredential.participating` (boolean)
    true if the card participates in Visa Flexible Credential or Mastercard One Credential. Use this to determine whether flexible credential routing logic applies.
    Example: true

  - `flexibleCredential.deploymentModel` (string)
    Visa Flexible Credential deployment model. Only present when `participating` is true.
- `managed`: cardholder choices held by Visa.
- `selfServe`: cardholder choices held by the issuer.
    Enum: "selfServe", "managed"

  - `accountFundingTransactions` (object)
    Visa Direct Account Funding Transaction (AFT) eligibility for this BIN. AFTs are used to pull funds from a Visa card account to fund a push payment (OCT) to another account. Check these flags before initiating a Visa Direct pull payment to determine whether the transaction is permitted for this card.

  - `accountFundingTransactions.domestic` (string)
    Whether this card is eligible to be the source of a domestic Visa Direct Account Funding Transaction. A value of supported means the issuer participates in AFT for domestic transactions. notSupported means the issuer does not permit AFTs for domestic transactions.
    Enum: "supported", "notSupported"

  - `accountFundingTransactions.crossBorder` (string)
    Whether this card is eligible to be the source of a cross-border Visa Direct Account Funding Transaction. A value of supported means the issuer participates in AFT for cross-border transactions. notSupported means the issuer does not permit AFTs for cross-border transactions.
    Enum: "supported", "notSupported"

  - `payouts` (object)
    Supported payout capabilities for Visa and Mastercard. This object is omitted when payout information is not applicable to the scheme or when capability data is unavailable.

  - `payouts.standard` (object)
    Support status for standard processing where funds are received in 1-3 business days.

  - `payouts.standard.domestic` (object)
    Support status for domestic payouts.

  - `payouts.standard.domestic.moneyTransfer` (string)
    Support for person-to-person and remittance payouts.
    Enum: "supported", "notSupported"

  - `payouts.standard.domestic.nonMoneyTransfer` (string)
    Support for commercial and non-remittance payouts.
    Enum: "supported", "notSupported"

  - `payouts.standard.domestic.gambling` (string)
    Support for gambling/gaming payouts.
    Enum: "supported", "notSupported"

  - `payouts.standard.crossBorder` (object)
    Support status for cross-border payouts.

  - `payouts.fast` (object)
    Support status for fast funding where funds are received within 30 minutes.

## Response 200 headers (application/json):

  - `WP-CorrelationId` (string)
    Unique request/response correlation ID. Include in support tickets when reporting issues.
    Example: 4c195ce9-3dbd-4bc8-9c94-3d3393842323

  - `WP-Api-Version` (string)
    Full API version (major.minor.patch) used to process the request.
    Example: 2.0.20260327

## Response 400:

  - `400` (unknown)
    Bad request. The request body or a required header is invalid. Inspect `errorName` and `validationErrors` to identify the specific problem, fix the request, and retry. Do NOT retry without fixing the issue first.

## 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 400 headers (application/json):

  - `WP-CorrelationId` (string)
    Correlation ID for support.
    Example: 4c195ce9-3dbd-4bc8-9c94-3d3393842323

  - `WP-Api-Version` (string)
    Full API version (major.minor.patch) used to process the request.
    Example: 2.0.20260327

## Response 401:

  - `401` (unknown)
    Unauthorized. The Authorization header is missing or contains invalid credentials. Do not retry automatically. Verify credentials and re-authenticate.

## 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 401 headers (application/json):

  - `WP-CorrelationId` (string)
    Correlation ID for support.
    Example: 4c195ce9-3dbd-4bc8-9c94-3d3393842323

## Response 404:

  - `404` (unknown)
    Not found. The supplied card number or token does not match any known BIN range or token record. Do not retry. Surface the error to the caller; the input data may be invalid or unsupported.

## 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 404 headers (application/json):

  - `WP-CorrelationId` (string)
    Correlation ID for support.
    Example: 4c195ce9-3dbd-4bc8-9c94-3d3393842323

  - `WP-Api-Version` (string)
    Full API version (major.minor.patch) used to process the request.
    Example: 2.0.20260327

## Response 415:

  - `415` (unknown)
    Unsupported Media Type. Set Content-Type to application/json and retry immediately.

## 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 415 headers (application/json):

  - `WP-CorrelationId` (string)
    Correlation ID for support.
    Example: 4c195ce9-3dbd-4bc8-9c94-3d3393842323

  - `WP-Api-Version` (string)
    Full API version (major.minor.patch) used to process the request.
    Example: 2.0.20260327

## Response 500:

  - `500` (unknown)
    Internal server error. The problem is on Worldpay's side. Retry with exponential back-off. If errors persist, contact support and provide WP-CorrelationId.

## 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

## Response 500 headers (application/json):

  - `WP-CorrelationId` (string)
    Correlation ID - include in all support tickets.
    Example: 4c195ce9-3dbd-4bc8-9c94-3d3393842323

  - `WP-Api-Version` (string)
    Full API version (major.minor.patch) used to process the request.
    Example: 2.0.20260327

## Response 200 examples:

  - `Card response - tokenized issuer range` (unknown)

  - `Worldpay token response - Includes payouts data` (unknown)

## Response 400 examples:

  - `Request body failed schema validation` (unknown)

  - `Required header missing` (unknown)

## Response 404 examples:

  - `Worldpay token not found` (unknown)

  - `PAN not found in any BIN range` (unknown)