Płatności cykliczne

1 O produkcie

PayU ǀ Płatności cykliczne polegają na cyklicznym obciążaniu karty płatniczej. Wprowadzenie tej usługi pozwala na wyeliminowanie konieczności podawania numeru karty przy każdej płatności. To prosty sposób na zwiększenie liczby lojalnych konsumentów i zwiększenie zysków z eCommerce!

Usługa ta rekomendowana jest szczególnie firmom oferującym sprzedaż na podstawie abonamentów, subskrypcji, karnetów (kluby fitness, centra medyczne, media, firmy ubezpieczeniowe, serwisy oferujące prenumeraty itd).

Transparentna integracja

Usługa płatności cyklicznej opiera się na transparentnej integracji, tj. odbywa się bez przekierowania na formularz PayU. Pomimo tego taka integracja jest bezpieczna i minimalizuje obowiązki wynikające z PCI DSS. Ponadto daje więcej elastyczności i zwiększa konwersję (ilość udanych płatności), ponieważ płatność odbywa się na stronie sklepu.

Proces płatności odbywa się w dwóch krokach - najpierw należy uzyskać dane karty (poprzez widget PayU lub poprzez formularz), a następnie obciążyć kartę. Dane karty są zwracane z PayU w postaci tokena wraz maskowanym numerem karty oraz datą ważności - sklep nie otrzymuje i nie musi przetwarzać pełnego numeru karty.

Płatności cykliczne polegają na obciążaniu tokenów wielorazowych. Wszystkie transakcje poza pierwszą, która inicjuje cykl, nie są wywoływane przez płacącego, ale bezpośrednio przez aplikację sklepu. Dlatego takie transakcje nie wymagają dodatkowego uwierzytelnienia poprzez 3DS lub podanie kodu bezpieczeństwa (CVV2/CVC2). W celu obciążania karty zgodnie z harmongramem (cyklem, subskrypcją) na który płatnik wyraził zgodę, aplikacja sklepowa powinna posiadać stosowną funkcjonalność (ang. scheduler).

Konfiguracja w PayU

Płatność cykliczna wymaga specjalnej konfiguracji po stronie PayU. Dlatego przed przystąpieniem do integracji należy skontaktować się z opiekunem handlowym w PayU.

Wymogi i zalecenia dot. bezpieczeństwa

Zanim przystąpisz do integracji usługi, zapoznaj się z zaleceniami i wymogami przygotowanymi przez ekspertów ds. bezpieczeństwa w PayU. Ich przestrzeganie pomoże zminimalizować ryzyko związane z transakcjami oszukańczymi.

2 Integracja usługi

Płatności cykliczne opierają sie na tokenizacji danych karty. Kroki:
  • (pierwsza płatność) tokenizacja karty, można wykorzystać formularz lub (najlepiej) widget PayU; uwierzytelnienie przez 3DS/CVV2 jest wymagane; PayU zwraca token jednorazowy
  • (pierwsza płatność) należy wysłać komunikat OrderCreateRequest (zob. niżej) z tokenem jednorazowym, w odpowiedzi system PayU przekazuje token wielorazowy
  • (druga i kolejne płatności) należy wysłać komunikat OrderCreateRequest z tokenem wielorazowym, 3DS/CVV2 nie są wymagane

Płatność z tokenem jednorazowym (pierwsza w cyklu):

Płatność z tokenem wielorazowym (druga i kolejne w cyklu):

2.1 Front-end

Poniższy opis dotyczy widgeta pop-up. Można również wykorzystać widget wlewany (inline), ale należy pamiętać, że wlewany widget nie zawiera nagłówka, który informuje płatnika, że dana płatność inicjuje cykl i jest pierwszą z wielu.

Modyfikacja frontu: widget

1. Należy włączyć do strony sklepu formularz z przyciskiem płatności. W tym celu należy podać właściwy parametr:
                    <form action="http://exampledomain.com/processOrder.php" method="post">
                        <button id="pay-button">Pay now</button>
                    </form>
                
2. Należy dołączyć skrypt JS wywołujący widget podając odpowiednie parametry i wyliczyć SIG:
                    <script
                        src="https://secure.payu.com/front/widget/js/payu-bootstrap.js"
                        pay-button="#pay-button"
                        merchant-pos-id="145227"
                        shop-name="Nazwa sklepu"
                        total-amount="9.99"
                        currency-code="PLN"
                        customer-language="pl"
                        store-card="true"
                        recurring-payment="true"
                        customer-email="email@exampledomain.com"
                        sig="4752ce2b163684a9c27cc0923ad46068c04da5d34329f5669ce73dcf96394558">
                    </script>
                

