openapi: 3.0.1
info:
  title: Card BIN Data
  description: >-
    Lookup card metadata from a Primary Account Number (PAN), Network Token
    Number, or Worldpay token href.


    Returns: card brand(s), BIN and BIN length, PAN length, funding type, issuer
    name, issuer country (ISO alpha-2), default currency (ISO alpha-3), DCC
    eligibility, anonymous prepaid / AMLD5 compliance status, card category
    (consumer or commercial), product ID, product subtype, flexible credential
    participation including the Visa deployment model and account funding
    transactions support for domestic and cross-border. <br><br>

        __Set your headers__
      ```
        Authorization: {your_credentials}
        Content-Type: application/json
        WP-Api-Version: 2
      ```
    Replace `{your_credentials}` with your base64-encoded Basic Auth
    username:password given to you by your Worldpay Implementation Manager.
    <br/><br/> We require the Content-Type header if the request you're sending
    includes a request body, and if the HTTP method is a `POST` or a `PUT`.
    <br/><br/> We use the WP-Api-Version header to identify which version of our
    API you are using. You must use this header for any request you send to our
    Card BIN API. <br/><br/>

    __DNS whitelisting__ <br> Whitelist the following URLs:<br> *
    `https://try.access.worldpay.com/`<br> *
    `https://access.worldpay.com/`<br><br>

    Please ensure you use DNS whitelisting, not explicit IP whitelisting.
  version: '2'
  x-ai-hints:
    primary-use-cases:
      - Lookup card brand and funding type before processing a payment
      - Determine DCC eligibility for a card
      - Check anonymous prepaid / AMLD5 status for compliance
      - Enrich card data from a stored Worldpay token
      - Determine Visa Direct AFT eligibility before initiating a pull payment
    authentication: >-
      HTTP Basic Auth. Set the Authorization header to "Basic
      <base64(username:password)>". Credentials are issued by your Worldpay
      Worldpay Implementation Manager.
    required-headers:
      - 'Authorization: Basic <credentials>'
      - 'Content-Type: application/json'
      - 'WP-Api-Version: 2'
    error-recovery:
      '400': >-
        Fix the request body or headers per the validationErrors array and retry
        immediately.
      '401': Re-check credentials. Do not retry automatically.
      '404': >-
        The card or token is not in Worldpay BIN ranges. Do not retry; surface
        error to caller.
      '415': Set Content-Type to application/json and retry immediately.
      '500': >-
        Transient server error. Retry with exponential back-off; include
        WP-CorrelationId in support tickets.
  x-metadata:
    category:
      - Card BIN
    business:
      - Enterprise
    catalog-list: true
    generated: false
servers:
  - url: https://try.access.worldpay.com
    description: Test (Try) - use for integration and QA
  - url: https://access.worldpay.com
    description: Live - use for production traffic
tags:
  - name: Card Lookup
    description: Lookup card metadata by PAN, Network Token Number, or Worldpay token.
