# Installments Notification API source: https://developer.mastercard.com/unified-installments/documentation/testing/mastercard-installments-payment-services/installments-notification-api/index.md If CIS has configured customer's API endpoint to Sandbox, then after every valid `POST /plans` API call, Mastercard will call customer's Notification API endpoint. ## Prerequisites {#prerequisites} To test the Notification API on Sandbox, customers must build the Notification API endpoint within their domain as per guidelines provided by Mastercard and establish connectivity between Mastercard and the customer domains. Once this is complete, there are following two options to test the notification API: | Option | Description | |--------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | #1. | To speed up testing using pre-loaded test data on Sandbox, Mastercard can configure Customer's Notification API endpoint on Sandbox environment along with Customer's developers project. After successful configuration, customers can execute the following test cases with exact same payloads and test if they are able to receive the Notification API events with expected test data. Note: Customers would receive notifications for a test issuer, which will not belong to their CID, ICA or Account ranges. | | #2. | If a customer chooses to test with their own data, then they must complete Issuer onboarding on the Mastercard Installments, with the help of CIS/CTS. Once this is complete, they can set up Installment offers using their own data, such as account ranges. Then, they will be able to receive Notification API events, which includes their own data. Note: In this case issuer can use the below test cases as a reference and modify the payload to provide their own data and perform testing. | #### Test Case 1: Successful delivery of Notification API for a funding PAN based transaction {#test-case-1-successful-delivery-of-notification-api-for-a-funding-pan-based-transaction} **GIVEN** : The customer is willing to test Notification API as per Option **#1** defined above, and the customer has already executed the [POST /offers](https://developer.mastercard.com/unified-installments/documentation/api-reference/apis/index.md#apis) API endpoint. **WHEN** : The customer executes a `POST /plans` call with a funding PAN with the following request payload (with correct `offerTransactionId` as per the `POST /offers` API response). ##### Request Body {#request-body} * JSON ```JSON { "offerId": "98427054", "offerTransactionId": "480285894528466944", "providerId": "29694e7a-b4a8-11ec-b909-0242ac120002", "tokenTransactionId": "tokenTransactionId", "merchant": { "acceptor": null, "mcc": "1711", "country": "MEX", "acquirerId": "5551", "name": "Testing Merchant", "merchantId": "21605304228" }, "transaction": { "amount": 169.14, "currency": "USD", "stan": "9991", "rrn": "8888", "authorizationCode": "AUTH99", "localDateTime": "2030-03-18T00:00:00Z", "transmissionDateTime": "2030-03-18T00:00:00Z", "transactionLinkId": "" }, "planInstallmentInformation": { "apr": 17.8, "totalAmount": 526.32, "firstInstallmentAmount": 87.72, "otherInstallmentAmount": 87.72, "currency": "USD", "tenure": 6, "frequency": "MONTHLY" }, "schedulePayments": [ { "installmentNumber": 1, "installmentAmount": 28.19, "dueDate": "2030-04-18" }, { "installmentNumber": 2, "installmentAmount": 28.19, "dueDate": "2030-05-18" }, { "installmentNumber": 3, "installmentAmount": 28.19, "dueDate": "2030-06-18" }, { "installmentNumber": 4, "installmentAmount": 28.19, "dueDate": "2030-07-18" }, { "installmentNumber": 5, "installmentAmount": 28.19, "dueDate": "2030-08-18" }, { "installmentNumber": 6, "installmentAmount": 28.19, "dueDate": "2030-09-18" } ], "sensitiveData": { "consumer": { "primaryAccountNumber": "2303770004152813" } } } ``` **THEN** : 1. The customer should receive an API notification call on customer's Sandbox URL from Mastercard. The customer should be able to decrypt the `encryptedValue` parameter by following [Integration and testing](https://developer.mastercard.com/unified-installments/tutorial/integration-and-testing/index.md) guide, and using the JWE decryption scheme, in order to fetch the `sensitiveData` parameter containing cleartext PAN. This PAN should be same as the PAN provided in the `POST /plan` request. 2. Upon decryption, the customer should be able to see the following request payload Note: `PlanId` will differ. ##### Request Body {#request-body-1} * JSON ```JSON { "planId": "4ab119cd-0d99-4aea-97ef-384d1816d44a", "issuerCid": "117643", "issuerIca": "4350", "merchant": { "country": "MEX", "acquirerId": "5551", "name": "Testing Merchant", "merchantId": "21605304228" }, "offerId": "98427054", "tokenTransactionId": "tokenTransactionId", "offerCode": "Special Discount", "planInstallmentInformation": { "apr": 17.8, "totalAmount": 526.32, "firstInstallmentAmount": 87.72, "otherInstallmentAmount": 87.72, "currency": "USD", "tenure": 6, "frequency": "MONTHLY" }, "schedulePayments": [ { "installmentNumber": 1, "installmentAmount": 28.19, "dueDate": "2030-04-18" }, { "installmentNumber": 2, "installmentAmount": 28.19, "dueDate": "2030-05-18" }, { "installmentNumber": 3, "installmentAmount": 28.19, "dueDate": "2030-06-18" }, { "installmentNumber": 4, "installmentAmount": 28.19, "dueDate": "2030-07-18" }, { "installmentNumber": 5, "installmentAmount": 28.19, "dueDate": "2030-08-18" }, { "installmentNumber": 6, "installmentAmount": 28.19, "dueDate": "2030-09-18" } ], "transaction": { "amount": 169.14, "currency": "USD", "localDateTime": "2030-03-18T00:00:00Z" }, "sensitiveData": { "consumer": { "primaryAccountNumber": "2303770004152813" } } } ``` ##### Response {#response} Customer should be able to return an appropriate response to Mastercard after processing the request. #### Test Case 2: Successful delivery of Notification API for a Token PAN based transaction {#test-case-2-successful-delivery-of-notification-api-for-a-token-pan-based-transaction} **GIVEN** : The customer is willing to test Notification API as per Option **#1** defined above, and the customer has already executed the [POST /offers](https://developer.mastercard.com/unified-installments/documentation/api-reference/apis/index.md#apis) API endpoint. **WHEN** : The customer executes a `POST /plans` call with a token PAN with the following request payload (with correct `offerTransactionId` as per the `POST /offers` API response). ##### Request Body {#request-body-2} * JSON ```JSON { "offerId": "98427054", "offerTransactionId": "480285894528466944", "providerId": "29694e7a-b4a8-11ec-b909-0242ac120002", "tokenTransactionId": "tokenTransactionId", "merchant": { "acceptor": null, "mcc": "1711", "country": "MEX", "acquirerId": "5551", "name": "Testing Merchant", "merchantId": "21605304228" }, "transaction": { "amount": 169.14, "currency": "USD", "stan": "9991", "rrn": "8888", "authorizationCode": "AUTH99", "localDateTime": "2030-03-18T00:00:00Z", "transmissionDateTime": "2030-03-18T00:00:00Z", "transactionLinkId": "" }, "planInstallmentInformation": { "apr": 17.8, "totalAmount": 526.32, "firstInstallmentAmount": 87.72, "otherInstallmentAmount": 87.72, "currency": "USD", "tenure": 6, "frequency": "MONTHLY" }, "schedulePayments": [ { "installmentNumber": 1, "installmentAmount": 28.19, "dueDate": "2030-04-18" }, { "installmentNumber": 2, "installmentAmount": 28.19, "dueDate": "2030-05-18" }, { "installmentNumber": 3, "installmentAmount": 28.19, "dueDate": "2030-06-18" }, { "installmentNumber": 4, "installmentAmount": 28.19, "dueDate": "2030-07-18" }, { "installmentNumber": 5, "installmentAmount": 28.19, "dueDate": "2030-08-18" }, { "installmentNumber": 6, "installmentAmount": 28.19, "dueDate": "2030-09-18" } ], "sensitiveData": { "consumer": { "primaryAccountNumber": "5468600800011000" } } } ``` **THEN** : 1. The customer should receive an API notification call on customer's Sandbox URL from Mastercard. The customer should be able to decrypt the `encryptedValue` parameter by following [Integration and testing](https://developer.mastercard.com/unified-installments/tutorial/integration-and-testing/index.md) guide, and using the JWE decryption scheme, in order to fetch the `sensitiveData` parameter containing cleartext PAN. This PAN received in notification API will be the funding PAN mapped to the token PAN provided in the `POST /plan` request. Hence the PAN sent in `POST /plans` and PAN sent in Notification API will be different. 2. Upon decryption, the customer should be able to see the following request payload Note: `PlanId` will differ. ##### Request Body {#request-body-3} * JSON ```JSON { "planId": "4ab119cd-0d99-4aea-97ef-384d1816d44a", "issuerCid": "117643", "issuerIca": "4350", "merchant": { "country": "MEX", "acquirerId": "5551", "name": "Testing Merchant", "merchantId": "21605304228" }, "offerId": "98427054", "tokenTransactionId": "tokenTransactionId", "offerCode": "Special Discount", "planInstallmentInformation": { "apr": 17.8, "totalAmount": 526.32, "firstInstallmentAmount": 87.72, "otherInstallmentAmount": 87.72, "currency": "USD", "tenure": 6, "frequency": "MONTHLY" }, "schedulePayments": [ { "installmentNumber": 1, "installmentAmount": 28.19, "dueDate": "2030-04-18" }, { "installmentNumber": 2, "installmentAmount": 28.19, "dueDate": "2030-05-18" }, { "installmentNumber": 3, "installmentAmount": 28.19, "dueDate": "2030-06-18" }, { "installmentNumber": 4, "installmentAmount": 28.19, "dueDate": "2030-07-18" }, { "installmentNumber": 5, "installmentAmount": 28.19, "dueDate": "2030-08-18" }, { "installmentNumber": 6, "installmentAmount": 28.19, "dueDate": "2030-09-18" } ], "transaction": { "amount": 169.14, "currency": "USD", "localDateTime": "2030-03-18T00:00:00Z" }, "sensitiveData": { "consumer": { "primaryAccountNumber": "5468600800011000" } } } ``` ##### Response {#response-1} Customer should be able to return an appropriate response to Mastercard after processing the request. #### Test Case 3: Customer should not receive notification for a failed POST /plans call {#test-case-3-customer-should-not-receive-notification-for-a-failed-post-plans-call} **GIVEN** : The customer is willing to test Notification API as per Option **#1** defined above, and the customer has already executed the [POST /offers](https://developer.mastercard.com/unified-installments/documentation/api-reference/apis/index.md#apis) API. **WHEN** : The customer executes a `POST /plans` call with a funding PAN with the following request payload (with correct `offerTransactionId` as per the `POST /offers` API response). ##### Request Body {#request-body-4} * JSON ```JSON { "offerId": "98427054", "offerTransactionId": "480285894528466944", "providerId": "29694e7a-b4a8-11ec-b909-0242ac120002", "tokenTransactionId": "tokenTransactionId", "merchant": { "acceptor": null, "mcc": "1711", "country": "MEX", "acquirerId": "5551", "name": "Testing Merchant", "merchantId": "21605304228" }, "transaction": { "amount": 169.14, "currency": "USD", "stan": "9991", "rrn": "8888", "authorizationCode": "AUTH99", "localDateTime": "2030-03-18T00:00:00Z", "transmissionDateTime": "2030-03-18T00:00:00Z", "transactionLinkId": "" }, "planInstallmentInformation": { "apr": 17.8, "totalAmount": 526.32, "firstInstallmentAmount": 87.72, "otherInstallmentAmount": 87.72, "currency": "USD", "tenure": 6, "frequency": "MONTHLY" }, "schedulePayments": [ { "installmentNumber": 1, "installmentAmount": 28.19, "dueDate": "2030-04-18" }, { "installmentNumber": 2, "installmentAmount": 28.19, "dueDate": "2030-05-18" }, { "installmentNumber": 3, "installmentAmount": 28.19, "dueDate": "2030-06-18" }, { "installmentNumber": 4, "installmentAmount": 28.19, "dueDate": "2030-07-18" }, { "installmentNumber": 5, "installmentAmount": 28.19, "dueDate": "2030-08-18" }, { "installmentNumber": 6, "installmentAmount": 28.19, "dueDate": "2030-09-18" } ], "sensitiveData": { "consumer": { "primaryAccountNumber": "2303770004152813" } } } ``` **THEN** : The customer should not receive an API notification call on customer's Sandbox URL from Mastercard as the `POST /Plans` request was not successful. #### Test Case 4: In case of failed notification API calls, Mastercard performs retry until it is successful {#test-case-4-in-case-of-failed-notification-api-calls-mastercard-performs-retry-until-it-is-successful} **GIVEN**: 1. The customer is willing to test Notification API as per Option #1 defined above. 2. The customer executes a `POST /plans` call. 3. The customer receives an API notification call on customer's Sandbox URL from Mastercard having same information matching Plan request data provided earlier. 4. The customer has planned to return a temporary failure response to test the retry capability. **WHEN** : The customer API returns a 5XX response code to simulate a failure scenario. **THEN**: Mastercard retries sending the notification API for up to 3 times with an internal of 1 minute initially. After that 3 times, after every one hour interval indefinitely, until the customer returns 201 response. No further retries, once the customer returns 201 response.