openapi: 3.0.1
info:
  title: Card BIN Data
  description: |-
    Retrieve detailed information about a card.


      __Header__
    ```
        Authorization: {your_credentials}
        Content-Type: application/json
        WP-Api-Version: 1
    ```
        Replace `{your_credentials}` with your base64-encoded Basic Auth username and password given to you by your Implementation Manager.
        <br><br>
      You **must** use the `Authorization` header for any request you send to our Card BIN Data API. <br /><br />   __DNS whitelisting__

        Whitelist the following URLs:
        * `https://try.access.worldpay.com/`
        * `https://access.worldpay.com/`

        Please ensure you use DNS whitelisting, not explicit IP whitelisting.
        When you make a request within Access Worldpay, you should always cache the response returned.
     
  version: '1'
  x-metadata:
    category:
      - Card BIN
    business:
      - Enterprise
    catalog-list: true
    generated: false
servers:
  - url: https://try.access.worldpay.com/api
    description: Try
  - url: https://access.worldpay.com/api
    description: Live
security:
  - BasicAuth: []
paths:
  /cardBin/panLookup:
    post:
      summary: Get BIN data
      description: Returns card BIN data for the card number or Worldpay token supplied.
      operationId: panlookup
      parameters:
        - $ref: '#/components/parameters/wpApiVersion'
      requestBody:
        description: Lookup details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/request'
            examples:
              cardNumber:
                $ref: '#/components/examples/cardRequest'
              token:
                $ref: '#/components/examples/tokenRequest'
        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'
      deprecated: false
    parameters: []
