openapi: 3.0.3
info:
  title: BIN lookup service API
  description: This is an API reference for the BIN lookup service.
  version: 1.0.0
servers:
  - url: https://api-services.pxp.io/api/v1
    description: Production environment
  - url: https://api-services.test.pxp.io/api/v1
    description: Sandbox environment
paths:
  /bin-recognition/bin-range-lookup:
    post:
      summary: BIN lookup
      description: >-
        Perform a BIN (Bank Identification Number) lookup using a card's PAN
        (Primary Account Number). This will return high-level data about the
        card, such as the issuer, card type, and funding source. For more
        details, use the extended endpoint.
      operationId: bin-lookup
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BinLookupRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BinLookupResponse'
              examples:
                BIN lookup response:
                  value:
                    fromBin: 441690000000000000
                    toBin: 441691000000000000
                    cardScheme: Visa
                    issuerName: UCBF
                    issuerCountryCode: USD
                    issuerMemberId: Test Bank
                    cardType: Visa
                    fundingSource: Credit
                    ownerType: Individual
                    currencyCode: USD
                    binLength: 8
                    gamingCreditSupported: true
                    productName: Debit Plus
                    productTarget: USA
                    isAnonymousProduct: true
                    rangeType: none
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_400'
        '401':
          description: Unauthorised
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_401'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_403'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_404'
        '413':
          description: Payload too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_413'
        '422':
          description: Unprocessable entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_422'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_500'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
  /bin-recognition/bin-range-lookup/extended:
    post:
      summary: BIN lookup (extended)
      description: >-
        Perform an extended BIN (Bank Identification Number) lookup using a
        card's PAN (Primary Account Number). This will return detailed
        information about the card, including the issuer, card type, and funding
        source. For high-level data, use the standard endpoint.
      operationId: bin-lookup-extended
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BinLookupRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BinLookupExtendedResponse'
              examples:
                BIN lookup extended response:
                  value:
                    fromBin: 441690000000000000
                    toBin: 441691000000000000
                    cardScheme: Visa
                    issuerName: UCBF
                    issuerCountryCode: USD
                    issuerMemberId: Test Bank
                    cardType: Visa
                    fundingSource: Credit
                    ownerType: Individual
                    currencyCode: USD
                    binLength: 8
                    gamingCreditSupported: true
                    productName: Debit Plus
                    productTarget: USA
                    isAnonymousProduct: true
                    rangeType: none
                    extendedData:
                      issuerBin: 441690
                      issuerName: Bank of America
                      binLength: 6
                      minPanLength: 15
                      maxPanLength: 15
                      cashbackEligibility: 'N'
                      tokenIndicator: 'N'
                      productRegulationValue: NA
                      lastUpdate: '2007-01-29'
                      cpsOption: 'N'
                      productType: Commercial
                      productTypeId: Commercial
                      countryCodeNumeric: '840'
          description: Success
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_400'
        '401':
          description: Unauthorised
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_401'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_403'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_404'
        '413':
          description: Payload too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_413'
        '422':
          description: Unprocessable entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_422'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_500'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