3. Aby wyliczyć SIG, należy użyć następującego algorytmu: Parametry widgeta.

Modyfikacja frontu: formularz

Należy dołączyć skrypty OpenPayU, które umożliwiają bezpieczne przesyłanie danych karty bezpośrednio do PayU:
                    <script src="https://secure.payu.com/res/v2/jquery-1.7.2.js"></script>
                    <script src="https://secure.payu.com/res/v2/openpayu-2.0.js"></script>
                    <script src="https://secure.payu.com/res/v2/plugin-token-2.0.js"></script>
                
Formularz należy zbudować w sposób umożliwiający prawidłowe działanie skryptów. W tym celu elementy w <form> powinny mieć poniższą strukturę:
                    <form action="" method="post">
                        <table>
                            <tr>
                                <td>Numer karty</td>
                                <td><input type="text" class="payu-card-number"></td>
                            </tr>
                            <tr>
                                <td>CVV2/CVC2</td>
                                <td><input type="text" class="payu-card-cvv"></td>
                            </tr>
                            <tr>
                                <td>miesiąc</td>
                                <td><input type="text" class="payu-card-expm"></td>
                            </tr>
                            <tr>
                                <td>rok</td>
                                <td><input type="text" class="payu-card-expy"></td>
                            </tr>
                            <tr>
                                <td>Akceptacja regulaminu Konta PayU i zgoda na zapisanie karty</td>
                                <td><input type="checkbox" value="false" class="payu-agreement"></td>
                            </tr>                            
                            <input type="hidden" class="payu-customer-email" value="...@...">
                                <tr>
                                    <td><input type="submit" id="payu-cc-form-submit"></td>
                                </tr>
                        </table>
                    </form>
                

Skrypty wyszukują następujące nazwy klas:

Nazwa Wymagana Opis
payu-card-cardholder opcjonalna Imię i nazwisko posiadacza karty.
payu-card-number tak Numer karty płatniczej.
payu-card-cvv tak Kod bezpieczeństwa karty (CVV2/CVC2).
payu-card-expm tak Miesiąc daty ważności.
payu-card-expy tak Rok daty ważności.
payu-agreement tak Wartości true/false. Oznacza zgodę posiadacza karty na zapisanie danych i regulamin Konta PayU. Przy wartości false PayU nie zwróci tokena wielorazowego.
payu-customer-email opcjonalna Adres email posiadacza karty.

Następnie należy dodać skrypt, który zajmuje się komunikacją między stroną sklepu, aplikacją sklepu i PayU:
                    //creates single-use token and sends it to merchant url_handler
                    OPU(function() {
                        OpenPayU.merchantId = 'pos_id';
                        ocrq_handler_url    = "handler url in your system";
                        OPU('#payu-cc-form-submit').click(function() {
                            OpenPayU.Token.create({}, function(data) {
                                OPU.post(ocrq_handler_url, data, function(response) {
                                    handle_ocrs_statuses(response);
                                });
                            });
                        return false;
                        });
                    }());
                    
                    //response - zawiera odpowiedź do komunikatu OrderCreateRequest
                    //           wysłanego przez aplikację sklepu do PayU
                    function handle_ocrs_statuses(response) {
                        if (response.status == 'SUCCESS') {
                             //wyczyść i schowaj dane karty 
                          }else{
                             // WARNING_CONTINUE_CVV lub WARNING_CONTINUE_3DS, zob. niżej,
                             // lub obsługa błędu
                         }
                    };
                

Wizualizacja statusów:

2.2 Back-end

Modyfikacja back-endu

Tworzenie Zamówienia (Order) poprzez REST API jest opisane tutaj. Dla płatności drugiej i kolejnych w cyklu należy rozszerzyć komunikat OrderCreateRequest o sekcję payMethods podając jako wartość token wielorazowy (TOKC_) oraz podać parametr "recurring" zgodnie z przykładem poniżej.

Uwaga: pierwsza płatność w cyklu (Order) odbywa się tokenem jednorazowym (TOK_) i nie powinna zawierać parametru "recurring".

Ponadto dla pierwszej płatności, w przypadku odpowiedzi z kodem WARNING_CONTINUE_3DS, należy przekierować płatnika na stronę banku wydawcy karty w celu dodatkowego uwierzytelnienia płatności w procesie 3D Secure.

