# Installments Offers API source: https://developer.mastercard.com/unified-installments/documentation/testing/mastercard-installments-payment-services/installments-offers-api/index.md Using offers, customers can invoke `/POST offers` to expect an appropriate response. Any PAN belonging to the enabled Account range can be used for testing. ## Prerequisites {#prerequisites} The API provides eligibility and offers response for Installments offers for purchases made on existing cards (Credit/Debit). #### Test-case 1: Success-Verify that the consumer is able to see all the eligible offers {#test-case-1-success-verify-that-the-consumer-is-able-to-see-all-the-eligible-offers} **GIVEN** : The consumer has access to the Mastercard Installments API and has integrated their solution or application with the [/installments/offers](https://developer.mastercard.com/unified-installments/documentation/api-reference/apis/index.md#apis) endpoint. **WHEN** : The consumer backend system makes a REST call to the '/installments/offers' endpoint. **THEN** : The consumer should receive details of all the eligible offers based on the following criteria: * amount * currency * localdatetime * country * mcc * url * acquirerId * merchantId * PAN (Encryption required) ##### Request Body {#request-body} * JSON ```JSON { "transaction": { "amount": 150, "currency": "USD", "localDateTime": "2025-08-03T16:55:43Z" }, "merchant": { "name": "Globex Decor", "country": "USA", "mcc": "1711", "url": "https://www.globexdecor.com", "acquirerId": 234353, "merchantId": "121234" }, "sensitiveData": { "consumer": { "primaryAccountNumber": 2303770000057107 } } } ``` ##### Response {#response} * JSON ```JSON { "offers": [ { "apr": 15.36, "currencySymbol": "$", "feeDistribution": "FRST_INSTL", "feeType": "FIXED_AMT", "feeValue": 10, "countryCode": "USA", "firstInstallmentAmount": 22.5, "firstInstallmentSchedule": "TRANSCTN_DATE", "frequency": "MONTHLY", "interestRate": 0, "objectType": "OfferGroupAndPriority", "offerBeginDatetime": "2025-05-21T15:00:00-04:00", "offerDisplayText": "12 monthly payments of $12.50", "offerEndDatetime": "2029-12-31T18:59:59-05:00", "offerId": "71392364", "offerType": "CARDED_OFFER", "oneTimeFeeAmount": 10, "otherInstallmentAmount": 12.5, "priority": 1, "provider": { "cid": "242666", "providerId": "29694e7a-b4a8-11ec-b909-0242ac120002", "providerLogoUrl": "https://mtf.installments.mastercard.com/mtf/Mast_b3136bef-1f6f-4fae-8732-3cd539f30d91.png", "providerName": "Mastercard - Operations and Technology - BizOps", "disclosure": "Disclosure: This offer is part of a testing environment and is not valid for actual transactions. All Terms & Conditions displayed are for simulation purposes only.", "disclosureLinks": [ { "linkText": "Terms and Conditions", "linkUrl": "https://www.mastercard.com/us/en/terms-of-use.html" } ] }, "schedulePayments": [ { "installmentAmount": 22.5, "installmentNumber": 1 }, { "installmentAmount": 12.5, "installmentNumber": 2 }, { "installmentAmount": 12.5, "installmentNumber": 3 }, { "installmentAmount": 12.5, "installmentNumber": 4 }, { "installmentAmount": 12.5, "installmentNumber": 5 }, { "installmentAmount": 12.5, "installmentNumber": 6 }, { "installmentAmount": 12.5, "installmentNumber": 7 }, { "installmentAmount": 12.5, "installmentNumber": 8 }, { "installmentAmount": 12.5, "installmentNumber": 9 }, { "installmentAmount": 12.5, "installmentNumber": 10 }, { "installmentAmount": 12.5, "installmentNumber": 11 }, { "installmentAmount": 12.5, "installmentNumber": 12 } ], "selectable": false, "tenure": 12, "totalAmount": 160, "totalFeeAmount": 10, "totalInterestAmount": 0, "totalInterestAndFeeAmount": 10, "transactionCurrency": "USD" }, { "apr": 23.68, "countryCode": "USA", "currencySymbol": "$", "feeDistribution": "ALL_INSTL", "feeType": "PRCENTG", "feeValue": 1.5, "firstInstallmentAmount": 25.4, "firstInstallmentSchedule": "DELAY_RE_PYMNT", "frequency": "WEEKLY", "interestRate": 1.25, "objectType": "OfferGroupAndPriority", "offerBeginDatetime": "2025-05-21T15:00:00-04:00", "offerDisplayText": "6 weekly payments of $25.40", "offerEndDatetime": "2029-12-31T18:59:59-05:00", "offerId": "71392362", "offerType": "CARDED_OFFER", "otherInstallmentAmount": 25.4, "recurringFeeAmount": 0.38, "priority": 2, "provider": { "cid": "242666", "providerId": "29694e7a-b4a8-11ec-b909-0242ac120002", "providerLogoUrl": "https://mtf.installments.mastercard.com/mtf/Mast_b3136bef-1f6f-4fae-8732-3cd539f30d91.png", "providerName": "Mastercard - Operations and Technology - BizOps", "disclosure": "Disclosure: This offer is part of a testing environment and is not valid for actual transactions. All Terms & Conditions displayed are for simulation purposes only.", "disclosureLinks": [ { "linkText": "Terms and Conditions", "linkUrl": "https://www.mastercard.com/us/en/terms-of-use.html" } ] }, "schedulePayments": [ { "installmentAmount": 25.4, "installmentNumber": 1 }, { "installmentAmount": 25.4, "installmentNumber": 2 }, { "installmentAmount": 25.4, "installmentNumber": 3 }, { "installmentAmount": 25.4, "installmentNumber": 4 }, { "installmentAmount": 25.4, "installmentNumber": 5 }, { "installmentAmount": 25.4, "installmentNumber": 6 } ], "selectable": false, "tenure": 6, "totalAmount": 152.4, "totalFeeAmount": 2.25, "totalInterestAmount": 0.12, "totalInterestAndFeeAmount": 2.37, "transactionCurrency": "USD" } ], "offerTransactionId": "473848442280480768", "total": 2 } ``` #### Test-case 2: Failure-Verify that the consumer is not able to see the offers if the criteria is not matched {#test-case-2-failure-verify-that-the-consumer-is-not-able-to-see-the-offers-if-the-criteria-is-not-matched} **GIVEN** : The consumer has access to the Mastercard Installments API and has integrated their solution or application with the [/installments/offers](https://developer.mastercard.com/unified-installments/documentation/api-reference/apis/index.md#apis) endpoint. **AND** : There are multiple offers with different configurations that are amount, MCC, PAN number, and so on. **WHEN** : The consumer backend system makes a REST call to the '/installments/offers' endpoint that does not meet any criteria. **THEN**: The consumer should not receive any offer. ##### Request Body {#request-body-1} * JSON ```JSON { "transaction": { "amount": 700.3, "currency": "USD", "localDateTime": "2024-05-02T00:00:00Z" }, "merchant": { "country": "USA", "name": "Kohls", "url": "https://corporate.kohls.com" }, "sensitiveData": { "consumer": { "primaryAccountNumber": "2303770000057107" } } } ``` ##### Response {#response-1} * JSON ```JSON { "total": 0, "offerTransactionId": "547354508733190144", "offers": [], "eligibilityMessages": [ { "reasonCode": "consumer.not.eligible", "message": "Consumer is not eligible for Installments" } ] } ``` #### Test-case 3: Failure-Verify that the consumer is not able to see the offers if the PAN number or Token number is not matched {#test-case-3-failure-verify-that-the-consumer-is-not-able-to-see-the-offers-if-the-pan-number-or-token-number-is-not-matched} **GIVEN** : The consumer has access to the Mastercard Installments API and has integrated their solution or application with the [/installments/offers](https://developer.mastercard.com/unified-installments/documentation/api-reference/apis/index.md#apis) endpoint. **AND** : There are multiple offers with different configurations that are amount, MCC, PAN number, and so on. **WHEN** : The consumer backend system makes a REST call to the '/installments/offers' endpoint and the request payload does not have an eligible PAN. **THEN**: The consumer should not receive any offer. ##### Request Body {#request-body-2} * JSON ```JSON { "transaction": { "amount": 700.3, "currency": "USD", "localDateTime": "2024-05-02T00:00:00Z" }, "merchant": { "country": "USA", "name": "Kohls", "url": "https://corporate.kohls.com" }, "sensitiveData": { "consumer": { "primaryAccountNumber": "3555555555354444" } } } ``` ##### Response {#response-2} * JSON ```JSON { "total": 0, "offerTransactionId": "547354508733190144", "offers": [], "eligibilityMessages": [ { "reasonCode": "consumer.not.eligible", "message": "Consumer is not eligible for Installments" } ] } ```