Mastercard Products API

openapi: 3.2.0
info:
  title: Mastercard Benefit Eligibility Service Products API
  version: 1.0.1
  description: This API is for third-parties who want to enable eligibility checks based on input criteria including card number. The Eligibility API is a PAN (Primary Account Number) level verification service designed to promote targeted distribution of Mastercard card level benefits. This service enables merchants and third-party developers to use a PAN to check the eligibility and access rights to the benefits for those cardholders.
  contact:
    name: API Support
    email: apisupport@mastercard.com
    url: https://developer.mastercard.com/support
servers:
- url: https://api.mastercard.com/loyalty/eligibility
  description: Production server
- url: https://sandbox.api.mastercard.com/loyalty/eligibility
  description: Sandbox server
tags:
- name: Products
  description: Handles Products
paths:
  /products/searches:
    post:
      tags:
      - Products
      description: Returns the product information using the card number provided for the requested date. If no date is provided, then current date will be used.
      summary: Search products
      operationId: searchProducts
      requestBody:
        $ref: '#/components/requestBodies/ProductSearch'
      responses:
        '200':
          $ref: '#/components/responses/SearchProducts'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
components:
  schemas:
    Error:
      description: A single error
      type: object
      properties:
        Source:
          type: string
          minLength: 0
          maxLength: 200
          description: Information about where the error happened
          example: ELIGIBILITY_BENEFITS_API
        ReasonCode:
          type: string
          minLength: 0
          maxLength: 200
          description: An error code
          example: BAD_REQUEST
        Description:
          type: string
          minLength: 0
          maxLength: 10000
          description: A description of the error
          example: We couldn't handle your request
        Recoverable:
          type: boolean
          description: Indicates if the request can be presented again for processing
          example: false
        Details:
          type: string
          minLength: 0
          maxLength: 10000
          description: More details about the error
          example: Invalid JSON payload
    SearchProducts:
      type: object
      properties:
        icaBusinessName:
          description: Name of Issuer
          type: string
          example: Bank Group
          minLength: 0
          maxLength: 60
        icaCode:
          description: ICA code of the issuer
          type: string
          example: '7379'
        icaRegion:
          description: The geographical region of card issuer
          type: string
          example: US
          minLength: 2
          maxLength: 40
          pattern: '[A-Z]+'
        icaCountry:
          description: The country of the card issuer
          type: string
          example: USA
          maxLength: 3
          minLength: 3
          pattern: '[A-Z]+'
        icaState:
          description: The state of the card issuer
          type: string
          example: SOUTH DAKOTA
          minLength: 0
          maxLength: 300
        icaLegalName:
          description: This is the ICAs Legal name for MPI, MasterCard's Licensing database
          type: string
          example: Bank Group, N.A.
          minLength: 0
          maxLength: 300
        parentICACode:
          description: Code for Parent Issuer
          type: string
          example: '7379'
          minLength: 4
          maxLength: 9
        data:
          description: Array of Products
          type: array
          items:
            $ref: '#/components/schemas/Product'
    Errors:
      description: Object that contains the list of errors
      type: object
      required:
      - Error
      properties:
        Error:
          $ref: '#/components/schemas/ErrorList'
    ErrorList:
      description: The list of errors
      type: array
      minItems: 1
      items:
        $ref: '#/components/schemas/Error'
    ErrorWrapper:
      description: A top level object for errors
      type: object
      required:
      - Errors
      properties:
        Errors:
          $ref: '#/components/schemas/Errors'
    Products:
      type: object
      properties:
        effectiveDate:
          description: Date for which benefits are to be determined. Defaults to the current date if not provided. Date is in YYYY-MM-DD format
          type: string
          example: '2022-12-15'
          pattern: ^\d{4}-\d{2}-\d{2}$
        cardNumber:
          description: Full card number or BIN number
          type: string
          example: '5308780000000000'
          minLength: 6
          maxLength: 19
      required:
      - cardNumber
    Product:
      type: object
      properties:
        productCode:
          description: 3 alpha character code of MasterCard Product. This is required if the BIN or card number has multiple Products associated with it.
          type: string
          example: MCC
          minLength: 3
          maxLength: 3
          pattern: ^[A-Z]{3}$
        productName:
          description: Name that corresponds to the Mastercard product
          type: string
          example: Mixed Product
          minLength: 1
          maxLength: 100
  examples:
    BadRequestExample:
      value:
        Errors:
          Error:
          - Source: Benefits Eligibility Service
            ReasonCode: BENEFITINFO_VAL_001
            Description: Validation Error  BIN Number should be numeric.
            Recoverable: false
    UnauthorizedExample:
      value:
        Errors:
          Error:
          - Source: Gateway
            ReasonCode: DECLINED
            Description: Unauthorized - Access Not Granted
            Recoverable: false
            Details: null
  requestBodies:
    ProductSearch:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Products'
  responses:
    UnauthorizedError:
      description: Unauthorized - Access Not Granted
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            UnauthorizedExample:
              $ref: '#/components/examples/UnauthorizedExample'
    SearchProducts:
      description: Returns Products that match the search criteria
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SearchProducts'
    BadRequestError:
      description: Something was wrong with the request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            BadRequestExample:
              $ref: '#/components/examples/BadRequestExample'