Tokenizacja kart

Tokenizacja kart 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, 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.

Konfiguracja w PayU

Tokenizacja karty typu SINGLE (token jednorazowy, karta nie zostaje zapisana) jest dostępna bez dodatkowej konfiguracji. Jednak tokenizacja typu MULTI (token wielorazowy i zapisanie karty dla danego użytkownika) wymaga specjalnej konfiguracji po stronie PayU, dlatego przed przystąpieniem do integracji należy skontaktować się z opiekunem handlowym w PayU.

Na środowisku Sandbox punkty płatności typu REST API zostaną skonfigurowane automatycznie pod możliwość testowania tej funkcjonalności w ciągu 90 minut od utworzenia.

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.

• Tokenizacja
• Tokenizacja typu MULTI (one-click)

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

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

Secure Form jest preferowanym rozwiązaniem do tokenizacji karty. Wszystkie dane karty są wprowadzane poprzez iframe w formularzu PayU, co eliminuje potrzebę obsłużenia wrażliwych danych na Twojej stronie.

Pamiętaj, że wykorzystując Secure Form należy wyświetlić również niezbędne Przypisy prawne.

Jeżeli w swoim projekcie używasz Typescript po prostu dodaj definicję typów w swoim projekcie.

npm install --save @types/payu-emea-sdk

Wczytanie JS SDK

Dodaj skrypt JS SDK na każdej stronie, na której chcesz używać Secure Form. Musi być on zawsze ładowany bezpośrednio z serwerów PayU. Nie może być ładowany z własnych serwerów oraz załączany do budowanej paczki.

<script type="text/javascript" src="https://secure.payu.com/javascript/sdk"></script>

<script type="text/javascript" src="https://secure.snd.payu.com/javascript/sdk"></script>

Utworzenie instancji JS SDK

var payu = PayU('393823');

Metody instancji JS SDK

var secureForms = payu.secureForms();

{
    "status": "SUCCESS",
    "body": {
        "token": "TOK_1JOQVU5KJNOV4c4O8UbZySwcfBdS",
        "mask": "444433******1111"
    }
}

var secureForms = payu.secureForms();

{
    "status": "SUCCESS"
}

payu.sendCvv('7b09781ee6a3303cc86712fce16fe030');

var refReqId = payu.extractRefReqId('https://secure.payu.com/cpm/threeds/proxy?refReqId=7b09781ee6a3303cc86712fce16fe030"');

Metody instancji SecureForms

var cardNumberForm = secureForms.add('number');

Metody instancji SecureForm

cardNumberForm.render('#cardNumberForm');

cardNumberForm.update({lang: 'en'});

cardNumberForm
    .on('ready', function() {
        // formularz gotowy
    })
    .on('focus', function() {
        // formularz aktywowany
    })
    .on('blur', function() {
        // formularz dezaktywowany
    })
    .on('change', function(body) {
        // zmieniała się zawartość
    });

cardForm.clear();

cardForm.focus();

cardForm.remove();

Wszystkie parametry są sprawdzane pod kątem odpowiedniego typu oraz czy zawieraja poprawne wartości. W przypadku nieznanego lub nieporawnego parametru jest on ignorowany bez informacji o błędzie.

Tablica fonts

Zawiera listę obiektów definiującą dodatkowe czcionki, które zostaną dodane do każdego formularza przy użyciu @font-face.

Atrybuty family i src są wymagane.

{
    fonts: [
        {
            family: 'Own Font',
            src: 'url(https://ownulr.com/own_font_normal.woff2) format("woff2"), url(https://ownulr.com/own_font_normal.woff) format("woff2)',
            style: 'normal',
            weight: 400
        },
        {
            family: 'Own Font',
            src: 'url(https://ownulr.com/own_font_bold.woff2) format("woff2")',
            style: 'normal',
            weight: 'bold'
        }
    ]
}

Wszystkie parametry są sprawdzane pod kątem odpowiedniego typu oraz czy zawieraja poprawne wartości. W przypadku nieznanego lub nieporawnego parametru jest on ignorowany bez informacji o błędzie.

{
    style: {
        basic: {
            fontColor: '#0000FF'
            fontSize: '26px'
            fontWeight: '700'
        },
        invalid: {
            fontColor: '#990000'
        },
        placeholder: {
            fontColor: '#aaaaaa'
        }
    },
    placeholder: {
        number: '',
        date: 'MM / YY',
        cvv: ''
    },
    cardIcon: true,
    lang: 'en',
    disabled: false
}

