PayU | Express

1 O produkcie

PayU ǀ Express to rodzina usług umożliwiających realizację płatności jednym kliknięciem – przelewem lub kartą, bez każdorazowego logowania do banku i przepisywania haseł SMS, czy podawania danych karty.

Dzięki PayU ǀ Express Twój Klient oszczędza czas, wygodnie oraz przede wszystkim bezpiecznie dokonuje płatności, a Ty zyskujesz lojalnych konsumentów, dzięki dostarczeniu im nowoczesnej i intuicyjnej metody płatności.

Transparentna integracja

PayU|Express 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.

Tokeny zwrócone przez PayU mogą być jednorazowe lub wielorazowe. Tokeny wielorazowe mogą posłużyć do przyszłych płatności. Funkcjonalność ta skierowana jest do sklepów mających dużą ilość powracających klientów – połączenie konta użytkownika w sklepie z tokenem wielorazowym umożliwia dokonywania płatności bez każdorazowego podawania danych karty. Zwykle płatności zapisaną kartą mogą być wykonane ekspresowo, jednym kliknięciem przycisku "Płacę", jednak ze względów bezpieczeństwa niektóre transakcje mogą wymagać uwierzytelnienia przez przekierowanie na stronę banku-wydawcy karty (3D Secure) lub podanie kodu CVV2/CVC2. W związku z tym, płatności usługą PayU|Express powinny być inicjowane przez płatnika i z jego udziałem, a nie wyłącznie przez sklep, tak jak w przypadku płatności cyklicznych.

Konfiguracja w PayU

PayU|Express 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

Usługa PayU | Express jest oparta 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):

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

3 Pobranie danych karty

Istnieją dwie możliwości pobrania danych karty: poprzez widget PayU (wariant preferowany) lub poprzez formularz na stronie sklepu z dołączonym skryptem JS, który przesyła dane z formularza do PayU. Widget ma dwie wersje: pop-up (widget pojawia się nad stroną sklepu) i inline (widget jest wlewany w stronę sklepu).

Dane przekazywane przez widget wyglądają następująco:

   value:"TOK_1IOPVS7EMKVT4GYvs44XPxAOb8yc",
   maskedCard:"424242******4242",
   tokenType:"STANDARD",
   type:"CARD_TOKEN"
            
Nazwa parametru Opis
value token jednorazowy ("TOK_") - wygasa po pierwszym użyciu
maskedCard maskowany numer karty
tokenType stała wartość (zawsze STANDARD)
type stała wartość (zawsze CARD_TOKEN)

3.1 Widget pop-up

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"
                        customer-email="email@exampledomain.com"
                        sig="250f5f53e465777b6fefb04f171a21b598ccceb2899fc9f229604ad529c69532"
                    </script>
                
3. Aby wyliczyć SIG, należy użyć następującego algorytmu: Parametry widgeta.
W niektórych przypadkach, PayU może poprosić o kod CVV2/CVC2. W tym przypadku należy wywołać specjalny widget:
                    <script
                        src="https://secure.payu.com/front/widget/js/payu-bootstrap.js"
                        merchant-pos-id="145227"
                        shop-name="Shop name"
                        total-amount="9.99"
                        currency-code="PLN"
                        customer-language="pl"
                        widget-type="cvv"
                        cvv-url="refReqId=c4b31c492b0a5aaa9eb12d07578286a0"
                        vv-success-callback="cvvSuccess"
                        sig="e08f617240bac43954bcbb5782a0ce203a23717ba9760be71c9ea8cab127ad12">
                    </script>
                    <script type="text/javascript">
                        function cvvSuccess() {
                        //wyświetla stronę o udanym zainicjowaniu płatności
                        }
                    </script>
                

3.2 Widget inline

Widget inline to modyfikacja widgeta pop-up. Nie zawiera on nagłówka z nazwą sklepu i kwoty zakupu oraz wykorzystuje dodatkowe parametry.
1. Widget inline jest wlewany w stronę, jeśli zawiera ona następujący element:
<div id="payu-widget"></div>
2. Wlany widget może przekazać dane poprzez metodę HTTP POST lub przekazać je poprzez funkcję callback. Aby jej użyć, należy w skrypcie podać parametr success-callback. Funkcja callback może wyglądać jak poniżej (poniższy przykład pozwala wyświetlić dane w konsoli w przeglądarce):
<script>
      function test($data) {
           console.log("callback");
           console.log($data);
      }
