Pay in installments with Mastercard

1 Pay in installments with Mastercard

Service currently available only at Sandbox!

"Pay in installments with Mastercard" is a service that allows Mastercard card holders to split payments into monthly installments. You can find more details on https://www.mastercard.pl/raty

"Pay in installments with Mastercard" service is enabled by default for all merchants, there are no additional charges to use this service.

2 Exclusions

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

3 REST API transparent integration

In order to offer "Pay in installments with Mastercard" service to the customers after successful card payment you have to:

3.1 Determine if payment can be split into installments

This and later steps should be performed only after status of an order is COMPLETED (e.g. notification with the status COMPLETED has been received).

For this purpose you have to retrieve order transaction data. If payment can be split into installments then card section will contain cardInstallmentProposal subsection with installment proposal identifier proposalId.

{
  "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 can be split into installments, then such possibility should be presented to the payer.

3.2 Fetch installment proposal

Installment proposal on the Sandbox environment is not related to the order amount and always returns data for 480 PLN.

For this purpose 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.
{
  "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
    }
  ]
}
                

Remarks:

Parameter Description
id Unique identifier of installment proposal.
cardScheme Card scheme (MC – Mastercard).
installmentOptionFormat Installment option format ( VARYING_NUMBER_OF_OPTIONS, VARYING_NUMBER_OF_INSTALLMENTS)
currencyCode 3-letter currency code.
minNumberOfInstallments Minimum number of installments allowed, values from 2 to 99.
maxNumberOfInstallments Maximum number of installments allowed, values from 2 to 99.
installmentOptions.id Identifier of installment option.
installmentOptions.interestRate Interest rate.
installmentOptions.installmentFeeAmount Installment fee amount in pennies.
installmentOptions.annualPercentageRate Annual percentage rate (APR).
installmentOptions.totalAmountDue Total amount due in pennies.
installmentOptions.firstInstallmentAmount First installment amount in pennies.
installmentOptions.installmentAmount Subsequent installment amounts in pennies.
installmentOptions.numberOfInstallments Number of installments.

Examples for order amount of 480 PLN:

  • Format with multiple installment options (VARYING_NUMBER_OF_OPTIONS):
{
  "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
    }
  ]
}
                
  • Format with single installment option (VARYING_NUMBER_OF_INSTALLMENTS):
{
  "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
    }
  ]
}
                
Installment options should be presented to the payer. We advise to present at minimum:
  • number of installments,
  • first installment amount,
  • total amount due.

3.3 Send back payer's decision

Payer has 15 minutes to make selection.

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

{
  "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 installmentDecision section when installment proposal is fetched again:

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

In case of success response (HTTP 204 - NO CONTENT) you should inform the payer that request for payment in installments has been forwarded to card issuing bank. In case of further questions payer should directly contact card issuing bank in next working day.

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

4 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:

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

Table below presents possible error codes and their descriptions:

HTTP status StatusCode Code Description
422 INVALID_OPTION_ID 4301 Decision contains invalid value of optionId parameter.
INSTALLMENT_PROPOSAL_EXPIRED 4302 Time to send back payer's decision has lapsed.
INVALID_NUMBER_OF_INSTALLMENTS 4303 Decision contains invalid value of numberOfInstallments parameter.
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.