Obiekt style

Grupuje w obiektach style dla różnych zachowań formularza. Każda grupa ma swoje dozwolone style.

Style

Obiekt placeholder

Formularze emitują zdarzenia do których można dołączyć własną funkcję zwrotną za pomocą metody on.

Zdarzenie ready

Zdarzenie to jest emitowane po wywołaniu metody render gdy formularz zostanie wyświetlony.

Zdarzenie focus

Zdarzenie to jest emitowane formularz zostanie aktywowany.

Zdarzenie blur

Zdarzenie to jest emitowane formularz zostanie dezaktywowany.

Zdarzenie change

Zdarzenie to jest emitowane gdy zawartość formularza ulegnie zmianie.
Funkcja zwrotna wywoływana jest z jednym parametrem będącym obiektem o następującej strukturze:

Do elementu, w którym wyświetlany jest formularz dodawane są dynamicznie klasy:

W obiekcie error znajduje się tablica messages zawierająca obiekty, w których znajdują się informacje o poszczególnych błędach.

Obiekt błędu w tablicy messages

Lista błędów

{
    "status": "ERROR",
    "correlationId": "",
    "error": {
        "messages": [
            {
                "type": "validation",
                "code": "error.validation.expDate.value",
                "parameters": {},
                "message": "Card expiration date is invalid"
            },
            {
                "type": "validation",
                "code": "error.validation.cvv.empty",
                "parameters": {},
                "message": "Empty CVV"
            }
        ]
    }
}

Potrzebuję tłumaczenia na język xx.

W przypadku elementów zastępczych przekazujemy je w parametrze placeholder w opcjach formularza np.

{
    placeholder: {
        number: 'Kartennummer',
        date: 'MM / JJ',
        cvv: 'CVV'
    }
}

W przypadku błędów na podstawie kodów błędów wyświetlamy swój komunikat np.

var errors = {
    messages: [
        {
            type: "validation",
            code: "error.validation.card.number",
            parameters: {},
            message: "Nieprawidłowy numer karty"
        }
    ]
};

var translations = {
    "error.validation.card.number": "Ungültige Kartennummer"
};

var showError = function() {
    errors.messages.forEach(function(message) {
        console.log(translations[message.code]); // pokazanie komunikatu błędu
    });
};

Ktoś pomniejszył okno przeglądarki lub obrócił telefon i chcę zmienić rozmiar czcionki oraz wyłączyć ikonę marki karty żeby formularz zmieścił się w całości na stronie.

Należy przy zmianie wielkości okna przeglądarki użyć metody update do aktualizacji opcji formularza np.

// kod inicjujący JS SDK i SecureForms został pominięty
var cardNumber = secureForms.add('number');
var options = {
    current: 'gt500',
    profiles: {
        gt500: {
            style: {
                basic: {
                    fontSize: '18px'
                }
            },
            cardIcon: true
        },
        lt500: {
            style: {
                basic: {
                    fontSize: '14px'
                }
            },
            cardIcon: false
        }
    }
};

// zmiana wielkości okna
window.addEventListener('resize', function() {
    var newProfile = window.innerWidth > 500 ? 'gt500' : 'lt500';
    if (newProfile !== options.current) {
        options.current = newProfile;
        // aktualizacja opcji formularza
        cardNumber.update(options.profiles[options.current]);
    }
});

Implementacja widgetu

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:

W przypadku włączenia płatności kartowych jesteś zobowiązany do przestrzegania norm PCI DSS.

Powinieneś co roku wypełnić Self-Assessment Questionnaire (SAQ), a także wykonywać kwartalny skan sieci przeprowadzany przez jednostkę weryfikującą - Approved Scan Vendor (ASV).

Dodatkowo, jeżeli przetwarzasz ponad 6 milionów transakcji rocznie powinieneś wykonać Report on Compliance (ROC), przeprowadzany przez certyfikowanego audytora - Qualified Security Assessor (QSA).

Więcej informacji możesz znaleźć na stronieSecurity Standards Council.

                    <script src="https://secure.payu.com/res/v2/openpayu-2.1.js"></script>
                    <script src="https://secure.payu.com/res/v2/plugin-token-2.1.js"></script>                

Utwórz formularz pobrania danych karty w sposób, który umożliwi poprawne działanie skryptu. W tym celu umieść elementy typu "input" na swojej stronie, których atrybuty "class" są nazwane tak jak w przykładzie poniżej.

