# Installments Notification API source: https://developer.mastercard.com/unified-installments/documentation/testing/mastercard-installments-payment-services/installments-notification-api/index.md After your Notification API endpoint is registered for Sandbox, Mastercard calls it after every valid `POST /plans` request. ## Prerequisites {#prerequisites} Complete these steps before you run the test cases: 1. Build the `POST /notifications` endpoint in your domain. It must meet the requirements in [Installments Notification API](https://developer.mastercard.com/unified-installments/documentation/use-cases/mastercard-installments-payment-services/post-purchase/index.md#installments-notification-api): a public HTTPS URL with a fully qualified domain name that ends in `/notifications`. 2. Configure JWE decryption with your client encryption private key, as described in [Encryption](https://developer.mastercard.com/unified-installments/documentation/api-basics/index.md#encryption). 3. Validate the endpoint yourself before Mastercard calls it. Take the `POST /notifications` example from the [Outbound API](https://developer.mastercard.com/unified-installments/documentation/api-reference/mastercard-installments-services/outbound-api/index.md#apis) specification, encrypt its `sensitiveData` object with your client encryption certificate, and send it to your endpoint. Confirm that your endpoint decrypts the payload and returns HTTP 201. 4. Register the endpoint URL for your Sandbox project when you set up the Notification API service during onboarding. For the overall onboarding process, see the [Onboarding Checklist](https://developer.mastercard.com/unified-installments/documentation/onboarding-checklist/index.md). If a call fails, use [Codes and Formats](https://developer.mastercard.com/unified-installments/documentation/code-and-formats/index.md) for troubleshooting. After your endpoint is registered, you can test the Notification API in either of the following ways: | Option | Description | |--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | #1. | Use the test data preloaded in Sandbox. Run the following test cases with the exact payloads shown, and confirm that your endpoint receives Notification API events with the expected test data. Note: You receive notifications for a test issuer, which does not belong to your CID, ICA, or account ranges. | | #2. | Use your own data. After you complete issuer onboarding for Mastercard Installments, set up installment offers with your own data, such as account ranges. You then receive Notification API events that include your own data. Note: Use the following test cases as a reference, and replace the payload values with your own data. | ## Positive test scenarios {#positive-test-scenarios} #### 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/mastercard-installments-services/inbound-api/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/mastercard-installments-services/outbound-api/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. ## Negative test scenario {#negative-test-scenario} #### 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/mastercard-installments-services/outbound-api/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 up to 3 times at 1-minute intervals. It then sends 3 retries every hour until the customer returns HTTP 201. Retries stop after the customer returns HTTP 201.