Przejdź do głównej zawartości

Płać w ratach z Mastercard

"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 Płać w ratach z Mastercard.

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.

Integrowanie strony płatności PayU

Merchant bezpośrednio zintegrowany ze stroną płatniczą PayU, w celu udostępnienia płacącemu usługi "Płać w ratach z Mastercard" nie musi wykonywać żadnych dodatkowych akcji.

Możesz sprawdzić jak wygląda proces płatniczy w przypadku usługi "Płać w ratach z Mastercard". Naciśnij poniższy przycisk a zostaniesz przekierowany na testową stronę płatniczą PayU. Do płatności użyj jednej z kart z sekcji Karty testowe z wartością tak w kolumnie Raty Mastercard. Następnie na stronie ze satusem płatności wybierz opcję Rozkładam na raty.

Wykluczenia

Punkty płatności typu "Prowizja płatnika" są wyłączone z usługi "Płać w ratach z Mastercard".

Integracja white label rat Mastercard

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:

  • ustalić, czy płatność może zostać rozłożona na raty,
  • pobrać propozycję rat,
  • odesłać decyzję płacącego.

Kiedy płatność może zostać rozłożona na raty?

Notatka

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

Aby ustalić czy płatność moża zostać rozłożona na raty powinieneś pobrać dane transakcyjne 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.

Przykład pobranych danych transakcyjnych
{
"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ść.

Pobranie propozycji ratalnej

Ciało żądania metody GET

Wysyłając żądania z metodą GET upewnij się, że w ciele żądania nie przesyłasz żadnych danych. Zgodnie ze standardem RFC 9110 żądania, które nie spełniają tego wymogu, zostaną odrzucone przez PayU i zwrócony zostanie kod HTTP 403.

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 metodą GET na endpoint /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.
Przykład odpowiedzi po pobraniu propozycji ratalnej
{
"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
}
]
}

Szczegółowe informacje na temat parametrów, znajdziesz w sekcji Mastercard Installments w naszej referencji API.

Przykłady dla kwoty zamówienia 480 PLN:

{
"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
}
]
}

W przypadku uzyskania odpowiedzi, która nie zawiera sekcji installmentDecision zaprezentuj płącącemu opcje ratalne do wyboru. Zaleca się zaprezentowanie co najmniej:

  • ilości rat,
  • wysokości pierwszej raty,
  • całkowitej kwoty do spłaty.

W przypadku uzyskania odpowiedzi, która zawiera sekcje installmentDecision zamiast wyświetlać opcje ratalne należy 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.

Odesłanie decyzji płacącego

Notatka

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

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

Przykład ciała żądania
{
"optionId": "2", // optional, required for VARYING_NUMBER_OF_OPTIONS format
"numberOfInstallments": 9 // optional, required for VARYING_NUMBER_OF_INSTALLMENTS format
}

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

Przykład sekcji installmentDecision
{
"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 znajdziej w poniższej sekcji.

Błędy

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:

Przykład odpowiedzi z błędem
{
"status": {
"statusCode": "INSTALLMENT_PROPOSAL_NOT_FOUND",
"severity": "ERROR",
"code": "4305",
"statusDesc": "Given installment proposal not found"
}
}
Możliwe błędy w usłudze Płać w ratach z Mastercard
Status HTTP
Kod statusu
Kod
Opis
422INVALID_OPTION_ID4301Decyzja zawiera nieprawidłową wartość parametru optionId.
422INSTALLMENT_PROPOSAL_EXPIRED4302Minął czas na wybranie opcji ratalnej.
422INVALID_NUMBER_OF_INSTALLMENTS4303Decyzja zawiera nieprawidłową wartość parametru numberOfInstallments.
422DIFFERENT_INSTALLMENT_DECISION_EXISTS4304Dokonano już wyboru innej opcji ratalnej.
404INSTALLMENT_PROPOSAL_NOT_FOUND4305Nie znaleziono propozycji ratalnej.
500ERROR_INTERNAL106Wewnętrzny błąd.