Przykładowy komunikat OrderCreateRequest dla drugiej i kolejnych płatności cyklicznych:

                    curl -v -X POST https://secure.payu.com/api/v2_1/orders \
                    -H "Content-Type: application/json" \
                    -H "Authorization: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd" \
                    -d '{
                          "notifyUrl":"https://your.eshop.com/notify",
                          "customerIp":"127.0.0.1",
                          "merchantPosId":"145227",
                          "recurring": "STANDARD",
                          "description":"Laptop",
                          "currencyCode":"PLN",
                          "totalAmount":"15000",
                          "extOrderId":"[generateExtOrderId]",
                          "products":[
                             {
                                "name":"Laptop",
                                "unitPrice":"15000",
                                "quantity":"1"
                             }
                          ],
                          "buyer": {
                              "email": "john.doe@example.com",
                              "firstName": "John",
                              "lastName": "Doe",
                              "language": "en"
                          },                          
                          "payMethods": {
                              "payMethod": {
                                   "value": "TOKC_1IHRPT6HKSSS3H62K0GS8pElP862",
                                   "type": "CARD_TOKEN"
                              }
                          }
                      }'
                

Sposób uwierzytelnienia jest opisany tutaj.

POS użyty w przykładzie powyżej nie jest skonfigurowany do tokenizacji kart.

Odpowiedzi:

Przykład odpowiedzi z kodem SUCCESS dla pierwszej płatności w cyklu. W odpowiedzi podany jest token wielorazowy:
{
     "orderId": "ORDER_ID",
     "payMethods": {
         "payMethod": {
              "card": {
                   "number": "424242******4242",
                   "expirationMonth": "12",
                   "expirationYear": "2017"
               },
               "type": "CARD_TOKEN",
               "value": "TOKC_KPNZVSLJUNR4DHF5NPVKDPJGMX7"
           }
       },
       "status": {
           "statusCode": "SUCCESS",
           "statusDesc": "Request successful"
       }
}
                
Przykład odpowiedzi z kodem WARNING_CONTINUE_3DS (pierwsza płatność):
{
     "orderId": "ORDER_ID",
     "status": {
         "statusCode": "WARNING_CONTINUE_3DS",
         "severity": "WARNING"
     },
     "redirectUri": "{redirectUri}"
}
                
Przykład odpowiedzi z kodem WARNING_CONTINUE_CVV (pierwsza płatność):
{
     "orderId": "ORDER_ID",
     "status": {
         "statusCode": "WARNING_CONTINUE_CVV",
         "severity": "WARNING"
     },
     "redirectUri": "{redirectUri}"
}
                

System PayU powiadamia sklep o statusie zamówienia poprzez wysłanie notyfikacji na adres podany w parametrze notifyUrl w komunikacie OrderCreateRequest. Więcej informacji o notyfikacjach znajduje się tutaj.

2.3 Pobieranie tokenów

Pobieranie metod płatności

Zalecamy, aby metody płatności dostępne dla danego użytkownika nie były przechowywane lokalnie przez sklep, ale raczej pobierane od PayU. Pobierane są zarówno zapisane metody płatności (tokeny) oraz standardowe metody płatności. Użycie tej usługi daje następujące korzyści:

- zwracane są wyłącznie metody płatności dostępne w danym momencie dla danego użytkownika,

- zwrócone tokeny są zawsze aktualne i zsynchronizowane z Kontem PayU danego użytkownika.

W celu pobrania metod płatności należy najpierw uzyskać token dostępowy OAuth2.

Uzyskiwanie tokena dostępowego OAuth

Aby uzyskać token dostępowy należy wywołać żądanie metodą POST na endpoint /pl/standard/user/oauth/authorize.

Żądanie należy wywołać z grant_type równym trusted_merchant.

apiary

Przykładowe żądanie:

curl 
-X POST 
-H "Cache-Control: no-cache" 
-H "Content-Type: application/x-www-form-urlencoded" 
-d 'grant_type=trusted_merchant&client_id=[provided by PayU]&client_secret=[provided by PayU]&email=[users email]&ext_customer_id=[Id of the customer used in merchant system]' 
'https://secure.payu.com/pl/standard/user/oauth/authorize'
                
Przykładowa odpowiedź (HTTP 200):
{
    "access_token": "4099c2c3-276f-488a-90e2-32620ac441dc",
    "token_type": "bearer",
    "expires_in": 43199,
    "grant_type": "trusted_merchant"
}
            

Pobieranie metod płatności

Należy wstawić uzyskany token dostępowy do nagłówka i wywołać żądanie metodą GET na endpoint api/v2_1/paymethods .

apiary

Przykładowe żądanie:
curl 
-X GET 
-H "Authorization: Bearer 87ad751f-7ea5-4023-a16f-04b6647a07f5" 
-H "Cache-Control: no-cache" 
'https://secure.payu.com/api/v2_1/paymethods'
                