</script>
        
3. Aby wyświetlić wlany widget, należy dołączyć do strony skrypt, podając parametry zgodnie ze swoimi preferencjami. Poniższy przykład wyświetli widget z białym tłem, bez znaku PayU, w trybie "Użyj" (zamiast "Płać"). Aby sprawdzić jego działae, wystarczy skopiować i wkleić poniższy skrypt do swojej strony, razem z podanym wyżej elementem div i funkcją callback.
                    <script
                        src="https://secure.payu.com/front/widget/js/payu-bootstrap.js"
                        merchant-pos-id="145227"
                        shop-name="TEST"
                        total-amount="12345"
                        currency-code="PLN"
                        customer-language="en"
                        store-card="true"
                        payu-brand="false"
                        success-callback="test"
                        widget-mode="use"
                        customer-email="test@test.com"
                        sig="203ec8c4b9571ce6b4c03058f57264f04d06d00a86da19390d47ba1be4551578"
                    </script>
                
4. Aby wyliczyć SIG, należy użyć następującego algorytmu: Parametry widgeta.

3.3 Parametry widgeta

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

  1. Posortować alfabetycznie parametry wg nazw potrzebne do wyliczenia SIGa (zob. tab. niżej, np. parametr customer-email powinien być przed parametrem customer-language itd.).
  2. Połączyć (tj. "skonkatenować") wartości parametrów wg kolejności sortowania.
  3. Do tak powstałego ciągu znaków należy 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.

Przykład wyliczenia wartości sig:

Parametry widgeta, które mają zostać użyte należy posortować wg nazwy (klucza) parametru:

  1. currency-code: PLN
  2. customer-email: test@test.com
  3. customer-language: pl
  4. merchant-pos-id: 145227
  5. shop-name: TEST
  6. total-amount: 12345

Następnie należy połączyć wartości parametrów i uzyskać ciąg znaków jak poniżej:

PLNtest@test.compl145227TEST12345

i dodać do niego wartość klucza drugiego (w przykładzie użyty został testowy POS produkcyjny). Uzyskany ciąg znaków, na którym na którym należy użyć funkcji skrótu SHA256 to:

PLNtest@test.compl145227TEST1234513a980d4f851f3d9a1cfc792fb1f5e50

A uzyskana wartość sig, po zastosowaniu funkcji skrótu, to:

cf16a6302c26e6f39b580be859caf1fe396e81366c4d8f56fb765fb374e8ed3a

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.

3.4 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') {
                             //clean and hide card details
                          }else{
                             // WARNING_CONTINUE_CVV lub WARNING_CONTINUE_3DS, zob. niżej,
                             // lub obsługa błędu
                         }
                    };
                

Wizualizacja statusów:

"Device fingerprint"

Device fingerprint to informacja zebrana o urządzeniu w celu jego identyfikacji.

Wartość "device fingerprint" jest tworzone przez skrypt fingerprint2.js, który musi zostać dołączony do strony.

Użycie:
new Fingerprint2({
    excludeJsFonts: true,
    excludeAdBlock: true,
    excludeFlashFonts: true,
    excludeWebGL: true
}).get(function (result) {  //tu wstaw funkcję callback
});                
Hash wygenerowany dla tej przeglądarki: [generateFingerPrint2]

Uzyskaną wartość należy przesłać do PayU poprzez back-end (zob. niżej).

4 Płatność tokenem

Modyfikacja back-end

Token wielorazowy (TOKC_) tworzony jest po pierwszym użyciu tokenu jednorazowego (TOK_).

Token jednorazowy należy wstawić jako wartość metody płatności do komunikatu OrderCreateRequest. Tworzenie zamówienia (Order) poprzez REST API jest opisane tutaj. Komunikat należy OrderCreateRequest należy rozszerzyć o sekcję Buyer oraz sekcję payMethods podając jako wartość token jednorazowy (TOK_).

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.