components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
  parameters:
    wpApiVersion:
      name: WP-Api-Version
      in: header
      description: The API version.
      style: simple
      required: true
      schema:
        type: integer
        minimum: 1
      example: 1
  schemas:
    cardNumber:
      type: object
      title: cardNumber
      properties:
        merchant:
          $ref: '#/components/schemas/merchant'
        cardNumber:
          type: string
          description: >-
            The Primary Account Number (PAN). <br> Supports full card numbers
            and network tokens.
          example: '4444333322221111'
          pattern: ^\d{12,19}$
      required:
        - merchant
        - cardNumber
    token:
      type: object
      title: token
      properties:
        merchant:
          $ref: '#/components/schemas/merchant'
        token:
          type: string
          description: Worldpay token href
          example: >-
            https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0NzI0NE1rdUtjMUFJdjYxVnlibWZuUT0ifQ
      required:
        - merchant
        - token
    entity:
      type: string
      description: >-
        Used to route the request in Access Worldpay, created as part of
        on-boarding.
      example: default
      minLength: 1
      maxLength: 64
      pattern: ^[A-Za-z0-9]*$
    merchant:
      type: object
      description: An object that contains information about the merchant.
      properties:
        entity:
          $ref: '#/components/schemas/entity'
      required:
        - entity
    request:
      type: object
      description: Lookup details.
      oneOf:
        - $ref: '#/components/schemas/cardNumber'
        - $ref: '#/components/schemas/token'
    response:
      type: object
      description: Successful response with BIN details.
      properties:
        type:
          type: string
          enum:
            - pan
            - networkToken
          description: The type of account number provided.
          example: pan
        brand:
          type: array
          items:
            type: string
            enum:
              - airplus
              - allstar
              - amex
              - argencard
              - aurore
              - bc
              - cabal
              - carnet
              - cartesBancaires
              - cencosud
              - unionPay
              - coopeplus
              - credimas
              - dankort
              - diners
              - discover
              - mastercard
              - eftposAU
              - elo
              - hana
              - hipercard
              - hyundai
              - italcred
              - jcb
              - keyfuels
              - kookmin
              - lotte
              - maestro
              - naranja
              - nativa
              - nevada
              - nexo
              - nonghyup
              - overdrive
              - samsung
              - sears
              - shinhan
              - sorocred
              - supercharge
              - tarjeta
              - troy
              - uatp
              - visa
              - gecapital
              - ikea
              - ncp
              - newday
              - interlink
              - interac
              - jeanie
              - nyce
              - pavd
              - pulse
              - shazam
              - starAccess
              - star
              - accel
              - affn
              - ath
              - culiance
          example: visa
          description: >-
            Brand of the card. For co-branded cards multiple brands are
            returned.
        bin:
          type: string
          description: Bank Identification Number.
          example: '444422'
        binLength:
          type: integer
          description: Length of the BIN.
          example: 6
        fundingType:
          type: string
          enum:
            - credit
            - debit
            - prepaid
            - chargeCard
            - deferredDebit
            - unknown
          description: Funding source of the card.
          example: credit
        issuerName:
          type: string
          description: Card issuer name.
          example: Bank of America
        countryCode:
          type: string
          description: Card issuer country in ISO alpha-2 format or unknown.
          example: US
        currency:
          type: string
          description: Currency of the card in ISO alpha-3 format.
          example: USD
        dccAllowed:
          type: boolean
          description: Sets whether Dynamic Currency Conversion (DCC) is permitted.
          example: true
        anonymousPrepaid:
          type: string
          enum:
            - anonymousNonCompliant
            - anonymousCompliant
            - notPrepaidOrNonAnonymous
            - unknown
          description: Anonymous prepaid program and AMLD5 compliance.
          example: notPrepaidOrNonAnonymous
        category:
          type: string
          enum:
            - commercial
            - consumer
          description: The card category.
          example: consumer
        multipleAccountAccess:
          type: string
          enum:
            - managed
            - selfServe
            - notParticipating
            - notSupported
          description: >-
            Participation in Visa multiple-account access. Managed cardholder
            choices are stored with Visa and self-serve with the issuer.
          example: managed
    validationError:
      type: object
      required:
        - errorName
        - message
      properties:
        errorName:
          type: string
          description: >-
            A machine and human readable error type for clarity and semantic
            understanding of the error.
          enum:
            - fieldIsMissing
            - fieldMustBeString
            - fieldMustBeNumber
            - fieldMustBeInteger
            - fieldMustBeBoolean
            - fieldMustBeObject
            - fieldMustBeArray
            - fieldIsNull
            - fieldIsEmpty
            - fieldHasInvalidValue
            - fieldIsNotAllowed
            - numberIsTooSmall
            - integerIsTooLarge
            - stringIsTooShort
            - stringIsTooLong
            - stringFailedRegexCheck
            - panFailedLuhnCheck
            - dateHasInvalidFormat
          example: fieldIsNotAllowed
        message:
          type: string
          description: >-
            A human readable message giving a corrective action for the error. 
            *This is not for machine consumption*.
          example: Field at path is not allowed.
        jsonPath:
          type: string
          description: >-
            This field represents the JSON path of the element within the
            request body associated with the error.
          example: $.transactionRef
  examples:
    cardRequest:
      value:
        merchant:
          entity: default
        cardNumber: '4444333322221111'
    tokenRequest:
      value:
        merchant:
          entity: default
        token: >-
          https://access.worldpay.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0NzI0NE1rdUtjMUFJdjYxVnlibWZuUT0ifQ
    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
        multipleAccountAccess: managed
    validationError:
      value:
        errorName: bodyDoesNotMatchSchema
        message: A JSON body matching the expected schema must be provided.
        validationErrors:
          - errorName: fieldIsNotAllowed
            message: Field at path is not allowed.
            jsonPath: $.transactionRef
    headerError:
      value:
        errorName: headerIsMissing
        message: A valid header must be provided.
        headerName: Content-Type
    cardNotFound:
      value:
        errorName: cardNotFound
        message: The card number cannot be found in any BIN ranges.
    tokenNotFound:
      value:
        errorName: tokenNotFound
        message: Token not found
  responses:
    '200':
      description: Request Successful
      headers:
        WP-CorrelationId:
          schema:
            type: string
          description: >-
            Generated identifier for the request and response. When contacting
            support please include this.
          example: 4c195ce9-3dbd-4bc8-9c94-3d3393842323
        WP-Api-Version:
          schema:
            type: string
          description: >-
            The complete API Version is returned in the WP-Api-Version HPP
            Header. It contains the Major, Minor and Patch details of API
            Version.
          example: 1.1.20240411
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/response'
          examples:
            cardNumber:
              $ref: '#/components/examples/response'
            token:
              $ref: '#/components/examples/response'
    '400':
      description: Bad Request
      headers:
        WP-CorrelationId:
          schema:
            type: string
          description: >-
            Generated identifier for the request and response. When contacting
            support please include this.
          example: 4c195ce9-3dbd-4bc8-9c94-3d3393842323
        WP-Api-Version:
          schema:
            type: string
          description: >-
            The complete API Version is returned in the WP-Api-Version HPP
            Header. It contains the Major, Minor and Patch details of API
            Version.
          example: 1.1.20240411
      content:
        application/json:
          examples:
            Validation Error:
              $ref: '#/components/examples/validationError'
            Header Error:
              $ref: '#/components/examples/headerError'
          schema:
            title: error400
            type: object
            required:
              - errorName
              - message
            properties:
              errorName:
                type: string
                enum:
                  - internalErrorOccurred
                  - headerIsMissing
                  - headerHasInvalidValue
                  - bodyIsEmpty
                  - bodyIsNotJson
                  - bodyDoesNotMatchSchema
                description: >-
                  A machine and human readable error type for clarity and
                  semantic understanding of the error.
                example: bodyDoesNotMatchSchema
              message:
                type: string
                description: >-
                  A human readable message giving a corrective action for the
                  error.  *This is not for machine consumption*.
                example: A JSON body matching the expected schema must be provided.
              validationErrors:
                type: array
                description: >-
                  If there were field validation errors, they will be collected
                  in this array.
                items:
                  $ref: '#/components/schemas/validationError'
              headerName:
                type: string
                description: >-
                  If the header is missing or does not contain an expected
                  value, this field will be populated with the incorrect header
                  name.
                example: Content-Type
    '401':
      description: Client is not authorized due to missing or invalid Authorization header.
      headers:
        WP-CorrelationId:
          schema:
            type: string
          description: >-
            Generated identifier for the request and response. When contacting
            support please include this.
          example: 4c195ce9-3dbd-4bc8-9c94-3d3393842323
      content:
        application/json:
          schema:
            title: error401
            type: object
            required:
              - errorName
              - message
            properties:
              errorName:
                type: string
                description: >-
                  A machine and human readable error type for clarity and
                  semantic understanding of the error.
                example: accessDenied
              message:
                type: string
                description: >-
                  A human readable message giving a corrective action for the
                  error.  *This is not for machine consumption*.
                example: Access to the requested resource has been denied
    '404':
      description: Not Found
      headers:
        WP-CorrelationId:
          schema:
            type: string
          description: >-
            Generated identifier for the request and response. When contacting
            support please include this.
          example: 4c195ce9-3dbd-4bc8-9c94-3d3393842323
        WP-Api-Version:
          schema:
            type: string
          description: >-
            The complete API Version is returned in the WP-Api-Version HPP
            Header. It contains the Major, Minor and Patch details of API
            Version.
          example: 1.1.20240411
      content:
        application/json:
          examples:
            Token Not Found:
              $ref: '#/components/examples/tokenNotFound'
            Card Not Found:
              $ref: '#/components/examples/cardNotFound'
          schema:
            title: error404
            type: object
            required:
              - errorName
              - message
            properties:
              errorName:
                type: string
                enum:
                  - tokenNotFound
                  - cardNotFound
                description: >-
                  A machine and human readable error type for clarity and
                  semantic understanding of the error.
                example: cardNotFound
              message:
                type: string
                description: >-
                  A human readable message giving a corrective action for the
                  error.  *This is not for machine consumption*.
                example: The card number cannot be found in any BIN ranges.
    '415':
      description: Invalid content-type HTTP header
      headers:
        WP-CorrelationId:
          schema:
            type: string
          description: >-
            Generated identifier for the request and response. When contacting
            support please include this.
          example: 4c195ce9-3dbd-4bc8-9c94-3d3393842323
        WP-Api-Version:
          schema:
            type: string
          description: >-
            The complete API Version is returned in the WP-Api-Version HPP
            Header. It contains the Major, Minor and Patch details of API
            Version.
          example: 1.1.20240411
      content:
        application/json:
          schema:
            title: error415
            type: object
            required:
              - errorName
              - message
            properties:
              errorName:
                type: string
                description: >-
                  A machine and human readable error type for clarity and
                  semantic understanding of the error.
                example: headerHasInvalidValue
              message:
                type: string
                description: >-
                  A human readable message giving a corrective action for the
                  error.  *This is not for machine consumption*.
                example: A valid header must be provided.
              headerName:
                type: string
                description: >-
                  If the header is missing or does not contain an expected
                  value, this field will be populated with the incorrect header
                  name.
                example: Content-Type
    '500':
      description: An error occurred processing the request on our side.
      headers:
        WP-CorrelationId:
          schema:
            type: string
          description: >-
            Generated identifier for the request and response. When contacting
            support please include this.
          example: 4c195ce9-3dbd-4bc8-9c94-3d3393842323
        WP-Api-Version:
          schema:
            type: string
          description: >-
            The complete API Version is returned in the WP-Api-Version HPP
            Header. It contains the Major, Minor and Patch details of API
            Version.
          example: 1.1.20240411
      content:
        application/json:
          schema:
            title: error500
            type: object
            required:
              - errorName
              - message
            properties:
              errorName:
                type: string
                enum:
                  - internalServerError
                description: >-
                  A machine and human readable error type for clarity and
                  semantic understanding of the error.
                example: internalServerError
              message:
                type: string
                description: >-
                  A human readable message giving a corrective action for the
                  error.  *This is not for machine consumption*.
                example: An internal server error occurred
