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:

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

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

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
422	INVALID_OPTION_ID	4301	Decyzja zawiera nieprawidłową wartość parametru optionId.
422	INSTALLMENT_PROPOSAL_EXPIRED	4302	Minął czas na wybranie opcji ratalnej.
422	INVALID_NUMBER_OF_INSTALLMENTS	4303	Decyzja zawiera nieprawidłową wartość parametru numberOfInstallments.
422	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.