openapi: 3.0.3 info: title: Mastercard Benefit Eligibility Service 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 - name: Products description: Handles Products - name: Widget Access Token description: Generates tokens for vendor site. paths: /benefits/searches: post: tags: - Benefits - Searches 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' /products/searches: post: tags: - Products - Searches 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' /widgets/access-tokens: get: tags: - Widgets - Access - Tokens description: Generate a new access token for the vendor site. summary: Generate Access Token operationId: generateBenefitsAccessToken responses: '200': $ref: '#/components/responses/AccessToken' '401': $ref: '#/components/responses/UnauthorizedError' components: requestBodies: BenefitsSearch: required: true content: application/json: schema: $ref: '#/components/schemas/Benefits' ProductSearch: required: true content: application/json: schema: $ref: '#/components/schemas/Products' responses: SearchBenefits: description: Returns Benefits that match the requested details content: application/json: schema: $ref: '#/components/schemas/SearchBenefits' examples: listOfMultipleBenefitTypes: $ref: '#/components/examples/MultipleBenefitTypes' SearchProducts: description: Returns Products that match the search criteria content: application/json: schema: $ref: '#/components/schemas/SearchProducts' AccessToken: description: Returns Token for cardholder content: application/json: schema: $ref: '#/components/schemas/BenefitsAccessToken' 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' schemas: SearchBenefits: type: object properties: data: description: Array of Products type: array items: $ref: '#/components/schemas/Benefit' 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' BenefitsAccessToken: type: object properties: accessToken: description: The String (text) representation of Benefits Access Token type: string example: >- hereeyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIyMDIzMTIxMjA5MjMzNC1zdGFnZS1iZW5lZml0cy1hY2Nlc3MtbWFzdGVyY2FyZC1jb20iLCJ0ZXN0IjoidGVzdCIsImV4cCI6MTcwNTkxNjUzNiwiaWF0IjoxNzA1OTEyOTM2fQ.6NGFRgiy_7TayB366Eupz-xmro6Sb9kpwLY35IHoQDs 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 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 Benefit: type: object description: > The representation of a benefit provided by Mastercard to the cardholders. The details of the benefit are represented by means of various properties defined by this object. Depending on the type of benefit, only a subset of these properties will have the values. Please refer to the examples to know more about the details of the attributes that are available for different benefit types. 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. This information along with the _occurTimeUnit_ identifies the time duration for the policy occurrence to begin. occurEndTime: type: string example: 1 description: > Numeric value of the Insurance policy occurrence end time. This information along with the _occurTimeUnit_ identifies the time duration for the policy occurrence to end. 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' 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% ErrorWrapper: description: A top level object for errors type: object required: - Errors properties: Errors: $ref: '#/components/schemas/Errors' ErrorList: description: The list of errors type: array minItems: 1 items: $ref: '#/components/schemas/Error' 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 Errors: description: Object that contains the list of errors type: object required: - Error properties: Error: $ref: '#/components/schemas/ErrorList' 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 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