Mastercard
Mastercard Bin API

The Bin API from Mastercard — 2 operation(s) for bin.
Documentation GitHub OpenAPI
OpenAPI Specification

swagger: '2.0'
info:
  title: Mastercard Bill Payment Validator Account Opening Bin API
  description: This service is provided on behalf of the Mastercard Remote Payment and Presentment (RPPS) Bill Payment Processing Network, which supports consumer to business "push" bill payments (i.e. those which are not funded by debit/credit card transactions) in the U.S.
  version: '1.0'
  x-artifactId: billpay-api
  contact:
    name: Bill Pay Development Support
    email: Bill_Pay_Development_Support@mastercard.com
host: sandbox.api.mastercard.com
basePath: /billpayAPI/v1
schemes:
- https
consumes:
- application/json
produces:
- application/json
tags:
- name: Bin
paths:
  /bin-ranges:
    post:
      summary: Get BIN Account Ranges
      description: Retrieve a list of all account range information or filtered results based on search criteria applied
      tags:
      - Bin
      parameters:
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/Size'
      - $ref: '#/components/parameters/Sort'
      requestBody:
        $ref: '#/components/requestBodies/BinResourceSearchRequest'
      operationId: get-bin-resources
      responses:
        '200':
          $ref: '#/components/responses/BinResourceResponse'
        '400':
          $ref: '#/components/responses/BadRequestErrorResponse'
        '401':
          $ref: '#/components/responses/NotAuthorizedErrorResponse'
        '403':
          $ref: '#/components/responses/ForbiddenErrorResponse'
        '404':
          $ref: '#/components/responses/NotFoundErrorResponse'
  /bin-ranges/account-searches:
    post:
      tags:
      - Bin
      summary: Search by 6 - 8 Digit BINs, or up to the 11th digit of an account range
      description: Find a specific account range by providing an 8 digit BIN, or up to 11 digits of an account range
      requestBody:
        $ref: '#/components/requestBodies/BinResourceSearchByAccountRangeRequest'
      operationId: search-by-account-range-resources
      responses:
        '200':
          $ref: '#/components/responses/AccountRangeSearchResponse'
        '400':
          $ref: '#/components/responses/BadRequestErrorResponse'
        '401':
          $ref: '#/components/responses/NotAuthorizedErrorResponse'
        '403':
          $ref: '#/components/responses/ForbiddenErrorResponse'
        '404':
          $ref: '#/components/responses/NotFoundErrorResponse'