Uwaga: nie jest konieczne umieszczenie elementów "input" w elemencie "form" ponieważ dane karty nie powinny zostać wysłane na Twój serwer.

W przypadku kiedy chcesz wysłać dane karty i spełniać wszystkie wymogi określone przez PCI DSS, zob. rozdz. Dane kartowe w postaci tekstowej.

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

Skrypty wyszukują następujące nazwy klas:

            
         {
           	data: {
           		mask: "444433******1111",
           		token: "TOK_1JKQSX1FMNTU831B8a6z4LDHbzsv",
           		type: "STANDARD"
           	},
           	status: {
           		statusCode: "SUCCESS",
           		codeLiteral: "SUCCESS",
           		code: "0"
           	}
         }        

            {
                card.expirationDate: "formatInvalid",
                card.expirationMonth: "formatInvalid",
                card.expirationYear: "formatInvalid",
                card.number: "unsupportedType"
             }           

Kody odpowiedzi na żądanie tokenizacji:

Twoja strona powinna również obsłużyć pobranie brakującego kodu CVV2.

<input type="text" class="payu-card-cvv">

Potrzeba pobrania wyłącznie kodu CVV2 może wystąpić w przypadku konieczności uwierzytelnienia płatności tokenem kartowym.

Wystąpić mogą 2 przypadki:

1. Obciążenie z pełnym uwierzytelnieniem. Kod CVV2 musi zostać pobrany kiedy płatnik powraca na Twoją stronę po uwierzytelnieniu poprzez 3DS - kod WARNING_CONTINUE_CVV jest podany w zapytaniu (query string) dodanym do adresu strony podanej jako continueUrl w OrderCreateRequest. Przykład zapytania:

                           https://your.shop.com/payment?statusCode=WARNING_CONTINUE_CVV&refReqId=b20399775cbf48a00469280499bdd912
                       

   Przykład skryptu (kod poniżej powinien zostać wywołany kiedy płatnik użyje przycisku do wysłania CVV2):

                               var url = "refReqId=" + 'wartość refReqId podana w zapytaniu (query string)';
                               var options = {url: url};
                               OpenPayU.authorizeCVV(options, function(data) {
                                   if (data.status === 'SUCCESS') {
                                       // CVV2 przesłany poprawnie, można ukryć pole input
                                   } else {
                                       // wystąpił błąd (zob. tabelę powyżej)
                                   }
                               }); 
                           

2. Obciążenie z częściowym uwierzytelnieniemn (tylko CVV2). Status WARNING_CONTINUE_CVV jest podany w odpowiedzi do OrderCreateRequest. Przykład takiej odpowiedzi znajduje się w rozdz.Płatność tokenem . Przykład skryptu (kod poniżej powinien zostać wywołany kiedy płatnik użyje przycisku do wysłania CVV2):

                          var options = {url: 'wartość redirectUri z OrderCreateResponse'};
                          OpenPayU.authorizeCVV(options, function(data) {
                               if (data.status === 'SUCCESS') {
                                       // CVV2 przesłany poprawnie, można ukryć pole input
                                   } else {
                                       // wystąpił błąd (zob. tabelę powyżej)
                                   }
                          });     
                       

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

Wartość "device fingerprint" jest tworzona przez statyczną funkcję Fingerprint2.get, która zastąpiła skrypt new Fingerprint2().get, przez to wynik nie będzie już automatycznie hash'owany.

Potrzebne biblioteki można znaleźć Tutaj.

            var options = {}
            Fingerprint2.get(options, function (components) {
              // components is array of {key: 'foo', value: 'component value'}
              ...
            })
            
            // or
            
            Fingerprint2.getPromise(options).then(function (components) {
              // components is array of {key: 'foo', value: 'component value'}
              ...
            })
          

            Fingerprint2.get(options, function (components) {
              var values = components.map(function (component) { return component.value })
              var murmur = Fingerprint2.x64hash128(values.join(''), 31)
            })
          

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

Modyfikacja back-end

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

Komunikat OrderCreateRequest należy rozszerzyć o sekcję Buyer oraz sekcję payMethods podając jako wartość token jednorazowy (TOK_). Tworzenie zamówienia (Order) poprzez REST API jest opisane w rozdziale Tworzenie zamówienia.

Przykład zamówienia wykorzystującego token jednorazowy (TOK_):

                    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",
                          "cardOnFile": "FIRST",
                          "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 w rozdziale Uwierzytelnienie.

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

