Mastercard Installments

"Pay in installments with Mastercard" is a service that offers Mastercard cardholders the option to divide their payments into monthly installments. Additional information about this service can be found on the mastercard installments page.

The "Pay in installments with Mastercard" service is automatically enabled for all merchants by default, and there are no extra charges associated with utilizing this service.

Integrating PayU Payment Page

Merchants using PayU payment page integration do not need to perform any additional action to offer "Pay in installments with Mastercard" service to the customers.

You can try the "Pay in installments with Mastercard" service by clicking the below button. You will be redirected to the PayU sandbox payment page. Use any card from the table on the Sandbox page that has yes in the Mastercard Installments column. Next, nn the Payment Status page, choose the Split Into Installments option.

Exclusions

POS of type Payer's commission are excluded from "Pay in installments with Mastercard" service.

Integrating Mastercard Intallments on the Checkout Page

To provide the "Pay in installments with Mastercard" service to customers following a successful card payment, you need to:

Determine if the payment is eligible for installment splitting.
Retrieve the installment proposal.
Transmit the payer's decision back.

When Payment can be Split into Installments?

Notes

These steps, along with the subsequent ones, should only be executed after the status of an order has reached COMPLETED (upon receiving a notification indicating the status COMPLETED).

To determine if the payment can be split into installments, you need to retrieve order transaction data. If the payment is eligible for installment splitting, the card section will encompass a cardInstallmentProposal subsection with an installment proposal identifier labeled as proposalId.

Example of Retrieved Order Transaction Data
{
    "transactions": [
        {
            "payMethod": {
                "value": "c"
            },
            "paymentFlow": "CARD",
            "card": {
                "cardData": {
                    "cardNumberMasked": "543402******4014",
                    "cardScheme": "MC",
                    "cardProfile": "CONSUMER",
                    "cardClassification": "DEBIT",
                    "cardResponseCode": "000",
                    "cardResponseCodeDesc": "000 - OK",
                    "cardEciCode": "7",
                    "card3DsStatus": "VN",
                    "cardBinCountry": "PL"
                },
                "cardInstallmentProposal": {
                    "proposalId": "5aff3ba8-0c37-4da1-ba4a-4ff24bcc2eed"
                }
            }
        }
    ]
}

If the payment is eligible for installment splitting, you should then present this option to the payer.

Fetching Installments Proposal

GET Request Body

When making GET requests, please remember not to include any data in the request body, as specified in the RFC 9110 standard. Requests that do not adhere to this requirement will be rejected by PayU with an HTTP 403 status.

In the Sandbox environment, the installment proposal is not linked to the order amount and consistently provides data for 480 PLN.

To retrieve installment proposal you should send GET request to /api/v2_1/card-installment-proposals/{proposalId}

Response will contain installment proposal with options in one out of two possible formats:

VARYING_NUMBER_OF_OPTIONS - format with multiple installment options (1 to 12), single option to choose;
VARYING_NUMBER_OF_INSTALLMENTS - format with single installment option, number of installments to choose.

Response Example for Fetching Installment Proposal
{
    "id": "5aff3ba8-0c37-4da1-ba4a-4ff24bcc2eed",
    "cardScheme": "MC",
    "installmentOptionFormat": "VARYING_NUMBER_OF_OPTIONS", // or VARYING_NUMBER_OF_INSTALLMENTS
    "currencyCode": "PLN",
    "minNumberOfInstallments": 6, // only for VARYING_NUMBER_OF_INSTALLMENTS
    "maxNumberOfInstallments": 12, // only for VARYING_NUMBER_OF_INSTALLMENTS
    "installmentOptions": [
        {
            "id": "1",
            "interestRate": 5.4,
            "installmentFeeAmount": 1000,
            "annualPercentageRate": 17.93,
            "totalAmountDue": 49440,
            "firstInstallmentAmount": 16480, // only for VARYING_NUMBER_OF_OPTIONS
            "installmentAmount": 16480, // only for VARYING_NUMBER_OF_OPTIONS
            "numberOfInstallments": 3 // only for VARYING_NUMBER_OF_OPTIONS
        }
    ]
}

For details on parameters, please refer to the Card Installments Proposal section in our API Reference.

Examples for order amount of 480 PLN:

VARYING_NUMBER_OF_OPTIONS
VARYING_NUMBER_OF_INSTALLMENTS

