# 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). * Refer [code and Formats](https://developer.mastercard.com/unified-installments/documentation/code-and-formats/index.md) for troubleshooting guidance. ## Positive test scenarios {#positive-test-scenarios} #### 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/mastercard-installments-services/inbound-api/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: Success-Amount less than min purchase amount {#test-case-2-success-amount-less-than-min-purchase-amount} ##### Request Body {#request-body-1} * JSON ```JSON { "transaction": { "amount": 50, "currency": "USD", "localDateTime": "2026-10-14T08:27:00Z" }, "sensitiveData": { "consumer": { "primaryAccountNumber": 2303770000051050 } } } ``` ##### Response {#response-1} * JSON ```JSON { "total": 0, "offerTransactionId": "633220593713418240", "offers": [], "eligibilityMessages": [ { "reasonCode": "amount.below.threshold", "message": "Purchase Amount does not qualify for Installments" } ] } ``` #### Test-case 3: Success-Only 1 offer when amount is more than 200 and less than 500 {#test-case-3-success-only-1-offer-when-amount-is-more-than-200-and-less-than-500} ##### Request Body {#request-body-2} * JSON ```JSON { "transaction": { "amount": 250, "currency": "USD", "localDateTime": "2026-10-14T08:27:00Z" }, "sensitiveData": { "consumer": { "primaryAccountNumber": 2303770000051050 } } } ``` ##### Response {#response-2} * JSON ```JSON { "total": 1, "offerTransactionId": "633220768800444416", "offers": [ { "priority": 1, "offerId": "71392362", "offerType": "CARDED_OFFER", "offerDisplayText": "6 weekly payments of $42.33", "currencySymbol": "$", "transactionCurrency": "USD", "totalInterestAndFeeAmount": 3.95, "recurringFeeAmount": 0.63, "apr": 23.39, "tenure": 6, "frequency": "WEEKLY", "interestRate": 1.25, "totalInterestAmount": 0.2, "firstInstallmentSchedule": "DELAY_RE_PYMNT", "totalAmount": 253.95, "firstInstallmentAmount": 42.33, "otherInstallmentAmount": 42.33, "feeType": "PRCENTG", "feeValue": 1.5, "feeDistribution": "ALL_INSTL", "totalFeeAmount": 3.75, "offerBeginDatetime": "2025-05-21T15:00:00-04:00", "offerEndDatetime": "2030-01-01T13:29:59-05:00", "selectable": false, "provider": { "providerId": "29694e7a-b4a8-11ec-b909-0242ac120002", "cid": "242666", "providerName": "Mastercard - Operations and Technology - BizOps", "providerLogoUrl": "https://mtf.installments.mastercard.com/mtf/Mast_b3136bef-1f6f-4fae-8732-3cd539f30d91.png", "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. " }, "schedulePayments": [ { "installmentNumber": 1, "installmentAmount": 42.33 }, { "installmentNumber": 2, "installmentAmount": 42.33 }, { "installmentNumber": 3, "installmentAmount": 42.33 }, { "installmentNumber": 4, "installmentAmount": 42.33 }, { "installmentNumber": 5, "installmentAmount": 42.33 }, { "installmentNumber": 6, "installmentAmount": 42.3 } ] } ] } ``` #### Test-case 4: Success-Amount more than 500 {#test-case-4-success-amount-more-than-500} ##### Request Body {#request-body-3} * JSON ```JSON { "transaction": { "amount": 1650, "currency": "USD", "localDateTime": "2026-10-14T08:27:00Z" }, "sensitiveData": { "consumer": { "primaryAccountNumber": 2303770000051050 } } } ``` ##### Response {#response-3} * JSON ```JSON { "total": 0, "offerTransactionId": "633221784660873216", "offers": [], "eligibilityMessages": [ { "reasonCode": "amount.above.threshold", "message": "Purchase Amount does not qualify for Installments" } ] } ``` #### Test-case 5: Success-When excluded MCC is provided in request {#test-case-5-success-when-excluded-mcc-is-provided-in-request} ##### Request Body {#request-body-4} * JSON ```JSON { "transaction": { "amount": 150, "currency": "USD", "localDateTime": "2025-08-03T16:55:43Z" }, "merchant": { "name": "Globex Decor", "country": "USA", "mcc": "7322", "url": "https://www.globexdecor.com", "acquirerId": 234353, "merchantId": "121234" }, "sensitiveData": { "consumer": { "primaryAccountNumber": 2303770000057107 } } } ``` ##### Response {#response-4} * JSON ```JSON { "total": 0, "offerTransactionId": "633222171400867840", "offers": [], "eligibilityMessages": [ { "reasonCode": "mcc.not.eligible", "message": "Merchant Category Code is not eligible for Installments" } ] } ``` ## Negative test scenario {#negative-test-scenario} #### Test-case 1: Failure-Verify that the consumer is not able to see the offers if the criteria is not matched {#test-case-1-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/mastercard-installments-services/inbound-api/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-5} * 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-5} * JSON ```JSON { "total": 0, "offerTransactionId": "547354508733190144", "offers": [], "eligibilityMessages": [ { "reasonCode": "consumer.not.eligible", "message": "Consumer is not eligible for Installments" } ] } ``` #### Test-case 2: Failure-Verify that the consumer is not able to see the offers if the PAN number or Token number is not matched {#test-case-2-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/mastercard-installments-services/inbound-api/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-6} * 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-6} * JSON ```JSON { "total": 0, "offerTransactionId": "547354508733190144", "offers": [], "eligibilityMessages": [ { "reasonCode": "consumer.not.eligible", "message": "Consumer is not eligible for Installments" } ] } ```