Płać w ratach z Mastercard

1 Płać w ratach z Mastercard

Usługa aktualnie dostępna tylko na Sandbox!

"Płać w ratach z Mastercard" to usługa, która oferuje posiadaczom kart Mastercard możliwość podziału płatności za zakupy na miesięczne raty. Więcej szczegółów możesz znaleźć na stronie https://www.mastercard.pl/raty

Usługa "Płać w ratach z Mastercard" domyślnie jest włączona dla wszystkich merchantów, brak dodatkowych opłat za korzystanie z tej usługi.

2 Wykluczenia

Z usługi "Płać w ratach z Mastercard" wykluczone są POSy typu "Prowizja płatnika".

3 Integracja transparentna REST API

W celu udostępnienia płacącemu możliwości skorzystania z usługi "Płać w ratach z Mastercard" po udanej płatności kartą powinieneś wykonać nastepujace kroki:

3.1 Ustalenie, czy płatność może zostać rozłożona na raty

Ten i kolejne kroki powinny być wykonane po uzyskaniu przez zamówienie statusu COMPLETED (np. gdy otrzymaliśmy notyfikację o statusie COMPLETED).

W tym celu powinieneś pobrać dane o transakcji utworzonej do danego zamówienia. Jeśli płatność może zostać rozłożona na raty to w sekcji card pojawi się sekcja cardInstallmentProposal z indentyfikatorem propozycji ratalnej 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"
        }
      }
    }
  ]
}
                

W przypadku gdy płatność może zostać rozłożona na raty należy zaoferować płacącemu taką możliwość.

3.2 Pobranie propozycji ratalnej

Propozycja ratalna na środowisku Sandbox nie jest powiązana z kwotą zamówienia i zawsze zwraca dane dla kwoty 480 PLN.

Aby pobrać propozycję ratalną powinieneś wysłać żądanie GET na adres /api/v2_1/card-installment-proposals/{proposalId}

Odpowiedz będzie zawierała propozycję ratalną z opcjami w jednym z dwóch możliwych formatów:

  • VARYING_NUMBER_OF_OPTIONS – format z wieloma opcjami ratalnymi (od 1 do 12), z możliwością wyboru jednej z opcji;
  • VARYING_NUMBER_OF_INSTALLMENTS – format z jedną opcją ratalną, z możliwością wyboru liczby rat.
{
  "id": "5aff3ba8-0c37-4da1-ba4a-4ff24bcc2eed",
  "cardScheme": "MC",
  "installmentOptionFormat": "VARYING_NUMBER_OF_OPTIONS", // lub VARYING_NUMBER_OF_INSTALLMENTS
  "currencyCode": "PLN",
  "minNumberOfInstallments": 6,  // tylko dla VARYING_NUMBER_OF_INSTALLMENTS
  "maxNumberOfInstallments": 12, // tylko dla VARYING_NUMBER_OF_INSTALLMENTS
  "installmentOptions": [
    {
      "id": "1",
      "interestRate": 5.4,
      "installmentFeeAmount": 1000,
      "annualPercentageRate": 17.93,
      "totalAmountDue": 49440,
      "firstInstallmentAmount": 16480, // tylko dla VARYING_NUMBER_OF_OPTIONS
      "installmentAmount": 16480,      // tylko dla VARYING_NUMBER_OF_OPTIONS
      "numberOfInstallments": 3        // tylko dla VARYING_NUMBER_OF_OPTIONS
    }
  ]
}
                

Uwagi:

Parametr Opis
id Unikalny identyfikator propozycji ratalnej.
cardScheme Schemat karty (MC – Mastercard).
installmentOptionFormat Format opcji ratalnych ( VARYING_NUMBER_OF_OPTIONS, VARYING_NUMBER_OF_INSTALLMENTS).
currencyCode 3 literowy kod waluty.
minNumberOfInstallments Minimalna dopuszczona liczba rat - wartość od 2 do 99.
maxNumberOfInstallments Maksymalna dopuszczona liczba rat - wartość od 2 do 99.
installmentOptions.id Unikalny identyfikator opcji ratalnej.
installmentOptions.interestRate Oprocentowanie.
installmentOptions.installmentFeeAmount Kwota opłaty w groszach.
installmentOptions.annualPercentageRate Rzeczywista roczna stopa oprocentowania (RRSO).
installmentOptions.totalAmountDue Całkowita kwota do spłaty w groszach.
installmentOptions.firstInstallmentAmount Kwota pierwszej raty w groszach.
installmentOptions.installmentAmount Kwota kolejnych rat w groszach.
installmentOptions.numberOfInstallments Liczba rat.

Przykłady dla zamówienia o wartosci 480 PLN:

  • Format z wieloma opcjami ratalnymi (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 z jedną opcją ratalną (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
    }
  ]
}
                
Opcje ratalne powinny zostać zaprezentowane płacącemu. Zalecamy zaprezentowanie co najmniej:
  • ilości rat,
  • wysokości pierwszej raty,
  • całkowitej kwoty do spłaty.

3.3 Odesłanie decyzji płacącego

Na dokonanie wyboru opcji ratalnej płacący ma 15 minut.

W celu odesłania decyzji płacącego powinieneś wysłać żądanie POST na adres /api/v2_1/card-installment-proposals/{proposalId}/decisions, które zawiera w body komunikatu informacje jednoznacznie identyfikujące wybraną opcje:

{
  "optionId": "2",          // opcjonalne, wymagane dla formatu VARYING_NUMBER_OF_OPTIONS
  "numberOfInstallments": 9 // opcjonalne, wymagane dla formatu VARYING_NUMBER_OF_INSTALLMENTS
}
                

Decyzja płacącego jest widoczna w sekcji installmentDecision po ponownym pobraniu propozycji ratalnej:

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

W przypadku uzyskania w odpowiedzi kodu powodzenia (HTTP 204 - NO CONTENT) powinieneś poinformować płacacego, że wniosek o rozłożenie płatności na raty został przekazany do banku wydawcy karty. W przypadku dodatkowych pytań płacący powinien skontaktować się bezpośrednio z bankiem wydawcy karty w kolejnym dniu roboczym.

W przypadku uzyskania w odpowiedzi kodu błędu powinieneś poinformować płacącego, że wniosek o rozłożenie płatności na raty nie został przekazany do banku wydawcy karty. Jednakże płatność zakończyła się sukcesem i karta zostanie obciążona pełną kwotą zamówienia. Możliwe kody błędów można znaleźć poniżej.

4 Kody błędów

Następujący komunikat błędu zostanie zwrócony w przypadku próby pobrania możliwych opcji ratalnych lub odesłania decyzji płacącego dla nieistniejącej propozycji ratalnej:

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

Poniższa tabela przedstawia możliwe błędy wraz z ich opisem:

Kod Statusu HTTP Kod Statusu Kod błędu Opis
422 INVALID_OPTION_ID 4301 Decyzja zawiera nieprawidłową wartość parametru optionId.
INSTALLMENT_PROPOSAL_EXPIRED 4302 Minął czas na wybranie opcji ratalnej.
INVALID_NUMBER_OF_INSTALLMENTS 4303 Decyzja zawiera nieprawidłową wartość parametru numberOfInstallments.
DIFFERENT_INSTALLMENT_DECISION_EXISTS 4304 Dokonano już wyboru innej opcji ratalnej.
404 INSTALLMENT_PROPOSAL_NOT_FOUND 4305 Nie znaleziono propozycji ratalnej.
500 ERROR_INTERNAL 106 Wewnętrzny błąd.