paths:
  /api/cardBin/panLookup:
    post:
      tags:
        - Card Lookup
      deprecated: false
      summary: Lookup BIN data for a card number or Worldpay token
      description: >-
        Returns card metadata for the supplied payment instrument. This is a
        read-only lookup with no side effects - safe to retry on network errors.
      operationId: getCardBinData
      security:
        - basicAuth: []
      x-ai-hints:
        when-to-call: >-
          Call before authorizing a payment when you need to know the card
          brand, funding type, or DCC eligibility, or when you need to verify
          AMLD5 compliance for a prepaid card, or to check AFT eligibility
          before initiating a Visa Direct pull payment.
        input-selection: >-
          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 (starts with
          https://.../tokens/).
        idempotency: >-
          This is a read-only lookup. Safe to retry on network errors. No side
          effects.
        response-fields:
          type: >-
            pan or networkToken. Indicates whether the card belongs to a
            tokenized issuer range.
          brand: >-
            Array of card brands. Co-branded cards return multiple values (e.g.
            ["visa","maestro"]).
          bin: >-
            Bank Identification Number extracted from the card. Use binLength to
            determine how many digits constitute the BIN for this card. Capped
            at 8 digits to protect PCI-sensitive data where the BIN length
            exceeds 8 digits.
          binLength: Number of digits in the BIN (typically 6 or 8).
          panLength: The length of the PAN, a value of 0 indicates a variable length.
          fundingType: >-
            credit | debit | prepaid | chargeCard | deferredDebit. Use to apply
            correct interchange category or surcharge logic.
          issuerName: Name of the card-issuing bank or financial institution.
          countryCode: >-
            ISO 3166-1 alpha-2 country code of the card issuer. Use for
            cross-border fee logic or geographic restrictions.
          currency: >-
            ISO 4217 alpha-3 default currency of the card. Use together with
            dccAllowed to determine whether to offer Dynamic Currency
            Conversion.
          dccAllowed: >-
            true if Dynamic Currency Conversion may be offered to the
            cardholder. Always check this flag before presenting a DCC offer.
          anonymousPrepaid: >-
            AMLD5 anonymous prepaid status. notPrepaidOrNonAnonymous means no
            AMLD5 concern. anonymousCompliant means anonymous prepaid but
            AMLD5-compliant. anonymousNonCompliant means anonymous and
            non-compliant - block if your compliance policy requires it. unknown
            means status could not be determined.
          category: commercial or consumer card classification.
          productId: >-
            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.
          productSubType: >-
            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.
          flexibleCredential.participating: >-
            true if the card participates in Visa Flexible Credential or
            Mastercard One Credential. Check this before applying flexible
            credential routing logic.
          flexibleCredential.deploymentModel: >-
            Visa only. managed means cardholder choices are held by Visa;
            selfServe means held by the issuer. Only present when
            flexibleCredential.participating is true.
          accountFundingTransactions.domestic: >-
            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.
          accountFundingTransactions.crossBorder: >-
            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.
      parameters:
        - $ref: '#/components/parameters/WPApiVersion'
      requestBody:
        description: >-
          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.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/request'
            examples:
              cardNumber:
                $ref: '#/components/examples/cardRequest'
              tokenHref:
                $ref: '#/components/examples/tokenHrefRequest'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/200'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '415':
          $ref: '#/components/responses/415'
        '500':
          $ref: '#/components/responses/500'
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        Base64-encode your username:password (issued by Worldpay) and send as
        `Authorization: Basic <token>` on every request.
  parameters:
    WPApiVersion:
      name: WP-Api-Version
      in: header
      description: API major version number. Must be 2.
      style: simple
      required: true
      schema:
        type: integer
        minimum: 2
        maximum: 2
      example: 2
  schemas:
    paymentInstrument:
      type: object
      description: >-
        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.
      discriminator:
        propertyName: type
        mapping:
          card: '#/components/schemas/cardInstrument'
          token: '#/components/schemas/tokenInstrument'
      oneOf:
        - $ref: '#/components/schemas/cardInstrument'
        - $ref: '#/components/schemas/tokenInstrument'
    cardInstrument:
      type: object
      description: >-
        Worldpay card lookup. Provide a Primary Account Number (PAN) or Network
        Token Number.
      required:
        - type
        - number
      properties:
        type:
          type: string
          description: Discriminator value identifying this as a card number lookup.
          enum:
            - card
        number:
          type: string
          description: >-
            Primary Account Number (PAN) or Network Token Number. Must be 12–19
            digits. Do not include spaces or dashes.
          example: '4444333322221111'
          minLength: 12
          maxLength: 19
          pattern: ^\d+$
    tokenInstrument:
      type: object
      description: >-
        Worldpay token lookup. Provide the token href URL returned when the
        token was originally created.
      required:
        - type
      properties:
        type:
          type: string
          description: Discriminator value identifying this as a token lookup.
          enum:
            - token
        href:
          type: string
          format: uri
          description: >-
            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:
      type: object
      required:
        - merchant
        - paymentInstrument
      properties:
        merchant:
          type: object
          description: >-
            Identifies the merchant entity for request routing. The entity value
            is assigned during on-boarding.
          required:
            - entity
          properties:
            entity:
              type: string
              description: >-
                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
              minLength: 1
              maxLength: 64
              pattern: ^(?! )[ \-A-Za-z0-9_!@#$%()*=.:;?\[\]{}~`\/+]*(?<! )$
        paymentInstrument:
          $ref: '#/components/schemas/paymentInstrument'
    brand:
      type: array
      description: >-
        Card brand(s). Co-branded cards return multiple values.<br><br> This
        list may grow as new schemes are added. Treat unrecognised values as
        valid strings and handle them gracefully rather than failing.
      items:
        type: string
        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
      example:
        - visa
    fundingType:
      type: string
      enum:
        - credit
        - debit
        - prepaid
        - chargeCard
        - deferredDebit
      description: >-
        Funding source of the card. Use to select the correct interchange
        category, apply surcharging rules, or restrict card acceptance by type.
      example: credit
    response:
      type: object
      description: >-
        Card metadata returned for a successful BIN lookup. Includes brand, BIN
        and BIN length, PAN length, funding type, issuer details, DCC
        eligibility, AMLD5 compliance status, card category, scheme product ID
        and sub-type, flexible credential participation, and Visa Direct Account
        Funding Transaction eligibility.
      properties:
        type:
          type: string
          enum:
            - pan
            - networkToken
          description: Indicates whether the card belongs to a tokenized issuer range.
          example: pan
        brand:
          $ref: '#/components/schemas/brand'
        bin:
          type: string
          description: >-
            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'
          maxLength: 8
        binLength:
          type: integer
          description: Number of digits in the BIN (typically 6 or 8).
          example: 6
        fundingType:
          $ref: '#/components/schemas/fundingType'
        issuerName:
          type: string
          description: Name of the card-issuing bank or financial institution.
          example: Bank of America
        countryCode:
          type: string
          description: >-
            ISO 3166-1 alpha-2 country code of the card issuer. Use for
            cross-border fee logic or geographic restrictions.
          example: US
        currency:
          type: string
          description: >-
            ISO 4217 alpha-3 default currency of the card. Use together with
            dccAllowed to determine whether to offer Dynamic Currency
            Conversion.
          example: USD
        dccAllowed:
          type: boolean
          description: >-
            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:
          type: string
          description: AMLD5 anonymous prepaid status.
          enum:
            - notPrepaidOrNonAnonymous
            - anonymousNonCompliant
            - anonymousCompliant
            - unknown
          x-enumDescriptions:
            notPrepaidOrNonAnonymous: No AMLD5 concern.
            anonymousCompliant: Anonymous prepaid but AMLD5-compliant.
            anonymousNonCompliant: >-
              Anonymous prepaid and non-compliant; block if your compliance
              policy requires it.
            unknown: Status could not be determined.
          example: notPrepaidOrNonAnonymous
        category:
          type: string
          enum:
            - commercial
            - consumer
          description: Whether the card is a commercial (business) or consumer card.
          example: consumer
    validationError:
      type: object
      required:
        - errorName
        - message
      properties:
        errorName:
          type: string
          description: 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
          example: fieldIsMissing
        message:
          type: string
          description: Human-readable description of the error and corrective action.
          example: Field at path must be present.
        jsonPath:
          type: string
          description: JSON path of the field that caused the validation error.
          example: $.merchant.entity
  examples:
    cardRequest:
      summary: Lookup by card number (PAN)
      value:
        merchant:
          entity: default
        paymentInstrument:
          type: card
          number: '4444333322221111'
    tokenHrefRequest:
      summary: Lookup by Worldpay token (href)
      value:
        merchant:
          entity: default
        paymentInstrument:
          type: token
          href: >-
            https://access.worldpay.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0NzI0NE1rdUtjMUFJdjYxVnlibWZuUT0ifQ
    cardResponse:
      summary: Card request response - tokenized issuer range
      value:
        type: networkToken
        brand:
          - visa
        bin: '491183'
        binLength: 6
        fundingType: debit
        issuerName: Bank of America
        countryCode: US
        currency: USD
        dccAllowed: false
        anonymousPrepaid: notPrepaidOrNonAnonymous
        category: consumer
    tokenResponse:
      summary: Worldpay token request response
      value:
        type: pan
        brand:
          - visa
        bin: '444433'
        binLength: 6
        fundingType: debit
        issuerName: Bank of America
        countryCode: US
        currency: USD
        dccAllowed: true
        anonymousPrepaid: notPrepaidOrNonAnonymous
        category: consumer
    validationError:
      summary: Request body failed schema validation
      value:
        errorName: bodyDoesNotMatchSchema
        message: A JSON body matching the expected schema must be provided.
        validationErrors:
          - errorName: fieldIsMissing
            message: Field at path must be present.
            jsonPath: $.merchant.entity
    headerError:
      summary: Required header missing
      value:
        errorName: headerIsMissing
        message: A valid header must be provided.
        headerName: Content-Type
    cardNotFound:
      summary: PAN not found in any BIN range
      value:
        errorName: cardNotFound
        message: The card number cannot be found in any BIN ranges.
    tokenNotFound:
      summary: Worldpay token not found
      value:
        errorName: tokenNotFound
        message: Token not found
  responses:
    '200':
      description: >-
        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, and Visa Direct Account
        Funding Transaction eligibility.
      headers:
        WP-CorrelationId:
          schema:
            type: string
          description: >-
            Unique request/response correlation ID. Include in support tickets
            when reporting issues.
          example: 4c195ce9-3dbd-4bc8-9c94-3d3393842323
        WP-Api-Version:
          schema:
            type: string
          description: Full API version (major.minor.patch) used to process the request.
          example: 2.0.20260327
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/response'
          examples:
            cardNumber:
              $ref: '#/components/examples/cardResponse'
            token:
              $ref: '#/components/examples/tokenResponse'
    '400':
      description: >-
        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.
      headers:
        WP-CorrelationId:
          schema:
            type: string
          description: Correlation ID for support.
          example: 4c195ce9-3dbd-4bc8-9c94-3d3393842323
        WP-Api-Version:
          schema:
            type: string
          description: Full API version (major.minor.patch) used to process the request.
          example: 2.0.20260327
      content:
        application/json:
          schema:
            title: error400
            type: object
            required:
              - errorName
              - message
            properties:
              errorName:
                type: string
                description: >
                  Machine-readable error code.

                  - `headerIsMissing` / `headerHasInvalidValue`: fix the named
                  header.

                  - `bodyIsEmpty` / `bodyIsNotJson` / `bodyDoesNotMatchSchema`:
                  fix the request body.
                enum:
                  - internalErrorOccurred
                  - headerIsMissing
                  - headerHasInvalidValue
                  - bodyIsEmpty
                  - bodyIsNotJson
                  - bodyDoesNotMatchSchema
                example: bodyDoesNotMatchSchema
              message:
                type: string
                description: Human-readable corrective action. Not for machine parsing.
                example: A JSON body matching the expected schema must be provided.
              validationErrors:
                type: array
                description: >-
                  Present when `errorName` is `bodyDoesNotMatchSchema`. Each
                  entry identifies a specific field error with a jsonPath
                  pointer.
                items:
                  $ref: '#/components/schemas/validationError'
              headerName:
                type: string
                description: >-
                  Present when `errorName` is `headerIsMissing` or
                  `headerHasInvalidValue`. Identifies which header needs to be
                  corrected.
                example: Content-Type
          examples:
            Validation Error:
              $ref: '#/components/examples/validationError'
            Header Error:
              $ref: '#/components/examples/headerError'
    '401':
      description: >-
        Unauthorized. The Authorization header is missing or contains invalid
        credentials. Do not retry automatically. Verify credentials and
        re-authenticate.
      headers:
        WP-CorrelationId:
          schema:
            type: string
          description: Correlation ID for support.
          example: 4c195ce9-3dbd-4bc8-9c94-3d3393842323
      content:
        application/json:
          schema:
            title: error401
            type: object
            required:
              - errorName
              - message
            properties:
              errorName:
                type: string
                enum:
                  - accessDenied
                description: >-
                  Machine-readable error code. Always `accessDenied` for 401
                  responses.
                example: accessDenied
              message:
                type: string
                description: Human-readable corrective action.
                example: Access to the requested resource has been denied
    '404':
      description: >-
        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.
      headers:
        WP-CorrelationId:
          schema:
            type: string
          description: Correlation ID for support.
          example: 4c195ce9-3dbd-4bc8-9c94-3d3393842323
        WP-Api-Version:
          schema:
            type: string
          description: Full API version (major.minor.patch) used to process the request.
          example: 2.0.20260327
      content:
        application/json:
          schema:
            title: error404
            type: object
            required:
              - errorName
              - message
            properties:
              errorName:
                type: string
                description: |
                  - `tokenNotFound`: the Worldpay token href is not recognized.
                  - `cardNotFound`: the PAN is not in any known BIN range.
                enum:
                  - cardNotFound
                  - tokenNotFound
                example: cardNotFound
              message:
                type: string
                description: Human-readable corrective action.
                example: The card number cannot be found in any BIN ranges.
          examples:
            Token Not Found:
              $ref: '#/components/examples/tokenNotFound'
            Card Not Found:
              $ref: '#/components/examples/cardNotFound'
    '415':
      description: >-
        Unsupported Media Type. Set Content-Type to application/json and retry
        immediately.
      headers:
        WP-CorrelationId:
          schema:
            type: string
          description: Correlation ID for support.
          example: 4c195ce9-3dbd-4bc8-9c94-3d3393842323
        WP-Api-Version:
          schema:
            type: string
          description: Full API version (major.minor.patch) used to process the request.
          example: 2.0.20260327
      content:
        application/json:
          schema:
            title: error415
            type: object
            required:
              - errorName
              - message
            properties:
              errorName:
                type: string
                description: >-
                  Machine-readable error code. Always `headerHasInvalidValue`
                  for 415 responses.
                enum:
                  - headerHasInvalidValue
                example: headerHasInvalidValue
              message:
                type: string
                description: Human-readable corrective action.
                example: A valid header must be provided.
              headerName:
                type: string
                description: Identifies which header is incorrect.
                example: Content-Type
    '500':
      description: >-
        Internal server error. The problem is on Worldpay's side. Retry with
        exponential back-off. If errors persist, contact support and provide
        WP-CorrelationId.
      headers:
        WP-CorrelationId:
          schema:
            type: string
          description: Correlation ID - include in all support tickets.
          example: 4c195ce9-3dbd-4bc8-9c94-3d3393842323
        WP-Api-Version:
          schema:
            type: string
          description: Full API version (major.minor.patch) used to process the request.
          example: 2.0.20260327
      content:
        application/json:
          schema:
            title: error500
            type: object
            required:
              - errorName
              - message
            properties:
              errorName:
                type: string
                description: >-
                  Machine-readable error code. Always `internalServerError` for
                  500 responses.
                enum:
                  - internalServerError
                example: internalServerError
              message:
                type: string
                description: Human-readable description of the server error.
                example: An internal server error occurred