W przypadku odpowiedzi z kodem WARNING_CONTINUE_CVV, należy poprosić płatnika o podanie kodu CVV2/CVC2 poprzez wywołanie widgeta ze stosownym parametrem lub formularza.

Przykład zamówienia w usłudze PayU|Express:

                    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",
                          "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": "pl"
                          },
                          "payMethods": {
                              "payMethod": {
                                   "value": "TOK_1IHRPT6HKSSS3H62K0GS8pElP862",
                                   "type":  "CARD_TOKEN"
                              }
                          },
                          "deviceFingerprint": "[generateFingerPrint2]"
                      }'
                

Uwierzytelnienie komunikatu jest opisane tutaj.

Uwaga: POS użyty w przykładzie ne ma włączonej usługi tokenizacji.

Odpowiedzi do komunikatu OrderCreateResponse:

Przykład odpowiedzi z kodem SUCCESS, zwracającej 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:
{
     "orderId": "ORDER_ID",
     "status": {
         "statusCode": "WARNING_CONTINUE_3DS",
         "severity": "WARNING"
     },
     "redirectUri": "{redirectUri}"
}
                
Przykład odpowiedzi z kodem WARNING_CONTINUE_CVV:
{
     "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.

5 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).

6 Usuwanie tokenów

Usuwanie tokena płatniczego

W przypadku kiedy użytkownik zamyka swoje konto w sklepie internetowym lub chce usunąć zapisaną kartę, token należy skasować.

W tym celu należy wysłać żądanie z metodą DELETE na endpoint https://secure.payu.com/api/v2_1/tokens/{tokenValue}

Nagłówek powinien zawierać token dostępowy OAuth typu trusted.merchant.

Przykład:
curl 
-X DELETE 
-H "Authorization: Bearer cccbbc40-8113-443b-b4ea-c4b266272b22" 
-H "Cache-Control: no-cache" 
"https://secure.payu.com/api/v2_1/tokens/TOKC_XATB7DF8ACXYTVQIPLWTVPFRKQE"

7 Card on file

Card on file (Czyste dane kartowe):

Tworzenie zamówienia (Order) poprzez REST API jest opisane tutaj. Standardowy komunikat OrderCreateRequest należy rozszerzyć o sekcję payMethods oraz parametr "cardOnFile".

Uwaga: w pierwszej transakcji (Order) należy ustawić parametr "cardOnFile" jako "FIRST". Kolejne Ordery powinny mieć parametr "cardOnFile" ustawiony jako "STANDARD_CARDHOLDER" lub "STANDARD_MERCHANT".

"STANDARD_CARDHOLDER" oznacza transakcję inicjowaną przez właściciela karty, "STANDARD_MERCHANT" oznacza transakcję inicjowaną przez merchanta. Przynajmniej jedna transakcja "FIRST" dla trójki: POS, karta, extUserID, musi zakończyć się pozytywną autoryzacją, aby kolejne płatności ("STANDARD_CARDHOLDER" lub "STANDARD_MERCHANT") nie wymagały podawania CVV/3DS.

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. Szczegóły zawarto w: Płatność tokenem.

Przykład zamówienia z flagą cardOnFile:

                    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",
                         "cardOnFile": "FIRST", 
                         "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",
                            "extCustomerId": "1001"
                         },                          
                         "payMethods": {
                            "payMethod": {
                               "card": {
                                  "number":"5100052384536818",
                                  "expirationMonth":"11",
                                  "expirationYear":"2020",
                                  "cvv":"123"
                               }
                            }
                         },
                         "deviceFingerprint": "[generateFingerPrint2]"
                    }'
                

Uwierzytelnienie komunikatu jest opisane tutaj.

Uwaga: POS użyty w przykładzie nie ma włączonej usługi tokenizacji.

8 Scenariusze płatności

Poniżej znajduje się omówienie scenariuszy płatności, które należy zaimplementować.

