# During Purchase source: https://developer.mastercard.com/unified-installments/documentation/use-cases/mastercard-installments-payment-services/during-purchase/index.md Mastercard can enable the distribution of Installments offers during checkout through distribution partners, such as Wallets, Browsers, Acquirers, Point of Sale (POS) terminal providers, Payment Gateway, Payment Service Provider (PSP) / Payment aggregators, and Merchants. ## API Overview {#api-overview} | No. | API Name | Access | High-Level Description | What It Does | Audience | |-----|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|----------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------| | 1. | [PAN List API](https://developer.mastercard.com/unified-installments/documentation/use-cases/mastercard-installments-payment-services/during-purchase/index.md#pan-list-api) | Inbound | Used for creating and maintaining a list of PANs (Primary Account Numbers) eligible for an Installments offer. | * Creates a new PAN List with a list of PANs * Modifies an existing PAN List to add/remove PANs | Issuer/Issuer Processor | | 2. | [Installments Offers API](https://developer.mastercard.com/unified-installments/documentation/use-cases/mastercard-installments-payment-services/during-purchase/index.md#installments-offers-api) | Inbound | Checks the cardholder's eligibility for installments and provides the installments plan calculation details | * Will run an eligibility check * Will return installments offers available for the transaction * Will return a valid error message if the transaction is ineligible | Distribution Partner | | 3. | [Installments Plan API](https://developer.mastercard.com/unified-installments/documentation/use-cases/mastercard-installments-payment-services/during-purchase/index.md#installments-plan-api) | Inbound | Used for saving the installment plan chosen by the cardholder | * Will save the cardholder-chosen plan and the associated transaction details in the Mastercard database * Will return a valid error message if the plan cannot be saved | Distribution Partner | | 4. | [Installments Notification API](https://developer.mastercard.com/unified-installments/documentation/use-cases/mastercard-installments-payment-services/during-purchase/index.md#installments-notification-api) | Outbound | Notifies Issuer/Processor of the cardholder chosen plan and associated transaction identifiers. | * Asynchronous notification - will notify Processor/Issuer about the cardholder chosen plan | Issuer/ Issuer Processor | ## PAN List API {#pan-list-api} The API allows you to create a list of PANs (Primary Account Numbers) that belong to the same account range. This list, known as a PAN List, is created in the Mastercard Installments database. Once the PAN List is created, it can be linked to an Installment offer group using the Mastercard Installments User Interface. This means that offers will only be available to the PANs in the respective PAN List. This feature is useful for issuers who wish to provide special installments offers to only a limited number of cardholders and not their entire portfolio/Account Range. Please note that when creating the PAN list, Issuers need to specify only the Funding PANs. They can include up to 20 PANs in a single request. Also, Issuers are allowed to add the same PAN to different PAN Lists. There are two endpoints available to maintain the PAN List: * [Create a PAN List and/or add PAN to a list](https://developer.mastercard.com/unified-installments/documentation/use-cases/mastercard-installments-payment-services/during-purchase/index.md#create-a-pan-list-and-or-add-pan-to-a-list) * [Deregister PAN from a PAN List](https://developer.mastercard.com/unified-installments/documentation/use-cases/mastercard-installments-payment-services/during-purchase/index.md#deregister-pan-from-a-pan-list) ### Create a PAN List and/or add PAN to a list {#create-a-pan-list-andor-add-pan-to-a-list} This endpoint lets you create a new PAN list or add more PANs to an existing PAN List. Issuers need to send encrypted PANs in the request body, following the encryption scheme specified by Mastercard. Mastercard will then validate the API request. The API can return one of the following responses: * **Success** : All PANs are processed successfully. This is indicated by an HTTP response code of 200 and a `failureCount` parameter in the response body of '0'. * **Failure**: The API call fails. This is indicated by an HTTP response code that is not 200. * **Partial Success** : Some PANs are processed successfully, but others fail. This is indicated by an HTTP response code of 200 and a `failureCount` parameter in the response body that is not '0'. For each failed PAN processing, the API response body includes a `reasonCode` and `description` to explain the failure. Please note that the `pans` object in the response body is encrypted by Mastercard, so you need to decrypt it. ### Endpoint {#endpoint} API Reference: `GET /consumers/pans/registrations` Here are the use cases supported by this API endpoint: #### Scenario 1: Create an Empty PAN List {#scenario-1-create-an-empty-pan-list} Issuers can create an empty PAN List by providing just the name of the PAN List and Account Range details. Also, they can add PANs to this list later. #### Scenario 2: Create a PAN List with Account Range \& PANs {#scenario-2-create-a-pan-list-with-account-range--pans} Issuers can create a new PAN List by providing the name of the PAN List, Account Range details, and a set of PANs. Mastercard will then check the PANs against the Account Range to ensure the data is correct. #### Scenario 3: Create a PAN List with PANs {#scenario-3-create-a-pan-list-with-pans} Issuers can create a new PAN List by providing the name of the PAN List and a set of PANs. In this case, Mastercard will determine the account range that the PAN belongs to, ensuring they all belong to the same Account Range. #### Scenario 4: Add PANs to an Existing PAN List {#scenario-4-add-pans-to-an-existing-pan-list} Issuers can add PANs to an existing PAN List by providing the `panListid` and a set of PANs. For more detailed information and examples, refer to the [API specification](https://developer.mastercard.com/unified-installments/documentation/api-reference/mastercard-installments-services/inbound-api/index.md#api). ### Deregister PAN from a PAN List {#deregister-pan-from-a-pan-list} This endpoint lets you remove a PAN (Primary Account Number) from a current PAN list. Issuers need to send encrypted PANs in the request body, following the encryption method specified by Mastercard. Mastercard will then validate the API request. The API can return one of the following responses: * **Success** : All PANs are processed successfully. This is shown when the HTTP response code is 200 and the `failureCount` parameter in the response body is '0'. * **Failure**: The API call fails. This is shown when the HTTP response code is not 200. * **Partial Success** : Some PANs are processed successfully, but others fail. This is shown when the HTTP response code is 200 and the `failureCount` parameter in the response body is not '0'. For each failed PAN processing, the API response body includes a `reasonCode` and `description` to explain the failure. Please note that the `pans` object in the response body is encrypted by Mastercard, so you need to decrypt it. ### Endpoint {#endpoint-1} API Reference: `GET /consumers/pans/deregistrations` Here are the use cases supported by this API endpoint: #### Scenario: Remove a PAN from an existing PAN List {#scenario-remove-a-pan-from-an-existing-pan-list} An Issuer can specify the `panListid` and the list of PANs that need to be removed from the current PAN List. For more detailed information and examples, refer to the detailed [API specification](https://developer.mastercard.com/unified-installments/documentation/api-reference/mastercard-installments-services/inbound-api/index.md#api). ## Installments Offers API {#installments-offers-api} The API allows distribution Partners to retrieve eligible installments offers for cardholders by providing PAN, merchant information, and transaction information. Distribution Partner must encrypt sensitive data in the API request body, as outlined in the API specification. The API uses the provided PAN, merchant details (like Merchant category code and merchant country), and transaction details (such as Amount, currency, and transaction timestamp) to check if there are any eligible offers. If eligible offers are found, the API returns the details of all offers. Distribution Partners can then share these offers with cardholders or consumers. For each offer, the API provides information about the tenure, interest rates, fees, terms and conditions, and a detailed loan repayment schedule. This information helps cardholders understand the repayment details. If no eligible offers match the request criteria, the API response will not include any offers. In this case, the Distribution Partner should inform the cardholders. For more detailed information and examples, refer to the [API specification](https://developer.mastercard.com/unified-installments/documentation/api-reference/mastercard-installments-services/inbound-api/index.md#api). ### Endpoint {#endpoint-2} API Reference: `GET /offers` ## Installments Plan API {#installments-plan-api} The API allows Distribution Partners to notify Mastercard when a cardholder chooses one of the installments offers previously shown through the Offer Presentment API. This chosen offer is known as an Installment Plan. The Distribution Partner needs to send the details of the selected offer, including the PAN, transaction information, merchant details, and offer specifics, without any changes. Mastercard then validates this data against the presented offer to ensure its integrity and provides a success or failure response. If the API processing is successful, it returns an HTTP status code of 201, a status of CREATED, and a unique Plan Identifier. In this scenario, the Distribution Partner can tell the cardholder that the installment offer has been processed successfully. However, if the API processing fails for some reason, it returns a corresponding HTTP status code. The response body includes a description and a reasonCode, which help the Distribution Partner understand why it failed and what corrective actions are needed. In this situation, the Distribution Partner should inform the cardholder about the failure in getting the installment. For more detailed information and examples, refer to the [API specification](https://developer.mastercard.com/unified-installments/documentation/api-reference/mastercard-installments-services/inbound-api/index.md#api). ### Endpoint {#endpoint-3} API Reference: `GET /plans` ## Installments Notification API {#installments-notification-api} This is an outbound notification from Mastercard to customer's API endpoint, to notify about the installment plan chosen by a cardholder. The API contains information about the cardholder, transaction, merchant and installments plan, using which the issuer or processor is expected to post the transaction as an Installments. Notification API will always contain funding PAN. If `POST /plans` API is invoked with a Token PAN, then Mastercard converts the Token PAN to corresponding funding PAN and sends it through Notification API. To configure the Notification API service, issuer must inform the same to the CIS representative. A customer needs to build and expose an API endpoint in their domain ensuring alignment with the following expectations: * API specification should strictly adhere to the [POST /notifications](https://developer.mastercard.com/unified-installments/documentation/api-reference/mastercard-installments-services/outbound-api/index.md#api) API definition. * The URL needs to be public and reachable on the internet. * It needs to be FQDN (Fully Qualified Domain Name) and HTTPS. * The domain name should be resolvable. * The URL should end with `/notifications` no other query parameter in URL or header is allowed or required. * Example of a non-supported URL `http://api.testcompany.com/?id=xxx` * Example of a supported URL: Accepted: `http://api.testcompany.com/notifications` * • Mastercard supports different destination paths for notifications in both MTF and Production environments. This endpoint requires partial request payload encryption using the JWE payload encryption. For implementation details, refer to the [Securing Sensitive Data Using Payload Encryption](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/) section. While sending an outbound API notification to customer, Mastercard would encrypt the `sensitiveData` object into `encryptedValues`, by using customer's public keys configured during project creation on the Mastercard Developers. Upon receiving the API call, customer is expected to decrypt the `encryptedValues` object into `sensitiveData`, using customer's private key, in order to obtain the clear PAN data. ### API response {#api-response} When customer successfully processes the API, they should return HTTP response code **201** as per the API specification. If a customer receives API call, which does not adhere to the API specification or encounters any other issue, customer can return an appropriate HTTP response code, along with the response body, strictly adhering to the API specification. ### API retry {#api-retry} After sending an Outbound API call to Customer's endpoint, if Mastercard receives HTTP error 5XX, then Mastercard will retry sending the notification API for up to 3 times with an internal of 1 minute initially AND after that 3 times after every one-hour interval indefinitely until the customer returns HTTP 201 response. The moment customer returns 201 responses, there will not be any further retries. For any HTTP response except 5XX, master card will not perform automatic retry of the API. ## Workflow {#workflow} ### During Purchase Transaction Workflow {#during-purchase-transaction-workflow} #### Auth enriched with Plan ID {#auth-enriched-with-plan-id} Diagram auth-during-purchase