Przykładowa odpowiedź (HTTP 200). Opis poszczególnych pól jest poniżej.

{  
   "cardTokens":[  
      {  
         "cardExpirationYear":"2017",
         "cardExpirationMonth":"12",
         "cardNumberMasked":"411111******1111",
         "cardBrand":"VISA",
         "value":"TOKC_XATB7DF8ACXYTVQIPLWTVPFRKQE",
         "brandImageUrl":"http://static.payu.com/images/mobile/visa.png",
         "preferred":true,
         "status":"ACTIVE"
      },
      {  
         "cardExpirationYear":"2014",
         "cardExpirationMonth":"12",
         "cardNumberMasked":"424242******4242",
         "cardBrand":"VISA",
         "value":"TOKC_XATB7DF8ACXYTVQIPLWTVPFRKQE",
         "brandImageUrl":"http://static.avocado.qxlint/images/mobile/visa.png",
         "preferred":false,
         "status":"EXPIRED"
      }
   ],
   "pexTokens":[  
      {  
         "accountNumber":"5311...7744",
         "payType":"mtex",
         "value":"TOKE_XPJ4UKJGHVRPMQPGB6X1JJQCUSS",
         "name":"account name set by the user",
         "brandImageUrl":"http://static.payu.com/images/mobile/logos/pex_mbank.png",
         "preferred":false,
         "status":"ACTIVE"
      }
   ],
   "payByLinks":[  
      {  
         "value":"c",
         "name":"Płatność online kartą płatniczą",
         "brandImageUrl":"http://static.payu.com/images/mobile/logos/pbl_c.png",
         "status":"ENABLED"
      },
      {  
         "value":"o",
         "name":"Pekao24Przelew",
         "brandImageUrl":"http://static.payu.com/images/mobile/logos/pbl_o.png",
         "status":"DISABLED"
      },
      {  
         "value":"ab",
         "name":"Płacę z Alior Bankiem",
         "brandImageUrl":"http://static.payu.com/images/mobile/logos/pbl_ab.png",
         "status":"TEMPORARY_DISABLED"
      }
   ]
}          
            

cardTokens

Ta sekcja zostanie zwrócona jako pusta, jeśli użytkownik nie ma żadnych aktywnych lub wygasłych tokenów.
Parametr Opis
cardExpirationYear Rok ważności karty w formacie RRRR
cardExpirationMonth Miesiąc ważności karty w formacie MM
cardNumberMasked Maskowany numer karty (pierwsze 6 i ostatnie 4 cyfry).
cardBrand Rodzaj karty. Wartości: 'VISA', 'MASTERCARD', 'MAESTRO'. Inne rodzaje nie są wspierane, ponadto 'MAESTRO' nie jest wspierane w płatnościach cyklicznych. VISA oznacza różne marki kart Visa, w tym Visa Electron. MASTERCARD oznacza również MasterCard Debit.
value Wartość tokena.
brandImageUrl Odnośnik do grafiki na serwerze PayU reprezentującej logo karty.
preferred Wartości true/false; 'true' oznacza ostatnio użyty token.
status Wartości: 'ACTIVE' i 'EXPIRED'.'EXPIRED' oznacza tokeny wygasłe, można ich nie prezentować lub prezentować wraz z prośbą o podanie aktywnego numeru karty (tj. ponowne podanie numeru karty wygasłej wraz z nową datą ważności i CVV2/CVC2 lub zupełnie nowego numeru).Token nie będzie prezentowany, jeśli został anulowany przez użytkownika lub zablokowany ze względów bezpieczeństwa przez PayU.

pexTokens

Ta sekcja będzie pusta jeśli użytkownik nie ma żadnych aktywnych tokenów.

Tokeny PEX oznaczają rachunki bankowe dostępne przez usługę PayU|Express.

Parametr Opis
accountNumber Pierwsze i ostatnie 4 cyfry rachunku bankowego.
payType Represents payType of the token. Oznacza typ platności (bank) powiązany z danym tokenem.
name Nazwa konta nadana przez użytkownika.
value Wartość tokena.
brandImageUrl Odnośnik do grafiki na serwerze PayU reprezentującej bank.
preferred Wartości true/false; 'true' oznacza ostatnio użyty token.
status Wartości: 'ACTIVE'. Token nie będzie prezentowany, jeśli został anulowany przez użytkownika lub zablokowany ze względów bezpieczeństwa przez PayU.

payByLinks

