Mastercard Benefits API

openapi: 3.2.0
info:
  title: Mastercard Benefit Eligibility Service Benefits 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: Benefits
  description: Handles Benefits
paths:
  /benefits/searches:
    post:
      tags:
      - Benefits
      description: Send cardholder information and a date, get the benefits that the cardholder had for that date. If no date is provided the current one is used.
      summary: Search benefits
      operationId: searchBenefits
      requestBody:
        $ref: '#/components/requestBodies/BenefitsSearch'
      responses:
        '200':
          $ref: '#/components/responses/SearchBenefits'
        '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
    CustomAttribute:
      type: object
      properties:
        name:
          type: string
          description: Name of the custom attribute.
          example: Discount
        value:
          type: string
          description: value of the custom attribute.
          example: 10%
    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'
    Benefit:
      type: object
      description: "The representation of a benefit provided by Mastercard to the cardholders.  \nThe details of the benefit are represented by means of various properties defined by this object.  \nDepending on the type of benefit, only a subset of these properties will have the values.  \nPlease refer to the examples to know more about the details of the attributes that are available for different benefit types.\n"
      properties:
        benefitBundleId:
          type: string
          example: 2afd75df-a9f6-407f-bdfb-f24d2532a711
          description: The unique identifier of the Bundle which the benefit is part of
          minLength: 36
          maxLength: 36
        benefitBundleName:
          type: string
          example: US OPT Extended Warranty
          description: Name of the benefit Bundle which the benefit is part of
          minLength: 1
          maxLength: 200
        benefitServicingId:
          type: string
          example: 2afd75df-a9f6-407f-bdfb-f24d2532a711
          description: Servicing identifier of the benefit
          minLength: 0
          maxLength: 36
        benefitServicingOptions:
          type: string
          example: All Claims
          description: Servicing option which benefit is associated to.
          minLength: 0
          maxLength: 100
        benefitID:
          type: string
          example: '2495'
          description: The unique numeric code of the Benefit
          minLength: 1
          maxLength: 6
        benefitCode:
          type: string
          example: WTY
          description: The three character unique code assigned by Mastercard and used to identify the benefit
          minLength: 3
          maxLength: 3
        benefitName:
          type: string
          example: Extended Warranty
          description: Name of the benefit
          minLength: 1
          maxLength: 50
        macBenefitCategory:
          type: string
          example: Shopping
          description: The category code defined by Mastercard to categorize the benefit
          minLength: 1
          maxLength: 100
        serviceProviderCode:
          type: string
          example: 58
          description: The code assigned for the Service Provider
          minLength: 1
          maxLength: 6
        serviceProviderName:
          type: string
          example: US Extended Warranty - Information
          description: The name of the Service Provider
          minLength: 1
          maxLength: 100
        paymentType:
          type: string
          example: MasterCard Pays/ All Cards
          description: MasterCard Pays vs Issuer Pays
          minLength: 1
          maxLength: 255
        occurBeginTime:
          type: string
          example: 0
          description: "Numeric value of the Insurance policy occurrence begin time.  \nThis information along with the _occurTimeUnit_ identifies the time duration for the policy occurrence to begin.\n"
        occurEndTime:
          type: string
          example: 1
          description: "Numeric value of the Insurance policy occurrence end time.  \nThis information along with the _occurTimeUnit_ identifies the time duration for the policy occurrence to end.\n"
        occurTimeUnit:
          type: string
          example: Year
          minLength: 0
          maxLength: 5
          description: Unit of measurement for the Occurrence begin time and end time
        occurMinimumAmount:
          type: string
          example: 0
          description: Minimum amount of claim before policy comes into effect.
        occurMaximumAmount:
          type: string
          example: 19999.99
          description: Maximum amount policy will pay per claim.
        occurCurrency:
          type: string
          minLength: 0
          maxLength: 3
          example: USD
          pattern: ^[A-Z]{3}$
          description: The ISO 4217 alpha code of the currency of the policy occurrence minimum and maximum amount.
        minimumClaimValue:
          type: string
          example: 1999.99
          description: The minimum value for submitting the claim.
        minimumClaimCurrencyType:
          type: string
          example: USD
          description: The ISO 4217 alpha code of the currency of the minimum claim value.
          minLength: 0
          maxLength: 3
          pattern: ^[A-Z]{3}$
        occurMisc:
          type: string
          example: 0
          description: Covers miscellaneous coverage issues like return policy and electronic & sport equipment coverage.
        policyTimeLimit:
          type: string
          example: 12
          description: Length of entire policy. This information along with the _policyTimeUnit_ identifies the duration of the policy.
        policyTimeUnit:
          type: string
          example: Month
          description: The unit of measurement for the policy time limit.  For example, Days, Months, Years.
        policyMaximumOccurs:
          type: string
          example: 0
          description: The maximum number of claims within policy time frame.
        policyMaximumAmount:
          type: string
          example: 19999.99
          description: The maximum amount that the policy will pay when the claim is settled.
        policyCurrency:
          type: string
          example: USD
          minLength: 0
          maxLength: 3
          pattern: ^[A-Z]{3}$
          description: The ISO 4217 alpha code for the currency of the maximum policy amount.
        policyRegionRestriction:
          type: string
          example: All
          description: Geographical regions where the policy cover is allowed.
        coverageType:
          type: string
          example: Excess
          description: The type of coverage, for example,  Primary or Excess.
        appliesTo:
          type: string
          example: Family
          minLength: 1
          maxLength: 255
          description: Identifies the members whom the policy is applicable to. For example, Individual or Family.
        qualifyingRequirement:
          type: string
          example: Recurrent bill payment with eligible MC $50 deductible.
          description: Identifies any additional requirements for qualifying for the policy coverage.
        additionalCoverage:
          type: string
          example: $300 Baggage Delay
          description: Any additional coverage, apart from the monetary benefit, that the policy provides.
        quantity:
          type: string
          example: 5
          minLength: 0
          description: The count for the number of items
        quantityType:
          type: string
          description: The information to supplement the 'quantity' by providing the additional details like 'Bags' or 'Gigabytes' or 'Tickets' etc.
          example: Tickets
        duration:
          type: string
          description: Numeric value of the duration of the coverage.
          example: 20
        durationTimeIncrement:
          type: string
          description: The unit of duration time increment. For example, Day, Hour, Minute, Second etc.
          example: Hour
        deductibleValue:
          type: string
          description: Applicable deductible value
          example: 100
        deductibleCurrencyType:
          type: string
          pattern: ^[A-Z]{3}$
          description: The ISO 4217 alphabetic code for the currency of Applicable deductible value.
          example: USD
        numberOfMemberEntitlements:
          type: string
          description: Number of member Entitlements. Can be a numeric value or the text 'Unlimited'.
          example: Unlimited
        memberEntitlementsFundedBy:
          type: string
          description: Information about who funds the member entitlements available as part of the benefit.
          example: Mastercard
        numberOfGuestEntitlements:
          type: string
          description: Number of guest entitlements.  Can be a numeric value or the text 'Unlimited'.
          example: 2
        typeOfGuestEntitlements:
          type: string
          description: Type of guest entitlements.
          example: Each Time
        guestEntitlementsFundedBy:
          type: string
          description: Information about who funds the Guest Entitlements.
          example: Issuer
        numberOfSharedMemberAndGuestEntitlements:
          type: string
          description: Number of shared member and guest entitlements. Can be a numeric value or the text 'Unlimited'.
          example: 3
        sharedMemberAndGuestEntitlementsFundedBy:
          type: string
          description: Information about who funds the shared member and guest entitlements.
          example: Mastercard
        discountValue:
          type: string
          description: Number representing the Applicable discount value.
          example: 10
        currency:
          type: string
          description: The ISO 4217 alpha code for the currency of Discount value.
          example: USD
          pattern: ^[A-Z]{3}$
        discountType:
          type: string
          description: Type of discount.
          example: basic-car-price
        interchangeableEntitlement:
          type: string
          description: Interchangeable entitlement name.
          example: FastTrack
        serviceProviderDealId:
          type: string
          description: The unique identifier of the agreement between Mastercard and the Benefit Service Provider with regards to providing the required services for the Benefit offered.
          example: PPMCOWELBGHUAT
        airportExperienceCoverage:
          type: string
          description: Identifies access limitations on where the benefit can be used.
          example: Global, Domestic
        airportExperienceExclusions:
          type: string
          description: Airport experience exclusions.
          example: SAMPLEEXCEPTIONREGION
        airportExperienceAccessMethod:
          type: string
          description: The method or way using which the airport experience can be accessed by the card holder.
          example: Access with Digital Membership Card (DMC)
        percentageOff:
          type: string
          description: The numeric value of Discount rate percentage.
          example: 10
        vendorReference:
          type: string
          description: The textual value agreed to by Mastercard and the Service Provider to exchange a needed identifier.
          example: PPMCOWELBGUK23
        bundleType:
          type: string
          minLength: 1
          maxLength: 255
          example: Region Specific Set
          description: Category that benefit belong to
        benefitEffectiveDate:
          type: string
          example: '2022-12-15'
          pattern: ^\d{4}-\d{2}-\d{2}$
          description: Date from which the benefit becomes active to the associated product. Date is in YYYY-MM-DD format
        benefitExpirationDate:
          type: string
          example: '2022-12-15'
          pattern: ^\d{4}-\d{2}-\d{2}$
          description: Date from which the benefit becomes in active to the associated product. Date is in YYYY-MM-DD format
        customAttributes:
          description: Array of custom attributes
          type: array
          items:
            $ref: '#/components/schemas/CustomAttribute'
    SearchBenefits:
      type: object
      properties:
        data:
          description: Array of Products
          type: array
          items:
            $ref: '#/components/schemas/Benefit'
    Benefits:
      type: object
      properties:
        cardNumber:
          description: Full card number or BIN number
          type: string
          example: '5308780000000000'
          minLength: 6
          maxLength: 19
        effectiveDate:
          description: Date for which products 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}$
        serviceProviderCode:
          description: Number that represents the Service Provider of a Benefit
          type: string
          example: '01'
          minLength: 1
          maxLength: 6
        productCode:
          description: The product identifier for a benefit, it is mandatory if a BIN is used
          type: string
          example: MCC
          minLength: 3
          maxLength: 3
        benefitCode:
          type: string
          maxLength: 3
          minLength: 3
          example: WTY
          description: The unique alpha code assigned for the benefit
      required:
      - cardNumber
    ErrorWrapper:
      description: A top level object for errors
      type: object
      required:
      - Errors
      properties:
        Errors:
          $ref: '#/components/schemas/Errors'
  examples:
    BadRequestExample:
      value:
        Errors:
          Error:
          - Source: Benefits Eligibility Service
            ReasonCode: BENEFITINFO_VAL_001
            Description: Validation Error  BIN Number should be numeric.
            Recoverable: false
    MultipleBenefitTypes:
      summary: Multiple types of Benefits
      value:
        data:
        - benefitBundleId: 5bbf8967-Rce1-ACGC-56ty-18IYUT6ba572
          benefitBundleName: OPT-PRO 121-IH
          benefitServicingId: 5890b2e4-4cc7-490c-a85b-715f7e989dc1
          benefitServicingOptions: Existing Claims
          benefitID: '2495'
          benefitCode: WTY
          benefitName: Airport Lounge Access
          macBenefitCategory: Travel
          serviceProviderCode: '58'
          serviceProviderName: US Extended Warranty - Information
          paymentType: MasterCard Pays/ All Cards
          bundleType: Region Specific Set
          benefitEffectiveDate: '2022-12-15'
          benefitExpirationDate: '2030-12-15'
          appliesTo: Family
          customAttributes:
          - name: dealId
            value: PPMCOWELBGHUAT
          numberOfEntitlements: Unlimited
          entitlementsFundedBy: Mastercard
          numberOfGuestEntitlements: '2'
          typeOfGuestEntitlements: Each Time
          guestEntitlementsFundedBy: Issuer
          numberOfSharedAndGuestEntitlements: '3'
          sharedAndGuestEntitlementsFundedBy: Mastercard
          discountValue: '10'
          currency: USD
          discountType: basic-car-price
          interchangeableEntitlement: FastTrack
          serviceProviderDealId: LOUNGEISSUERBANK
          airportExperienceCoverage: Global, Domestic
          airportExperienceExceptions: Lounge, Flight Delay Pass
          airportExperienceAccessMethod: Access with Digital Membership Card (DMC)
        - benefitBundleId: 2d01bd0d-84e6-46e7-89dc-7bba8797ed8c
          benefitBundleName: OPT-TRC-211-IA
          benefitServicingId: d2908f2b-8b41-4377-b5b6-025c223c0d33
          benefitServicingOptions: New Claims
          benefitID: '3395'
          benefitCode: MCW
          benefitName: Accidental Death and Dismemberment
          macBenefitCategory: Travel
          serviceProviderCode: '58'
          serviceProviderName: US Extended Warranty - Information
          paymentType: MasterCard Pays/ All Cards
          bundleType: Region Specific Set
          benefitEffectiveDate: '2022-12-15'
          benefitExpirationDate: '2030-12-15'
          appliesTo: Individual
          customAttributes: []
          occurBeginTime: '0'
          occurEndTime: '1'
          occurTimeUnit: Year
          occurMinimumAmount: '0'
          occurMaximumAmount: '10000'
          occurCurrency: USD
          minimumClaimValue: '10'
          minimumClaimCurrencyType: USD
          occurMisc: '0'
          policyTimeLimit: '12'
          policyTimeUnit: Month
          policyMaximumOccurs: '0'
          policyMaximumAmount: '10000'
          policyCurrency: USD
          policyRegionRestriction: All
          coverageType: Excess
          qualifyingRequirement: Recurrent bill payment with eligible MC $50 deductible.
          additionalCoverage: If death of the insured is abroad, and family decides not to repatriate the body, then maximum limit for funeral expenses is USD 5,000 / 70 or older max 30 days
          quantity: '5'
          duration: '20'
          durationTimeIncrement: Hour
          deductibleValue: '10'
          deductibleCurrencyType: USD
        - benefitBundleId: 10cc44cf-0151-4597-922b-c42a6cdfb408
          benefitBundleName: OPT-WTY 66-IA
          benefitServicingId: c8087ce6-32d6-435f-b700-7df231975800
          benefitServicingOptions: All Claims
          benefitID: '3149'
          benefitCode: MEP
          benefitName: Amazon Prime Membership
          macBenefitCategory: Lifestyle
          serviceProviderCode: '58'
          serviceProviderName: US Extended Warranty - Information
          paymentType: MasterCard Pays/ All Cards
          bundleType: Region Specific Set
          benefitEffectiveDate: '2022-12-15'
          benefitExpirationDate: '2030-12-15'
          appliesTo: Family
          customAttributes: []
          percentageOff: '10'
          quantity: '5'
          quantityType: ''
          duration: '20'
          durationTimeIncrement: Hour
          vendorReference: DP
    UnauthorizedExample:
      value:
        Errors:
          Error:
          - Source: Gateway
            ReasonCode: DECLINED
            Description: Unauthorized - Access Not Granted
            Recoverable: false
            Details: null
  responses:
    SearchBenefits:
      description: Returns Benefits that match the requested details
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SearchBenefits'
          examples:
            listOfMultipleBenefitTypes:
              $ref: '#/components/examples/MultipleBenefitTypes'
    BadRequestError:
      description: Something was wrong with the request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            BadRequestExample:
              $ref: '#/components/examples/BadRequestExample'
    UnauthorizedError:
      description: Unauthorized - Access Not Granted
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            UnauthorizedExample:
              $ref: '#/components/examples/UnauthorizedExample'
  requestBodies:
    BenefitsSearch:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Benefits'