components:
  examples:
    SearchBINsExample:
      value:
        currentPageNumber: 1
        currentPageSize: 2
        totalPages: 76
        totalRecords: 152
        items:
        - lowAccountRange: 2229293100000000000
          highAccountRange: 2229293200000000000
          binNum: '22292931'
          binLength: 8
          acceptanceBrand: MCC
          ica: '00000023460'
          customerName: TRIPLINK INTERNATIONAL CO.,LIMITED
          country:
            code: '372'
            alpha3: IRL
            name: Ireland
          localUse: false
          authorizationOnly: false
          productCode: MCO
          productDescription: MASTERCARD CORPORATE
          governmentRange: false
          nonReloadableIndicator: false
          anonymousPrepaidIndicator: N
          cardholderCurrencyIndicator: C
          billingCurrencyDefault: USD
          programName: Optum Health
          vertical: HEALTHCARE
          fundingSource: CREDIT
          consumerType: CORPORATE
          smartDataEnabled: false
          affiliate: California Community Bank
        - lowAccountRange: 2184410000000000000
          highAccountRange: 2184420000000000000
          binNum: '218441'
          binLength: 6
          acceptanceBrand: MSI
          ica: '00000002535'
          customerName: CITIBANK N.A.
          country:
            code: '840'
            alpha3: USA
            name: United States of America
          localUse: false
          authorizationOnly: false
          productCode: MSI
          productDescription: MAESTRO
          governmentRange: false
          nonReloadableIndicator: false
          anonymousPrepaidIndicator: N
          cardholderCurrencyIndicator: D
          billingCurrencyDefault: USD
          programName: Optum Health
          vertical: HEALTHCARE
          fundingSource: DEBIT
          consumerType: CONSUMER
          smartDataEnabled: true
          affiliate: null
    UnauthorizedExample:
      value:
        Errors:
          Error:
          - Source: BINTABLE_API
            ReasonCode: UNAUTHORIZED
            Description: We couldn't recognize you
            Recoverable: false
            Details: 'Full authentication is required to access this resource. See also: https://mstr.cd/31YcrTi'
    BINSuccessExample:
      description: Individual Mastercard BIN data
      value:
      - lowAccountRange: 2229326100000000000
        highAccountRange: 2229326200000000000
        binNum: '22292931'
        binLength: 8
        acceptanceBrand: MCC
        ica: '00000023460'
        customerName: TRIPLINK INTERNATIONAL CO.,LIMITED
        country:
          code: '372'
          alpha3: IRL
          name: Ireland
        localUse: false
        authorizationOnly: false
        productCode: MCO
        productDescription: MASTERCARD CORPORATE
        governmentRange: false
        nonReloadableIndicator: false
        anonymousPrepaidIndicator: N
        programName: null
        vertical: null
        fundingSource: DEBIT
        consumerType: CONSUMER
        cardholderCurrencyIndicator: C
        billingCurrencyDefault: USD
        smartDataEnabled: false
        affiliate: California Community Bank
    BadRequestExample:
      value:
        Errors:
          Error:
          - Source: BINTABLE_API
            ReasonCode: BAD_REQUEST
            Description: Not all mandatory parameters are supplied or sent incorrectly.
            Recoverable: false
            Details: The value of parameter 'sort' is invalid.
    BINNotFoundExample:
      value:
        Errors:
          Error:
          - Source: BINTABLE_API
            ReasonCode: NOT_FOUND
            Description: Invalid BIN format, please ensure there are no spaces used
            Recoverable: false
            Details: BIN '131 840' doesn't exist
    ForbiddenExample:
      value:
        Errors:
          Error:
          - Source: BINTABLE_API
            ReasonCode: PERMISSION_DENIED
            Description: You don't seem authorized to do that
            Recoverable: false
            Details: The resource was processed and can't be updated anymore
  schemas:
    BinResourcePage:
      type: object
      properties:
        currentPageNumber:
          description: current page indicator
          type: integer
          minimum: 1
          maximum: 100000000
          example: 10
        currentPageSize:
          description: total elements in current page
          type: integer
          minimum: 1
          maximum: 100000000
          example: 5000
        totalPages:
          description: total pages available with size of page
          type: integer
          minimum: 1
          maximum: 100000000
          example: 5000
        totalItems:
          description: total elements in the database
          type: integer
          format: int64
          minimum: 1
          maximum: 100000000
          example: 6000
        items:
          description: The items
          type: array
          items:
            $ref: '#/components/schemas/BinResource'
    SearchCriteria:
      type: object
      required:
      - key
      - value
      properties:
        key:
          type: string
          description: The key within the JSON response that you would like to filter the results on. For example, to search by customer name set this as 'customerName'. You can also filter on almost any other keys in the data such as 'ica', 'country.code', 'country.alpha3', 'country.name', 'productCode', and 'productDescription'. The exception to this is the governmentRange key, which you cannot filter on.
          minLength: 3
          maxLength: 25
          example: customerName
        value:
          type: string
          description: The value of the key that you would like to filter the results on. For example, provide the name of a customer to search with here such as 'CITIBANK EUROPE PUBLIC LIMITED COMPANY' when filtering on the 'customerName' key. When filtering on another key provide an appropriate value, for example 'FRA' when filtering the 'country.alpha3' key.
          minLength: 1
          maxLength: 200
          example: CITIBANK EUROPE PUBLIC LIMITED COMPANY
    ErrorResponse:
      type: object
      required:
      - Errors
      properties:
        Errors:
          type: object
          required:
          - Error
          properties:
            Error:
              $ref: '#/components/schemas/Errors'
    BinResourceArray:
      type: array
      items:
        $ref: '#/components/schemas/BinResource'
    SearchByAccountRange:
      type: object
      required:
      - accountRange
      properties:
        accountRange:
          type: number
          description: The first 8 digits of a card number (without spaces), or up to the 11th digit of an account range
          minimum: 10000000
          maximum: 99999999999
          example: 22293261
    Errors:
      type: array
      minItems: 1
      items:
        $ref: '#/components/schemas/Error'
    BinResource:
      type: object
      properties:
        lowAccountRange:
          type: integer
          description: The lowest possible account number that would be identified within this authorization account range.
          minimum: 1111111111111111200
          maximum: 10000000000000000000
          example: 5132625400000000000
        highAccountRange:
          type: integer
          description: The highest possible account number that would be identified within this authorization account range.
          minimum: 1111111111111111200
          maximum: 10000000000000000000
          example: 5132625500000000000
        binNum:
          type: string
          description: 'The RAW BIN assigned to the issuer. Can be the value UNKNOWN when the BIN of the account range has not been provdied. '
          minLength: 6
          maxLength: 11
          example: '222899'
        binLength:
          type: integer
          description: The length of the BIN, will be either 6 or 8 (or 0 when the binNumber is unknown)
          minimum: 0
          maximum: 8
          example: 6
        acceptanceBrand:
          type: string
          description: 'Mastercard or other proprietary service mark. Valid values: " MCC (Mastercard�) " DMC (Debit Mastercard�) " M (Maestro�) " CIR (Cirrus�) " PVL (Private Label)'
          minLength: 1
          maxLength: 3
          example: MCC
        ica:
          type: string
          description: Mastercard ICA number associated with this authorization account range in right justified, leading zeros format.
          minLength: 1
          maxLength: 11
          example: '1111'
        customerName:
          type: string
          description: The customer name.
          minLength: 0
          maxLength: 300
          example: FISERV SOLUTIONS
        country:
          description: Country of origin for the issuer of the account range. Valuable in e-commerce fraud management to help detect inconsistencies between the IP address of the originating purchase and the cardholder billing address that may warrant additional analysis. When used in conjunction with the Local Use flag, a merchant can identify when a card is being used outside of its intended allowed area of use.
          type: object
          properties:
            code:
              type: string
              description: Licensed Country Code of the account range in ISO code format
              example: 280
              minLength: 3
              maxLength: 3
            alpha3:
              type: string
              description: Licensed Country Code of the account range in Alpha-3 format
              example: USA
              minLength: 3
              maxLength: 3
            name:
              description: Licensed Country name of the account range in a human readable format
              example: United States of America
              type: string
              minLength: 1
              maxLength: 200
        localUse:
          type: boolean
          description: Indicates whether cards within the authorization account range may be used outside of the country of issuance. true = The range is intended for domestic use only. false = The range is intended for use outside the country of issuance.
          example: true
        authorizationOnly:
          type: boolean
          description: Indicates account range is only valid for authorization processing. true = Authorization only. false = Authorization and Clearing. Authorization only account ranges are used for promotional contexts in merchants such as branded rewards cards.
          example: true
        productCode:
          type: string
          description: The Brand Product Code associated with the account range.
          minLength: 1
          maxLength: 3
          example: MPM
        productDescription:
          type: string
          description: The description of the Brand Product Code named above.
          minLength: 1
          maxLength: 200
          example: MASTERCARD PREPAID CONSUMER INCENTIVE
        governmentRange:
          type: boolean
          description: Identifies if an account range product is a government product.
          example: true
        nonReloadableIndicator:
          type: boolean
          description: 'Indicates whether the account range is registered as a non-reloadable prepaid card program. Valid values: true = non-reloadable prepaid program false = reloadable prepaid program or non-prepaid program'
          example: false
        anonymousPrepaidIndicator:
          type: string
          description: "Valid values:\n  A = Anonymous prepaid program and not AMLDS compliant\n  E = Anonymous prepaid program and AMLDS compliant\n  N = Not prepaid or non-anonymous prepaid program/default\n  U = Unknown"
          minLength: 1
          maxLength: 1
          pattern: ^[A|E|N|U]{1}$
          example: A
        cardholderCurrencyIndicator:
          type: string
          description: "Indicates whether a card is eligible for Dynamic Currency Conversion (DCC) at the point of sale or not. This indicator helps address DCC issues for Travel Prepaid Cards, other \"foreign currency cards\" (e.g. a Swiss bank that issues cards in Euros), and Commercial Cards (where the \"cardholder\" is a corporation and has a travel policy against accepting DCC and the resulting fees). Valid values:\n  C = Do not provide POI currency conversion (or DCC)  corporate client opt-out\n  D = POI currency conversion (or DCC) is permissible for account range per Mastercard Rules\n  T = Do not provide POI currency conversion (or DCC) per Mastercard Rules  travel cards or multi-currency accounts\n  U = Not a Mastercard- branded account range"
          minLength: 1
          maxLength: 1
          example: C
        billingCurrencyDefault:
          type: string
          description: The default currency of the cards in this range in ISO 4217 alphabetic format.
          minLength: 3
          maxLength: 3
          example: USD
        programName:
          type: string
          description: The program name of the affiliate using a BIN within the Issuer Sponsor's account range. This will be the name a customer sees on their card but the Account is actually owner by the Issuer, as shared in the customerName value. Data for this element is only available for prepaid BINs within the healthcare sector and will be null for the majority of account ranges.
          minLength: 1
          maxLength: 200
          example: Alegues
        vertical:
          type: string
          description: The vertical of a prepaid cards in the healthcare sector BIN such as CONSUMER, COMMERCIAL, PUBLIC SECTOR, HEALTHCARE. Data for this element is only available for prepaid BINs within the healthcare sector and will be null for the majority of account ranges.
          minLength: 1
          maxLength: 70
          example: HEALTHCARE
        fundingSource:
          type: string
          description: The funding source of the cards in this range. It can be any one of the following three values; CREDIT, DEBIT, PREPAID
          minLength: 5
          maxLength: 7
          example: CREDIT
        consumerType:
          type: string
          description: The type of customer the cards in this range are targeted at, can be either CONSUMER or CORPORATE. Unlike the vertical parameter, this data is available for all ranges.
          minLength: 1
          maxLength: 9
          example: CONSUMER
        smartDataEnabled:
          type: boolean
          description: Indicates if the issuer has enrolled this account range in Mastercard's Smart Data program. Smart Data provides enriched information about transactions provided by issuers and merchants. If true it means you can connect with the Smart Data team to collect additional insights about transactions within this account range.
          example: false
        affiliate:
          type: string
          description: When populated this is the name of the issuer on the card. In instances where the BIN is a sponsored BIN the affiliate will be the name of the issuing institution. When this has a value you should use this otherwise pull the customerName value.
          minLength: 1
          maxLength: 300
          example: California Community Bank
    Error:
      type: object
      required:
      - Source
      - ReasonCode
      - Recoverable
      properties:
        Source:
          type: string
          description: The application that generated this error. Possible values = GATEWAY/BIN_RESOURCE_SERVICE
          example: BIN_RESOURCE_SERVICE
          minLength: 1
          maxLength: 50
        ReasonCode:
          type: string
          description: A unique constant identifying the error case encountered during transaction processing
          example: resource.not.found
          minLength: 1
          maxLength: 100
        Description:
          type: string
          description: Description of the 'ReasonCode' field with additional details
          example: The requested resource does not exist
          minLength: 0
          maxLength: 500
        Recoverable:
          type: boolean
          description: Indicates whether this error will always be returned for this request, or retrying with same value could change the outcome. For example, if the request contains an invalid signature, retrying will never result in a success. However, if the error is related to some unexpected timeout with the service, retrying the call could result in a successful response.
          example: false
        Details:
          type: string
          description: Could be null, present for backwards compatibility or extra information
          example: The provided search value does not exist
          minLength: 0
          maxLength: 500
  requestBodies:
    BinResourceSearchRequest:
      description: BIN Resource Search Request
      required: true
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/SearchCriteria'
    BinResourceSearchByAccountRangeRequest:
      description: BIN Resource Search By account range Request
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SearchByAccountRange'
  parameters:
    Size:
      name: size
      in: query
      schema:
        type: integer
      description: The number of items to be displayed per page. The larger the number the slower the API will respond, but the less requests you will need to make for paginating through data. We recommend trying a page size of 1000 and adjusting for your needs.
      example: 25
      required: false
    Sort:
      name: sort
      in: query
      schema:
        type: string
      description: Sort by any parameter that the API returns with a direction (- for descending sort, + for ascending sort). For example -lowAccountRange will present the returned data in descending order based on the low account range values. The same is true for any of parameters such as customerName (+customerName) or ica (-ica).
      example: -lowAccountRange
      required: false
    Page:
      name: page
      in: query
      schema:
        type: integer
        minimum: 1
      description: The current page based on the number of items per page. Use this value to iterate through all of the paginated data and to know when you are the end of the data.
      example: 1
      required: false
  responses:
    NotFoundErrorResponse:
      description: The URI didn't match an existing resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            BINNotFoundExample:
              $ref: '#/components/examples/BINNotFoundExample'
    BadRequestErrorResponse:
      description: Invalid or insufficient parameters supplied
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            BINNotFoundExample:
              $ref: '#/components/examples/BadRequestExample'
    AccountRangeSearchResponse:
      description: Account Range Search response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BinResourceArray'
          examples:
            BINSuccessExample:
              $ref: '#/components/examples/BINSuccessExample'
    NotAuthorizedErrorResponse:
      description: Authentication information was missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            BINNotFoundExample:
              $ref: '#/components/examples/UnauthorizedExample'
    ForbiddenErrorResponse:
      description: Insufficient permissions for interacting with the resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            BINNotFoundExample:
              $ref: '#/components/examples/ForbiddenExample'
    BinResourceResponse:
      description: BIN Resource response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BinResourcePage'
          examples:
            FilterBINsExample:
              $ref: '#/components/examples/SearchBINsExample'
Mastercard Bin API

Documentation

Specifications

Code Examples

Other Resources

OpenAPI Specification