8.1 Pierwsze obciążenie

  1. Pobierz token dostępowy OAuth. Endpoint: /pl/standard/user/oauth/authorize. Metoda: POST
  2. Pobierz dostępne metody płatności. Endpoint: /api/v2_1/paymethods. Metoda: GET
  3. Pobierz dane karty (numer /PAN/, data ważności, kod CVV2/CVC2) przez widget lub formularz. Tokenizuj kartę.
  4. Utwórz OrderCreateRequest, uzupełnij o jednorazowy token kartowy i wyślij żądanie. Endpoint: /api/v2_1/orders. Metoda POST.
  5. Obsłuż status WARNING_CONTINUE_3DS zwrócony przez OrderCreateResponse poprzez przekierowanie na adres podany w parametrze redirectUri.
  6. Opcjonalnie, tylko jeśli uwierzytelnienie 3DS trwało zbyt długo i kodu CVV2/CVC2 nie ma w cache po stronie PayU: obsłuż status WARNING_CONTINUE_CVV dodany do adresu continueUrl.
  7. Odbierz notyfikację o statusie zamówienia przesłaną na adres podany parametrem notifyUrl.
  8. Opcjonalnie, tylko jeśli auto-odbiór dla danej metody płatności jest wyłączony: odbierz zamówienie. Endpoint: /api/v2_1/orders/{orderId}/status. Metoda: PUT.

8.2 Kolejne obciążenie bez uwierzytelnienia

  1. Pobierz token dostępowy OAuth. Endpoint: /pl/standard/user/oauth/authorize. Metoda: POST
  2. Pobierz dostępne metody płatności. Endpoint: /api/v2_1/paymethods. Metoda: GET
  3. Utwórz OrderCreateRequest, uzupełnij o wielorazowy token kartowy i wyślij żądanie. Endpoint: /api/v2_1/orders. Metoda POST.
  4. Odbierz notyfikację o statusie zamówienia przesłaną na adres podany parametrem notifyUrl.
  5. Opcjonalnie, tylko jeśli auto-odbiór dla danej metody płatności jest wyłączony: odbierz zamówienie. Endpoint: /api/v2_1/orders/{orderId}/status. Metoda: PUT.

8.3 Kolejne obciążenie z pełnym uwierzytelnieniem

  1. Pobierz token dostępowy OAuth. Endpoint: /pl/standard/user/oauth/authorize. Metoda: POST
  2. Pobierz dostępne metody płatności. Endpoint: /api/v2_1/paymethods. Metoda: GET
  3. Utwórz OrderCreateRequest, uzupełnij o wielorazowy token kartowy i wyślij żądanie. Endpoint: /api/v2_1/orders. Metoda POST.
  4. Obsłuż status WARNING_CONTINUE_3DS zwrócony przez OrderCreateResponse poprzez przekierowanie na adres podany w parametrze redirectUri.
  5. Obsłuż status WARNING_CONTINUE_CVV dodany do continueUrl.
  6. Odbierz notyfikację o statusie zamówienia przesłaną na adres podany parametrem notifyUrl.
  7. Opcjonalnie, tylko jeśli auto-odbiór dla danej metody płatności jest wyłączony: odbierz zamówienie. Endpoint: /api/v2_1/orders/{orderId}/status. Metoda: PUT.

8.4 Kolejne obciążenie z częściowym uwierzytelnieniem

  1. Pobierz token dostępowy OAuth. Endpoint: /pl/standard/user/oauth/authorize. Metoda: POST
  2. Pobierz dostępne metody płatności. Endpoint: /api/v2_1/paymethods. Metoda: GET
  3. Utwórz OrderCreateRequest, uzupełnij o wielorazowy token kartowy i wyślij żądanie. Endpoint: /api/v2_1/orders. Metoda POST.
  4. Obsłuż status WARNING_CONTINUE_3DS lub WARNING_CONTINUE_CVV zwrócony przez OrderCreateResponse.
  5. Odbierz notyfikację o statusie zamówienia przesłaną na adres podany parametrem notifyUrl.
  6. Opcjonalnie, tylko jeśli auto-odbiór dla danej metody płatności jest wyłączony: odbierz zamówienie. Endpoint: /api/v2_1/orders/{orderId}/status. Metoda: PUT.