components:
  schemas:
    BinLookupRequest:
      type: object
      required:
        - primaryAccountNumber
      properties:
        primaryAccountNumber:
          type: string
          description: >-
            The unique number assigned to a payment card, such as a credit or
            debit card. This number typically contains 16 digits, structured in
            a specific format to indicate the card network, issuing bank, and
            account number.
          example: '4111111111111111'
      description: >-
        Request payload to perform a BIN (Bank Identification Number) lookup.
        The essential input for this request is the `primaryAccountNumber`,
        which should be a valid card number format.
    BinLookupResponse:
      type: object
      properties:
        fromBin:
          type: integer
          format: int64
          example: 41110000
          description: >-
            The starting number of the BIN range. This information helps
            businesses identify the first number in a series of card numbers
            issued by a single card issuer, aiding in card validation and fraud
            detection.
        toBin:
          type: integer
          format: int64
          example: 41112099
          description: >-
            The ending number of the BIN range. This detail is crucial for
            determining the scope of card numbers associated with a specific
            card issuer, enabling accurate card verification.
        issuerName:
          type: string
          description: >-
            The name of the financial institution that issued the card. This
            information is essential for transaction authentication and
            understanding the issuer's reputation and reliability.
        issuerCountryCode:
          type: string
          example: '840'
          maxLength: 3
          minLength: 3
          description: >-
            The country code of the card issuer, in ISO 3166-1 alpha-3 format.
            This is important for you to manage cross-border transactions,
            comply with regional regulations, and understand the geographical
            distribution of their customer base.
        issuerMemberId:
          type: string
          example: BofA-V1234567
          description: >-
            A unique identifier for the card issuer member. This aids in
            distinguishing between different entities within the same financial
            network for advanced transaction processing.
        cardScheme:
          example: Visa
          pattern: ^[A-Z]
          type: string
          description: >-
            The card network (e.g., Visa, MasterCard). This is essential for
            processing transactions according to the specific card scheme's
            guidelines and for compatibility with payment gateways.
        fundingSource:
          type: string
          enum:
            - Credit
            - Debit
            - Prepaid
          example: Credit
          description: >-
            The type of funding for the card (e.g., credit, debit). This can
            help you tailor payment options and understand the customer's
            spending behaviour.
        ownerType:
          type: string
          enum:
            - Consumer
            - Commercial
          description: >-
            The type of owner. Identifies if the card is owned by an consumer or
            a commercial entity. This is useful for personalisation of services
            and risk management in transaction processing.
        currencyCode:
          type: string
          example: EUR
          maxLength: 3
          minLength: 3
          description: The currency associated with the card, in ISO 4217 format.
        binLength:
          type: number
          example: 8
          description: >-
            The length of the BIN number. This information is vital for
            validating the format of the card number and ensuring compliance
            with industry standards.
        gamingCreditSupported:
          type: boolean
          nullable: true
          description: >-
            Whether the card supports gaming credits. This is particularly
            relevant for businesses in the gaming industry for payment option
            compatibility.
        productName:
          type: string
          example: Debit Plus
          description: The name of the product.
        productTarget:
          type: string
          example: USA
          description: The target market or region for the product.
        isAnonymousProduct:
          type: boolean
          example: true
          nullable: true
          description: Whether the product is anonymous.
        rangeType:
          type: string
          example: none
          description: The type of range associated with the product.
      description: Standard response for BIN lookup.
    BinLookupExtendedResponse:
      allOf:
        - $ref: '#/components/schemas/BinLookupResponse'
        - type: object
          description: Extended response for BIN lookup, inheriting from BinLookupResponse.
          properties:
            extendedData:
              type: object
              description: Additional details about the Bank Identification Number (BIN).
              properties:
                issuerBin:
                  type: string
                  example: '441690'
                  description: The Bank Identification Number (BIN) issued by the bank.
                issuerName:
                  type: string
                  example: Bank of America
                  description: The name of the bank that issued the card.
                binLength:
                  type: number
                  example: 6
                  description: The length of the Bank Identification Number (BIN).
                minPanLength:
                  type: number
                  example: 15
                  description: The minimum length of the Primary Account Number (PAN).
                maxPanLength:
                  type: number
                  example: 15
                  description: The maximum length of the Primary Account Number (PAN).
                cashbackEligibility:
                  type: string
                  maxLength: 1
                  minLength: 1
                  example: 'N'
                  description: Whether cashback is eligible (`Y` or `N`).
                tokenIndicator:
                  type: string
                  example: 'N'
                  maxLength: 1
                  minLength: 1
                  description: Whether a token is used (`Y` or `N`).
                productRegulationValue:
                  type: string
                  example: NA
                  description: The regulatory value associated with the product, if any.
                lastUpdate:
                  type: string
                  example: '2007-01-29'
                  description: The date of the last update to this information.
                cpsOption:
                  type: string
                  maxLength: 1
                  minLength: 1
                  example: 'N'
                  description: >-
                    Whether the CPS (Card Present Service) option is enabled
                    (`Y` or `N`).
                productType:
                  type: string
                  example: Commercial
                  description: The product type.
                productTypeId:
                  type: string
                  example: Commercial
                  description: The ID associated with the product type.
                countryCodeNumeric:
                  type: string
                  maxLength: 3
                  minLength: 3
                  example: '840'
                  description: >-
                    The numeric country code for the country where the product
                    is issued, in ISO 3166-1 alpha-3 format.
    inline_response_400:
      properties:
        correlationId:
          $ref: '#/components/schemas/correlationId'
        details:
          $ref: '#/components/schemas/details'
        errorCode:
          $ref: '#/components/schemas/errorCode'
        errorReason:
          $ref: '#/components/schemas/errorReason'
      type: object
    inline_response_401:
      properties:
        correlationId:
          $ref: '#/components/schemas/correlationId'
        details:
          $ref: '#/components/schemas/details'
        errorCode:
          $ref: '#/components/schemas/errorCode'
        errorReason:
          $ref: '#/components/schemas/errorReason'
      type: object
    inline_response_403:
      properties:
        correlationId:
          $ref: '#/components/schemas/correlationId'
        details:
          $ref: '#/components/schemas/details'
        errorCode:
          $ref: '#/components/schemas/errorCode'
        errorReason:
          $ref: '#/components/schemas/errorReason'
      type: object
    inline_response_404:
      properties:
        correlationId:
          $ref: '#/components/schemas/correlationId'
        details:
          $ref: '#/components/schemas/details'
        errorCode:
          $ref: '#/components/schemas/errorCode'
        errorReason:
          $ref: '#/components/schemas/errorReason'
      type: object
    inline_response_413:
      properties:
        correlationId:
          $ref: '#/components/schemas/correlationId'
        details:
          $ref: '#/components/schemas/details'
        errorCode:
          $ref: '#/components/schemas/errorCode'
        errorReason:
          $ref: '#/components/schemas/errorReason'
      type: object
    inline_response_422:
      properties:
        correlationId:
          $ref: '#/components/schemas/correlationId'
        details:
          $ref: '#/components/schemas/details'
        errorCode:
          $ref: '#/components/schemas/errorCode'
        errorReason:
          $ref: '#/components/schemas/errorReason'
      type: object
    inline_response_500:
      properties:
        correlationId:
          $ref: '#/components/schemas/correlationId'
        details:
          $ref: '#/components/schemas/details'
        errorCode:
          $ref: '#/components/schemas/errorCode'
        errorReason:
          $ref: '#/components/schemas/errorReason'
      type: object
    error:
      properties:
        correlationId:
          type: string
        details:
          items: {}
          type: array
        errorCode:
          type: string
        errorReason:
          type: string
      required:
        - correlationId
        - errorCode
        - errorReason
    correlationId:
      description: This is a unique reference generated by the PSP to locate the error.
      example: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
      required:
        - correlationId
      type: string
    details:
      items: {}
      type: array
    errorCode:
      description: The error code returned for the operation.
      example: This is the error code returned for the operation.
      required:
        - errorCode
      type: string
    errorReason:
      description: The error reason returned for the operation.
      example: This is the error reason returned for the operation.
      required:
        - errorReason
      type: string