{
    "id": "2bd92572-d32f-4aa8-b486-be51629811e5",
    "cardScheme": "MC",
    "installmentOptionFormat": "VARYING_NUMBER_OF_OPTIONS",
    "currencyCode": "PLN",
    "installmentOptions": [
        {
            "id": "1",
            "interestRate": 5.4,
            "installmentFeeAmount": 1000,
            "annualPercentageRate": 17.93,
            "totalAmountDue": 49440,
            "firstInstallmentAmount": 16480,
            "installmentAmount": 16480,
            "numberOfInstallments": 3
        },
        {
            "id": "2",
            "interestRate": 5.2,
            "installmentFeeAmount": 1100,
            "annualPercentageRate": 13.05,
            "totalAmountDue": 49848,
            "firstInstallmentAmount": 8308,
            "installmentAmount": 8308,
            "numberOfInstallments": 6
        },
        {
            "id": "3",
            "interestRate": 5,
            "installmentFeeAmount": 1200,
            "annualPercentageRate": 9.64,
            "totalAmountDue": 50544,
            "firstInstallmentAmount": 4344,
            "installmentAmount": 4200,
            "numberOfInstallments": 12
        }
    ]
}

{
    "id": "9c0d357d-7f78-42d2-898b-1fc9b528ac63",
    "cardScheme": "MC",
    "installmentOptionFormat": "VARYING_NUMBER_OF_INSTALLMENTS",
    "currencyCode": "PLN",
    "minNumberOfInstallments": 6,
    "maxNumberOfInstallments": 12,
    "installmentOptions": [
        {
            "id": "1",
            "interestRate": 0,
            "installmentFeeAmount": 0,
            "annualPercentageRate": 0,
            "totalAmountDue": 48000
        }
    ]
}

If the response doesn't include the installmentDecision section, you should display installment options to the payer. We recommend presenting, at the very least:

The number of installments.
The amount of the first installment.
The total amount due.

If the response contains an installmentDecision section, rather than presenting installment options, you should notify the payer that the installment request has been submitted to the card issuing bank. For any additional inquiries, the payer should directly contact the card issuing bank during the next business day.

Sending Back Payer's Descision

Notes

Payer has 15 minutes to make selection.

To return the payer's decision, you should send a POST request to /api/v2_1/card-installment-proposals/{proposalId}/decisions endpoint with a body containing data that uniquely identifies the selected installment option:

Decision Request Body Example
{
    "optionId": "2", // optional, required for VARYING_NUMBER_OF_OPTIONS format
    "numberOfInstallments": 9 // optional, required for VARYING_NUMBER_OF_INSTALLMENTS format
}

Payer's decision is visible in the installmentDecision section when installment proposal is fetched again:

installmentDecision Section Example
{
  "id": "5aff3ba8-0c37-4da1-ba4a-4ff24bcc2eed",
  (...)
  "installmentDecision": {
    "optionId": "3",
    "numberOfInstallments": 12,
    "createTime": "2021-03-05T12:58:14.828+01:00"
  }
}

In case of a successful response (HTTP 204 - NO CONTENT), you should inform the payer that the request for installment payment has been forwarded to the card issuing bank. In case of further questions, the payer should contact the card issuing bank directly within the next business day.

In case of error response you should inform the payer that the request for payment in installments has not been forwarded to the card issuing bank but the payment is successful and the card will be charged for the full order amount. Possible error responses are listed below.

Error Messages

Following error response will be returned when trying to retrieve card installment proposal or sending back payer's decision for installment proposal that does not exist:

Error Response Example
{
    "status": {
        "statusCode": "INSTALLMENT_PROPOSAL_NOT_FOUND",
        "severity": "ERROR",
        "code": "4305",
        "statusDesc": "Given installment proposal not found"
    }
}

Possible Error Codes Specific for Mastercard Installments

HTTP Status	StatusCode	Code	Description
422	INVALID_OPTION_ID	4301	Decision contains invalid value of `optionId` parameter.
422	INSTALLMENT_PROPOSAL_EXPIRED	4302	Time to send back payer's decision has lapsed.
422	INVALID_NUMBER_OF_INSTALLMENTS	4303	Decision contains invalid value of `numberOfInstallments` parameter.
422	DIFFERENT_INSTALLMENT_DECISION_EXISTS	4304	Decision has already been made with different installment option.
404	INSTALLMENT_PROPOSAL_NOT_FOUND	4305	Installment proposal has not been found.
500	ERROR_INTERNAL	106	Internal error.

Integrating PayU Payment Page​

Integrating Mastercard Intallments on the Checkout Page​

When Payment can be Split into Installments?​

Fetching Installments Proposal​

Sending Back Payer's Descision​

Error Messages​

On this page