Przykład odpowiedzi do komunikatu OrderCreateResponse z kodem SUCCESS:

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

Oznacza to, że zamówienie zostało przyjęte bez potrzeby dodatkowego uwierzytelnienia płacącego (3D Secure lub podanie kodu CVV2) i możesz oczekiwać na status zamówienia na adres podany w parametrze notifyUrl w komunikacie OrderCreateRequest.

Przykład zamówienia zainicjowanego przez merchanta i wykorzystującego token wielorazowy (TOKC_):

                    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",
                        "cardOnFile": "STANDARD_MERCHANT",
                        "extOrderId":"9xl0x8nr1wk7m0i3ltqbja",
                        "products":[
                            {
                               "name":     "Laptop",
                               "unitPrice":"15000",
                               "quantity": "1"
                            }
                        ],
                        "buyer": {
                            "email": "john.doe@example.com",
                            "firstName": "John",
                            "lastName": "Doe",
                            "language": "en"
                        },
                        "payMethods": {
                            "payMethod": {
                                "value": "TOKC_2IHRST6HKSST3H62K2GS8pElI862",
                                "type":  "CARD_TOKEN"
                            }
                        },
                        "deviceFingerprint": "0372098a4a90927db053463454491d78"
                    }'
                

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

Uwierzytelnienie 3DS może zostać przeprowadzone poprzez protokół 3DS1 lub protokół 3DS2. Protokół określa się poprzez ustawienie wartości pola threeDsProtocolVersion.

Aby dowiedzieć się jak podejść do 3DS 2, przejdź na stronę 3DS 2.

Przykład odpowiedzi WARNING_CONTINUE_3DS:

                    {
                        "orderId": "ORDER_ID",
                        "status": {
                            "statusCode": "WARNING_CONTINUE_3DS",
                            "severity": "WARNING"
                        },
                        "redirectUri": "{redirectUri}",
                        "iframeAllowed": true,
                        "threeDsProtocolVersion": "3DS1"
                    }
                

https://your.shop.com/payment?statusCode=SUCCESS&refReqId=5c867936fbb3cc2c373820b4550b4645

W przypadku gdy parametr statusCode przyjął wartość SUCCESS, to oznacza, że zamówienie zostało przyjęte bez potrzeby kolejnego uwierzytelnienia płacącego i możesz oczekiwać na status zamówienia.

Natomiast gdy parametr statusCode przyjął wartość WARNING_CONTINUE_CVV, to wówczas powinieneś wyciągnąć wartość parametru refReqId wraz z nazwą parametru, przykładowo:

refReqId=5c867936fbb3cc2c373820b4550b4645

                    {
                        "orderId": "ORDER_ID",
                        "status": {
                            "statusCode": "WARNING_CONTINUE_CVV",
                            "severity": "WARNING"
                        },
                        "redirectUri": "{redirectUri}"
                    }
                

Przykładowa wartość parametru redirectUri:

https://secure.payu.com/api/v2/token/token.json?refReqId=11ed628ebe88ef6837d90ebb26f1a8b9

Po podaniu przez płacącego kodu CVV2/CVC2 możesz oczekiwać na status zamówienia.

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 aktywnym 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.

Przykładowe żądanie:

                    
                    curl -X POST https://secure.payu.com/pl/standard/user/oauth/authorize \
                       -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]' 
                       
                

ext_customer_id jest identyfikatorem klienta w systemie merchanta, jest on konieczny w celu poprawnego wygenerowania tokena OAuth.

{
    "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 .

curl -X GET https://secure.payu.com/api/v2_1/paymethods \
   -H "Authorization: Bearer 87ad751f-7ea5-4023-a16f-04b6647a07f5" 
   -H "Cache-Control: no-cache" 

                

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",
         "minAmount": 50,
         "maxAmount": 100000
      },
      {  
         "value":"o",
         "name":"Pekao24Przelew",
         "brandImageUrl":"http://static.payu.com/images/mobile/logos/pbl_o.png",
         "status":"DISABLED",
         "minAmount": 50,
         "maxAmount": 100000
      },
      {  
         "value":"ab",
         "name":"Płacę z Alior Bankiem",
         "brandImageUrl":"http://static.payu.com/images/mobile/logos/pbl_ab.png",
         "status":"TEMPORARY_DISABLED",
         "minAmount": 50,
         "maxAmount": 100000
      }
   ]
}          
            

cardTokens

pexTokens

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

payByLinks

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.

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