payByLinks to metody płatności, które zawsze wymagają przekierowania. Oznaczają zarówno szybkie przelewy (pay-by-links), tradycyjny przelew, raty lub standardową płatność kartą bez tokenizacji poprzez formularz serwowany przez PayU.
Parametr Opis
value Wartość metody płatności. Dostępne wartości są tutaj.
name Nazwa typu płatności nadana przez PayU.
brandImageUrl Odnośnik do grafiki na serwerze PayU reprezentującej metodę płatności.
status Możliwe wartości: 'ENABLED' (aktywna), 'DISABLED' (nieaktywna), 'TEMPORARY_DISABLED' (czasowo nieaktywna z uwagi na brak rozliczeń online po stronie banku - wartość wystąpi po dokonaniu dodatkowej konfiguracji przez PayU).

2.4 Parametry widgeta

Parametr SIG (służący zabezpieczeniu widgeta przed modyfikacją) należy wyliczyć w następujący sposób:

  1. Posortować alfabetycznie parametry potrzebne do wyliczenia SIGa (zob. tab. niżej).
  2. Połączyć wartości parametrów wg kolejności sortowania.
  3. Dodać wartość klucza prywatnego - widocznego w Panelu PayU jako 'Drugi klucz (MD5)'.
  4. Wykonać funkcję SHA256 na całym ciągu znaków.
  5. Wstawić wynik funkcji jako parametr SIG przy wywołaniu widgeta.
Parametry skryptu wywołującego widget:
Nazwa parametru Wymagany Wymagany dla SIG Opis
pay-button tak nie Selektor CSS dla przycisku płatności.
merchant-pos-id tak tak Identyfikator POSa użytego do płatności.
shop-name tak tak Nazwa sklepu, która pojawi się na widgecie.
total-amount tak tak Kwota płatności, która pojawi się na widgecie.
currency-code tak tak Waluta płatności. Musi być zgodna z walutą POSa.
customer-language tak tak Język w którym zostanie wyświetlony widget. Dostępne wartości to: pl, en, cs oraz de, es, fr, it, pt.
customer-email nie tak Email posiadacza karty.
widget-type nie nie Domyślnie widget pokazuje formularz do podania pełnych danych karty. Podanie wartości 'cvv' wywoła widget służący tylko do podania danych karty. Widget 'cvv' wymaga zestawu nieco innych parametrów (zob. tabela poniżej).
store-card nie tak Wartości 'true'/'false'. Wartość 'true' oznacza wyświetlenie widgeta z opcją 'Zapisz kartę'.
recurring-payment nie tak Wartości 'true'/'false'. Podanie wartości 'true' wyświetla widget w wersji dla płatności cyklicznych (wówczas należy zadeklarować 'true' również dla parametru store-card.
payu-brand nie tak Wartości: true/false (domyślnie: "true"). Wyświetla widget bez znaku PayU (tylko dla widgeta w wersji inline).
widget-mode nie tak Wartości: pay/use (domyślnie: "pay"). Konfiguruje przyciski na widgecie. Opcja "Pay" zakłada, że płatność następuje zaraz po użyciu widgeta. Opcja "use" pozwala pobrać dane karty, bez ich natychmiastowego użycia.
success-callback nie nie Nazwa funkcji, która przechwytuje dane przekazane przez widget.
sig tak nie Wartość SIG wyliczona zgodnie z opisem powyżej.
Parametry widgeta pobierającego kod CVV2/CVC2:
Nazwa parametru Wymagany Wymagany dla SIG Opis
merchant-pos-id tak tak Identyfikator POSa użytego do płatności.
shop-name tak tak Nazwa sklepu, która pojawi się na widgecie.
total-amount tak tak Kwota płatności, która pojawi się na widgecie.
currency-code tak tak Waluta płatności. Musi być zgodna z walutą POSa.
customer-language tak tak Język w którym zostanie wyświetlony widget. Dostępne wartości to: pl, en, cs oraz de, es, fr, it, pt.
widget-type tak nie Należy użyć wartości 'cvv'
cvv-url tak tak Musi mieć wartość równą albo 'redirectUri' (zwróconą przez PayU w komunikacie OrderCreateResponse z kodem WARNING_CONTINUE_CVV) albo, w przypadku wywołania widgetu po udanym powrocie ze strony banku-wydawcy karty w procesie 3DS, wartość dodaną jako query string do parametru 'continueUrl' podanego w OrderCreateRequest.
cvv-success-callback nie nie Funkcja callback wywoływana po tym jak płatnik podał kod CVV2/CVC2 i została dokonana autoryzacja karty.
sig tak nie Wartość SIG wyliczona zgodnie z opisem powyżej.