Uwaga! Ten sposób integracji jest przeznaczony tylko dla punktów płatności, które spełniają wymogi określone przez PCI DSS i są uprawnione do przetwarzania danych kartowych po swojej stronie. Wymagają również dodatkowej konfiguracji.. Dlatego przed przystąpieniem do integracji należy skontaktować się z opiekunem handlowym w PayU.

Do standardowego zamówienia OrderCreateRequest należy dodać sekcję payMethods.payMethod zawierającą dane kartowe i parametr cardOnFile z jedną z poniższych wartości:

Odpowiednie ustawienie tego parametru pozwoli zwiększyć konwersję dla kart płatniczych i zagwarantować odpowiednie bezpieczeństwo transakcji.

Jeżeli jest to płatność jednorazowa kartą, wówczas parametr cardOnFile należy pominąć.

Przykład sekcji payMethods.payMethod uzupełnionej o dane kartowe w postaci tekstowej:

                    "payMethods": {
                        "payMethod": {
                            "card": {
                                "number":"5100052384536818",
                                "expirationMonth":"11",
                                "expirationYear":"2020",
                                "cvv":"123"
                            }
                        }
                    },

                

Przykład sekcji payMethods.payMethod uzupełnionej o dane kartowe w postaci tekstowej oraz identyfikator pierwszej transakcji cyklicznej lub Card-on-File:

                
                "payMethods": {
                    "payMethod": {
                        "card": {
                            "number":"5100052384536818",
                            "expirationMonth":"11",
                            "expirationYear":"2020",
                            "cvv":"123",
                            "firstTransactionId": "MCC0111LL1121"
                        }
                    }
                },
                
            

Również dla płatności z podaniem danych kartowych w postaci tekstowej należy być przygotowanym na obsługę odpowiedzi z kodem WARNING_CONTINUE_3DS lub WARNING_CONTINUE_CVV.

W przypadku gdy jesteś zintegrowany z własnym dostawcą usługi 3D Secure (zwany dalej w skrócie 3DS) masz możliwość przekazania parametrów będących wynikiem procesu obsługi 3DS w komunikacie OrderCreateRequest. Standardowy komunikat OrderCreateRequest należy rozszerzyć o sekcję payMethods.threeDsData zawierającą dane wynikowe procesu 3DS.

Jeżeli wynik obsługi 3DS zostanie dostarczony wraz z zamówieniem, to kod odpowiedzi WARNING_CONTINUE_3DS nigdy nie zostanie zwrócony.

Przykład uzupełnionej sekcji threeDsData dla uwierzytelnienia 3DS zakończonego sukcesem

                    
                    "payMethods": {
                        "payMethod": {
                            ...
                            },
                            "threeDsData": {
                                "status3Ds": "AY",
                                "status3DsDescription": "3ds successfull",
                                "xid": "PL345346456",
                                "eciCode": 5,
                                "cavv": "AAABBBEAUAAAABgICABQAAAAAAA="
                            }
                        }
                    }
                    
                

Przykład uzupełnionej sekcji threeDsData dla uwierzytelnienia 3DS2.x zakończonego sukcesem

                
                "payMethods": {
                    "payMethod": {
                        ...
                        },
                        "threeDsData": {
                            "status3Ds": "Y",
                            "status3DsDescription": "3ds2.x successfull",
                            "dsTransactionId": "3b31b19d-1c06-4ea4-a85a-00af10c66588",
                            "eciCode": 5,
                            "cavv": "AAABBBEAUAAAABgICABQAAAAAAA="
                        }
                    }
                }
                
            

Przykład uzupełnionej sekcji threeDsData dla karty, której wydawca nie wspiera 3DS

                    
                    "payMethods": {
                        "payMethod": {
                            ...
                            },
                            "threeDsData": {
                                "status3Ds": "VN",
                                "status3DsDescription": "Card is not participating in 3DS",
                                "xid": "PL345346456"
                            }
                        }
                    }
                    
                

Przykład uzupełnionej sekcji threeDsData dla próby uwierzytelnienia 3DS

                    
                    "payMethods": {
                        "payMethod": {
                            ...
                            },
                            "threeDsData": {
                                "status3Ds": "AA",
                                "status3DsDescription": "3DS authentication attempt",
                                "xid": "PL345346456",
                                "eciCode": 6,
                                "cavv": "BwABCJQnYgAAACdENCdiAAAAAAA="
                            }
                        }
                    }
                    
                

Parametry użyte w sekcji threeDsData

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 Secure Form 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.

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.

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.

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.