REST API

Informacje o aktualnej wersji

Dokument zawiera informacje o protokole REST API w wersji 2.1.

Jeżeli poszukujesz informacji o starszej wersji API skontaktuj się z nami.

Informacje podstawowe

Tutaj znajdziesz informacje jak skonfigurować sklep i POS po zalogowaniu się do konta PayU dla sprzedających.

Przed rozpoczęciem procesu integracji należy się upewnić, że punkt płatności na którym będą realizowane zamówienia jest typu REST API (Checkout) (do sprawdzenia na ekranie sklepów w Panelu Managera).

Informacje nt. testowania i dane testowych POSów (produkcja i sandbox) znajdują się w sekcji Testowanie.

Opis usługi

Dokumentacja ma na celu przedstawienie sposobu wdrożenia płatności internetowych w sklepie internetowym za pośrednictwem usług PayU. Dokumentacja podzielona jest na kilka części. Pierwsza to wprowadzenie w usługę płatności. Następna to minimalny przykład wdrożenia płatności w sklepie internetowym w tzw. trybie hosted (przekierowanie na stronę PayU). Kolejne dwie części poświęcone są na omówienie procesów powiadomienia oraz zwrotów. Kolejne części to przykłady oraz referencje.

Materiał ten jest przede wszystkim przeznaczony dla deweloperów, którzy chcą zintegrować usługę płatności PayU ze swoim sklepem internetowym.

Proces obsługi płatności w sklepie internetowym za pośrednictwem usługi PayU składa się z dwóch etapów.

1. Złożenie zamówienia przez kupującego na stronie sklepu.
2. Potwierdzenia prawidłowego rozliczenia płatności zrealizowanej przez usługę PayU.

Etap pierwszy. Złożenie zamówienia przez kupującego.

Proces jest przedstawiony na poniższym diagramie.

1. Kupujący klika w przycisk reprezentujący usługę płatności PayU.
2. System PayU prezentuje stronę z podsumowaniem zamówienia na której kupujący potwierdza płatność. System PayU przekierowuje kupującego na stronę banku.
3. Kupujący akceptuje płatność na stronie Banku. Nastepuje przekierowanie kupującego ponownie na stronę systemu PayU.
4. System Sprzedawcy prezentuje podziękowanie za transakcje.

Etap drugi (opcjonalny). Rozliczenie (odebranie) płatności.

1. System PayU powiadamia system sprzedawcy o zmianie statusu procesowanej płatności zgodnie z jej cyklem za pomocą powiadomień ("notyfikacji").
2. System sprzedawcy potwierdza odebranie powiadomienia.

Aktualny status danej płatności możesz obejrzeć w panelu menadżera.

Metody uwierzytelnienia znajdują się w: Uwierzytelnienie użytkownika API.

W celu utworzenia nowego zamówienia należy za pomocą metody POST wyśłać komunikat OrderCreateRequest na endpoint /api/v2_1/orders.

Uwaga: wszystkie kwoty należy podawać w najmniejszej jednostce dla danej waluty np. w groszach dla PLN czyli "1000" oznacza 10 zł. Wyjątkiem jest HUF, który należy pomnożyć razy 100.

Uwaga: Odpowiedź na żądanie nowego zamówienia zwraca kod HTTP 302 oraz nagłówek Location ustawiony na redirectUri. Może być to powodem automatycznych przekierowań i otrzymywaniem odpowiedzi w formacie HTML.

Przykład zamówienia z jednym produktem i podstawowymi danymi kupującego oraz extOrderId:

                 curl -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": "RTV market",
                     "currencyCode": "PLN",
                     "totalAmount": "15000",
                     "extOrderId":"[generateExtOrderId]",
                     "buyer": {
                         "email": "john.doe@example.com",
                         "phone": "654111654",
                         "firstName": "John",
                         "lastName": "Doe"
                     },
                     "products": [
                         {
                             "name": "Wireless Mouse for Laptop",
                             "unitPrice": "15000",
                             "quantity": "1"
                         }
                     ]
                 }'
            

Jeśli zewnętrzny identyfikator zamówienia (extOrderId) jest przesyłany w komunikacie, jego wartość musi być unikalna obrębie jednego POS-a.

Po wysłaniu żądania utworzenia nowego zamówienia zostanie odesłana odpowiedź. Pole redirectUri zawiera URL pod jaki należy przekierować kupującego.

Przykład odpowiedzi na żądanie utworzenia nowego zamówienia:

{  
   "status":{  
      "statusCode":"SUCCESS",
   },
   "redirectUri":"{url_do_przekierowania_na_stronę_podsumowania_płatności}",
   "orderId":"WZHF5FFDRJ140731GUEST000P01",
   "extOrderId":"{twój_identyfikator_zamówienia}",
}
         

Więcej informacji o możliwych kodach odpowiedzi znajduje się w sekcji Kody statusów.

W trakcie wykonywania przekierowania możliwe jest ustawienie języka strony PayU przez użycie opcjonalego parametru lang.

Aby ustawić język strony, na którą zostanie przeniesiony użytkownik po przekierowaniu, należy użyć parametru language w sekcji <buyer> albo przekształcić redirectUri poprzez dokonanie następującego złożenia:

{redirectUri z OrderCreateResponse}&lang=pl

Akceptowane wartości parametru lang są tutaj.

                <form method="POST" action="https://secure.payu.com/api/v2_1/orders">
                    <input type="hidden" name="customerIp" value="123.123.123.123"> 
                    <input type="hidden" name="merchantPosId" value="145227"> 
                    <input type="hidden" name="description" value="Opis zamówienia"> 
                    <input type="hidden" name="totalAmount" value="1000"> 
                    <input type="hidden" name="currencyCode" value="PLN"> 
                    <input type="hidden" name="products[0].name" value="Produkt 1"> 
                    <input type="hidden" name="products[0].unitPrice" value="1000"> 
                    <input type="hidden" name="products[0].quantity" value="1">
                    <input type="hidden" name="notifyUrl" value="http://shop.url/notify">
                    <input type="hidden" name="continueUrl" value="http://shop.url/continue">
                    <input type="hidden" name="OpenPayu-Signature" type="hidden" value="sender=145227;algorithm=SHA-256;signature=565f9f4dda43c8e24ccab4472133d680e2aa58e1f58bea845c4cf2926965144d">
                    <button type="submit" formtarget="_blank">Płacę z PayU</button>
                </form>
            

Więcej informacji na temat parametrów (np. jak zdefiniować język strony płatniczej) znajdziesz w rozdziale Parametry formularza.

Szczegóły jak wykonać podpis znajdziesz w rozdziale Podpisywanie parametrów formularza.

Pliki graficzne pomocne w ostylowaniu przycisku formularza znajdują się pod tym linkiem.

Aby uruchomić otrzymywanie powiadomień dla konkretnej płatności, należy podać parametr notifyUrl podczas tworzenia płatności. Dla każdej płatności można zdefiniować inny URL, na który będą wysyłane powiadomienia.

Wszystkie powiadomienia są wysyłane w sposób asynchroniczny. Należy ignorować wszystkie komunikaty otrzymane po wiadomości o statusie COMPLETED.

Po wysłaniu notyfikacji system PayU oczekuje na odpowiedź ze statusem HTTP 200. W przypadku każdego innego statusu nastąpi ponowne wysłanie notyfikacji. Należy uwzględnić sytuację, gdy powiadomienie zostanie wysłane kilka razy dla tego samego statusu zamówienia. Na każde powtórzone powiadomienie należy również odpowiedzieć statusem 200.

Po odbiorze notyfikacji przychodzącej z serwera PayU, należy poddać weryfikacji wartość signature znajdującą się w nagłówku OpenPayu-Signature. Sprawdzanie podpisu powiadomień ma na celu zapewnienia zaufanej komunikacji między sklepem a PayU. Więcej informacji o sprawdzaniu podpisu notyfikacji znajdziesz w dziale Weryfikacja podpisu notyfikacji.

Notyfikacje są wysyłane dla zamówień w statusach PENDING, WAITING_FOR_CONFIRMATION, COMPLETED, CANCELED.

Uwaga: jeśli Twój system filtruje ruch przychodzący, pamiętaj aby dodać wyjątki dla adresów IP z których są wysyłane powiadomienia. Są to:

PRODUKCJA

185.68.12.10, 185.68.12.11, 185.68.12.12, 185.68.12.26, 185.68.12.27, 185.68.12.28

SANDBOX

185.68.14.10, 185.68.14.11, 185.68.14.12, 185.68.14.26, 185.68.14.27, 185.68.14.28 

Cykl życia płatności.

Uwaga: dla każdej metody płatności z osobna można skonfigurować poprzez Panel Managera tzw. auto-odbiór.

Domyślnie auto-odbiór jest włączony, co oznacza, że każda pozytywnie zautoryzowana płatność jest rozliczana, tj. 1/ kupujący jest obciążany kwotą zamówienia, 2/ saldo sklepu jest zwiększane o kwotę zamówienia, 3/ PayU nalicza prowizję do zamówienia.

Przy wyłączonym auto-odbiorze, należy dla każdego zamówienia indywidualnie użyć metody PUT w celu jego odbioru (Odebranie zamówienia) lub metody DELETE w celu jego anulowania (Anulowanie).

Niewykonanie żadnej z tych akcji skutkuje autoanulowaniem zamówienia. Autoanulowanie następuje po czasie wskazanym dla danej metody płatności.

Powiadomienia są wysyłane natychmiast po zmianie statusu płatności, w przypadku gdy powiadomienie nie zostanie odebrane przez aplikację Sklepu zostanie ono wysłane ponownie zgodnie z poniższą tabelką:

Przykład powiadomienia wysyłanego przez PayU do sklepu dla zakończonego zamówienia:

• Powiadomienia wysyłane są w formacie JSON za pomocą metody POST.
• Więcej informacji na temat parametrów komunikatu znajdziesz w rozdziale Parametry komunikatów JSON.

Nagłówki HTTP dodawane przez PayU (HTTP Headers):

              PayU-Processing-Time: 1000                                     // dla wybranych statusów
              Content-Type: application/json;charset=UTF-8
              User-Agent: Jakarta Commons-HttpClient/3.1
              Content-Length: 100
              Authorization: Basic MTIzNDU2Nzg6QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVo=
              OpenPayu-Signature: sender=checkout;signature=d47d8a771d558c29285887febddd9327;algorithm=MD5;content=DOCUMENT
              X-OpenPayU-Signature: sender=checkout;signature=d47d8a771d558c29285887febddd9327;algorithm=MD5;content=DOCUMENT
              
           

Zawartość (Body):

{ 
   "order":{ 
      "orderId":"LDLW5N7MF4140324GUEST000P01", 
      "extOrderId":"Id zamówienia w Twoim sklepie", 
      "orderCreateDate":"2012-12-31T12:00:00", 
      "notifyUrl":"http://tempuri.org/notify", 
      "customerIp":"127.0.0.1", 
      "merchantPosId":"{Id punktu płatności (pos_id)}", 
      "description":"Twój opis zamówienia", 
      "currencyCode":"PLN", 
      "totalAmount":"200", 
      "buyer":{ 
         "email":"john.doe@example.org", 
         "phone":"111111111", 
         "firstName":"John", 
         "lastName":"Doe",
         "language":"pl"
      },
      "payMethod": {
         "amount": "200",
         "type": "PBL" //lub "CARD_TOKEN", "INSTALLMENTS"
      },
      "products":[
         { 
               "name":"Product 1", 
               "unitPrice":"200", 
               "quantity":"1" 
         }
      ], 
      "status":"COMPLETED" 
   },
   "localReceiptDateTime": "2016-03-02T12:58:14.828+01:00",
   "properties": [
      {
         "name": "PAYMENT_ID",
         "value": "151471228"
      }
   ]
}       
            

Uwaga:

• "localReceiptDateTime" występuje tylko w przypadku statusu "COMPLETED".
• "PAYMENT_ID" oznacza identyfikator płatności, widoczny na zestawieniach transakcji jako "Trans ID" i podczas wyszukiwania transakcji w Panelu Managera.
• PayU-Processing-Time (sekcja Headers) oznacza ile czasu trwało przetwarzanie po stronie PayU, do momentu próby wysłania pierwszej notyfikacji. Niektóre notyfikacje zostają celowo opóźnione przez PayU ponieważ Merchant może odbierać równolegle jedynie określoną liczbę notyfikacji (tzn. throttling). Wówczas czas opóźnienia nie wpływa na czas przetwarzania. Z czasu tego wyłączone jest również przetwarzanie po stronie banku oraz ogranizacji kartowej.
• "payMethod.type" oznacza typ metody płatności użytej do opłacenia zamówienia. "PBL" oznacza przelew online lub przelew tradycyjny, "CARD_TOKEN" płatność kartą (w tym Masterpass i Visa Checkout), a "INSTALLMENTS" płatność poprzez PayU|Raty.

Przykład dla zamówienia anulowanego:

{ 
   "order":{ 
      "orderId":"LDLW5N7MF4140324GUEST000P01", 
      "extOrderId":"Id zamówienia w Twoim sklepie", 
      "orderCreateDate":"2012-12-31T12:00:00", 
      "notifyUrl":"http://tempuri.org/notify", 
      "customerIp":"127.0.0.1", 
      "merchantPosId":"{Id punktu płatności (pos_id)}", 
      "description":"Twój opis zamówienia", 
      "currencyCode":"PLN", 
      "totalAmount":"200",
      "products":[ 
         { 
               "name":"Product 1", 
               "unitPrice":"200", 
               "quantity":"1" 
         }
      ], 
      "status":"CANCELED" 
   } 
}       
            

Przykład powiadomienia wysyłanego przez PayU do sklepu:

                {
                   "orderId": "2DVZMPMFPN140219GUEST000P01",
                   "extOrderId": "Id zamówienia w Twoim sklepie",
                   "refund": {
                      "refundId": "912128",
                      "amount": "15516",
                      "currencyCode": "PLN",
                      "status": "FINALIZED",
                      "statusDateTime": "2014-08-20T19:43:31.418+02:00",
                      "reason": "refund",
                      "reasonDescription": "na życzenie klienta",
                      "refundDate": "2014-08-20T19:43:30.150+02:00"
                   }
                }
            

Uwaga: W przypadku płatności metodą "PayU | Płacę później", środki zwracane są do pożyczkodawcy.

Żądanie zwrotu środków do kupującego może być wykonane w dwóch trybach: pełnym lub częściowym.

Aby zrealizować zwrot (pełny lub częściowy) środków na konto kupującego wyślij żądanie na endpoint /api/v2_1/orders/{orderId}/refunds przy użyciu metody POST. Przykłady takiego wywołania zaprezentowano poniżej

Zwrot pełny:

                curl -X POST https://secure.payu.com/api/v2_1/orders/H9LL64F37H160126GUEST000P01/refunds \
                -H "Content-Type: application/json" \
                -H "Authorization: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd" \
                -d '{
                        "refund": {
                            "description": "Refund"
                        }
                    }'
            

Zwrot częściowy

Dla zwrotów częściowych należy podać kwotę, która jest wyrażona w najmniejszych jednostkach monetarnych dla danej waluty (np. w Polsce najmniejszą jednostką jest grosz - 0,01PLN - więc kwota 10 PLN będzie wyrażona jako 1000). Natomiast sama waluta musi być zgodna z walutą z pierwotnego zamówienia.

W ramach jednego zamówienia możliwe jest wysłanie kilku żądań o zwrot częściowy. Suma wartości w poszczególnych żądaniach nie może przekraczać kwoty pierwotnego zamówienia.

System payu umożliwia wykonanie wielu zwrotów częściowych w tym samym czasie. W tym celu wymagane jest przesłanie w żądaniu parametru extRefundId. W sytuacji gdy zwroty częściowe nie będą wykonywane częściej niż raz na sekundę parametr extRefundId nie jest wymagany.

W przykładzie zaprezentowano zwrot częściowy na wartość 10 w walucie zamówienia:

                curl -X POST https://secure.payu.com/api/v2_1/orders/H9LL64F37H160126GUEST000P01/refunds \
                -H "Content-Type: application/json" \
                -H "Authorization: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd" \
                -d '{
                        "refund": {
                            "description": "Refund",
                            "amount": 1000
                        }
                    }'
            

Metody uwierzytelnienia znajdują się w sekcji: Uwierzytelnienie użytkownika API

Przyjęcie żądania przez system PayU zostanie potwierdzone odpowiedzią zawierającą odpowiedni status. Przykłady takich odpowiedzi zostały zawarte poniżej:

                {
                    "orderId":"ZXWZ53KQQM200702GUEST000P01",
                    "refund":{
                        "refundId":"5000009987",
                        "extRefundId":"20200702091903",
                        "amount":"21000",
                        "currencyCode":"PLN",
                        "description":"Uznanie 5000009987 Refund",
                        "creationDateTime":"2020-07-02T09:19:03.896+02:00",
                        "status":"PENDING",
                        "statusDateTime":"2020-07-02T09:19:04.013+02:00"
                    },
                    "status":{
                        "statusCode":"SUCCESS",
                        "statusDesc":"Refund queued for processing"
                    }
                }
                
            

W przypadku odrzucenia spowodowanego jednym z błędów:

                {
                    "status":{
                        "statusCode":"ERROR_VALUE_MISSING",
                        "severity":"ERROR",
                        "code":"8300",
                        "codeLiteral":"MISSING_REFUND_SECTION",
                        "statusDesc":"Missing required field"
                    }
                }
                
            

Poprawnie przyjęte przez system PayU żądanie zwrotu środków może być anulowane z poziomu Panelu Menadżerskiego.

Kody błędów tworzenia zwrotów

W przypadku wysłania błędnego żądania zwrotu, pole status w odpowiedzi będzie zawierać opis problemu. Znaczenie poszczególnych pól przedstawia tabela poniżej:

Aby pobrać informacje o zwrotach związanych z daną transakcją wyślij żądanie na endpoint /api/v2_1/orders/<orderId>/refunds przy użyciu metody GET. W odpowiedzi otrzymasz listę zwrotów dokonanych w zakresie tej transakcji:

                {
                    "refunds": [
                        {
                            "refundId": "5000000142",
                            "extRefundId":    "postman_refund1_QX9ZR7M6QP200601GUEST000P01",
                            "amount": "400",
                            "currencyCode": "PLN",
                            "description": "Zwrot transakcji BLIK",
                            "creationDateTime": "2020-06-01T13:05:39.489+02:00",
                            "statusDateTime": "2020-06-01T13:06:03.530+02:00",
                            "status": "FINALIZED"
                        },
                        {
                            "refundId": "5000000143",
                            "extRefundId": "postman_refund2_QX9ZR7M6QP200601GUEST000P01",
                            "amount": "400",
                            "currencyCode": "PLN",
                            "description": "Zwrot transakcji BLIK",
                            "creationDateTime": "2020-06-01T13:18:03.648+02:00",
                            "statusDateTime": "2020-06-01T13:18:33.661+02:00",
                            "status": "FINALIZED"
                        }
                    ]
                }
                
            

Możliwe jest również pobranie informacji o konkretnym zwrocie. W tym celu wyślij żądanie na endpoint /api/v2_1/orders/<orderId>/refunds/<refundId> przy użyciu metody GET. W odpowiedzi otrzymasz informacje dotyczące zwrotu o podanym refundId:

                {
                    "refundId": "5000000108",
                    "extRefundId": "pm_bst_refund_QLQWXCSM1D200609GUEST000P01_1591707454318",
                    "amount": "999",
                    "currencyCode": "PLN",
                    "description": "Zwrot transakcji",
                    "creationDateTime": "2020-06-09T14:57:34.594+02:00",
                    "statusDateTime": "2020-06-09T14:57:55.370+02:00",
                    "status": "CANCELED",
                    "statusError": {
                        "code": "PROVIDER_TECHNICAL_ERROR",
                        "description": "Temporary problem on Provider Side"
                    }
                }
                
            

Kody błędów autoryzacji zwrotów

Jeżeli zwrot zostanie wykonany błędnie tzn. autoryzacja zwrotu u dostawcy się nie powiedzie, to po wysłaniu żądania otrzymasz odpowiedź o błędzie wraz ze szczegółowymi informacjami:

                {
                    "refundId": "5000000108",
                    "extRefundId": "pm_bst_refund_QLQWXCSM1D200609GUEST000P01_1591707454318",
                    "amount": "999",
                    "currencyCode": "PLN",
                    "description": "Zwrot transakcji",
                    "creationDateTime": "2020-06-09T14:57:34.594+02:00",
                    "statusDateTime": "2020-06-09T14:57:55.370+02:00",
                    "status": "CANCELED",
                    "statusError": {
                        "code": "PROVIDER_TECHNICAL_ERROR",
                        "description": "Temporary problem on Provider Side"
                    }
                }
                
            

W tabeli zawarto kody błędów, które mogą wystąpić w trakcie procesowania zwrotu oraz wskazówkę co należy zrobić w każdym z przypadków:

Żądanie anulowania dotyczy zawsze całego zamówienia. Anulowanie skutkuje zwrotem środków na konto kupującego.

Aby anulować zamówienie i dokonać zwrotu środków na konto kupującego należy wywołać metodę /api/v2_1/orders/{orderId} przy użyciu metody DELETE. Przykład takiego wywołania znajduje się poniżej.

Anulować można jedynie zamówienie, które nie zostało jeszcze zakończone, tj. nie ma statusu COMPLETED.

Przykład odpowiedzi po anulowaniu zamówienia z użyciem API

{ 
   "orderId":"71S3CTJJXV140325GUEST000P01", 
   "extOrderId":"your_order_id"
   "status":{  
      "statusCode":"SUCCESS"
   }
}
            

Odebranie dotyczy zawsze całego zamówienia. Wykonanie tej operacji powoduje zmianę statusu zamówienia na COMPLETED (zakończona).

W celu zmiany statusu zamówienia należy wywołać usługę /api/v2_1/orders/{orderId}/status przy użyciu metody PUT.

Przykład odebrania zamówienia z użyciem API

curl -X PUT https://secure.payu.com/api/v2_1/orders/H9LL64F37H160126GUEST000P01/status \
-H "Content-Type: application/json" \
-H "Authorization: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd" \
-d '{
    "orderId": "H9LL64F37H160126GUEST000P01",
    "orderStatus": "COMPLETED"
}'
            

Przykład odpowiedzi z serwera po udanej zmianie statusu zamówienia

{
      "status": {
           "statusCode": "SUCCESS",
           "statusDesc": "Status was updated"
      }
}
            

Komunikat OrderRetrieveRequest pozwala pobrać dane i status zamówienia.

Należy wysłać żądanie HTTP GET na adres https://secure.payu.com/api/v2_1/orders/{orderId}

Przykład odpowiedzi po pobraniu informacji o zamówieniu:

                             {
                                    "orders": [
                                        {
                                            "orderId": "{orderId}",
                                            "extOrderId": "358766",
                                            "orderCreateDate": "2014-10-27T14:58:17.443+01:00",
                                            "notifyUrl": "http://localhost/OrderNotify/",
                                            "customerIp": "127.0.0.1",
                                            "merchantPosId": "145227",
                                            "description": "New order",
                                            "currencyCode": "PLN",
                                            "totalAmount": "3200",
                                            "status": "NEW",
                                            "products": [
                                                {
                                                    "name": "Product1",
                                                    "unitPrice": "1000",
                                                    "quantity": "1"
                                                },
                                                {
                                                    "name": "Product2",
                                                    "unitPrice": "2200",
                                                    "quantity": "1"
                                                }
                                            ]
                                        }
                                    ],
                                    "status": {
                                        "statusCode": "SUCCESS",
                                        "statusDesc": "Request processing successful"
                                    },
                                    "properties": [
                                        {
                                            "name": "PAYMENT_ID",
                                            "value": "1234567890"
                                        }
                                    ]        
                            }
                

Więcej informacji na temat parametrów komunikatu znajdziesz w rozdziale Parametry komunikatów JSON w opisie pól komunikatów OrderRetrieveRequest i OrderRetrieveResponse.

Komunikat TransactionRetrieveRequest umożliwia pobranie danych o transakcji utworzonej do danego zamówienia.

Należy wysłać żądanie HTTP GET na adres https://secure.payu.com/api/v2_1/orders/{orderId}/transactions

Ten endpoint jest szczególnie użyteczny, jeśli konieczne jest pobranie danych konta bankowego (numer, posiadacz) lub karty płatniczej (maskowany numer, rodzaj karty).

Opisy parametrów używanych w TransactionRetrieveRequest i TransactionRetrieveResponse można znaleźć Tutaj.

Uwaga: dane karty są dostępne natychmiast po przetworzeniu, ale dane konta bankowego są dostępne w okresie od kilku minut do następnego dnia roboczego, zależnie od banku.

Przykład odpowiedzi po pobraniu informacji o transakcji kartą:

                  
                  {
                    "transactions": [
                      {
                        "payMethod": {
                          "value": "c"
                        },
                        "paymentFlow": "FIRST_ONE_CLICK_CARD",
                        "card": {
                          "cardData": {
                            "cardNumberMasked": "543402******4014",
                            "cardScheme": "MC",
                            "cardProfile": "CONSUMER",
                            "cardClassification": "DEBIT",
                            "cardResponseCode":"000",
                            "cardResponseCodeDesc":"000 - OK",
                            "cardEciCode":"2",
                            "card3DsStatus":"Y",
                            "card3DsStatusDescription": "MessageVersion=2.1.0,browser flow,3DS method not available,dynamic authentication,no cancel indicator,no status reason",
                            "cardBinCountry":"PL",
                            "firstTransactionId": "MCC0111LL1121"
                          },
                          "cardInstallmentProposal": { //obiekt opcjonalny, zapoznaj się z notką pod przykładem
                            "proposalId": "5aff3ba8-0c37-4da1-ba4a-4ff24bcc2eed"
                          }
                        },
                        "resultCode": "AUT_ERROR_NO_AUTHORIZATION" // parametr opcjonalny
                      }
                    ]
                  }
                

Sekcja cardInstallmentProposal jest wykorzystywana tylko w usłudze Płać w ratach z Mastercard.

{  
   "transactions":[  
      {  
         "payMethod":{  
            "value":"m"
         },
         "bankAccount":{  
            "number":"80607787095718703296721164",
            "name":"JAN KOWALSKI", 
            //uwaga: zależnie od banku, imię, nazwisko i adres 
            //mogą zostać rozparsowane do dowolnego z poniższych pól 
            "city":"WARSZAWA",
            "postalCode":"02-638",
            "street":"UL.NOWOWIEJSKIEGO 8",
            "address":"Warszawa Nowowiejskiego 8"
         }
      }
   ]
}
                

Wyjaśnienia parametrów występujących w TransactionRetrieveRequest i TransactionRetrieveResponse można znaleźć Tutaj.

Aby móc pobrać dane sklepu należy najpierw wygenerować token uwierzytelniający.

Punkt płatności, który jest wykorzystywany do wygenerowania tokenu oAuth'owego musi należeć do sklepu, którego dane są pobierane.

Następnie należy wysłać żądanie HTTP GET na adres https://secure.payu.com/api/v2_1/shops/{public_shop_id}

Przykład żądania pobrania danych sklepu

                    curl -X GET https://secure.snd.payu.com/api/v2_1/shops/QFw0KGSX \
                    -H 'Content-Type: application/json' \
                    -H 'Authorization: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd'
                    
                

Przykład odpowiedzi po pobraniu danych sklepu

                    {
                        "shopId": "QFw0KGSX",
                        "name": "Shop Checkout",
                        "currencyCode": "PLN",
                        "balance": {
                            "currencyCode": "PLN",
                            "total": "220839",
                            "available": "220839"
                        }
                    }
                    
                

total przedstawia aktualne środki na saldzie sklepu w groszach.

available pokazuje środki na saldzie sklepu po odjęciu blokad/rezerwy wypłatowej.

Aby wyświetlić metody płatności w najbardziej odpowiedni sposób, należy je wcześniej pobrać. Dodatkowo, należy umieścić wymagane przepisami prawa informacje o PayU jako operatorze płatności. Jest to dokładniej omówione poniżej.

Transparentne zamówienie

Tworzenie zamówień z podaniem metody płatności wymaga umieszczenia sekcji payMethod i podania wartości reprezentującej metodę wybraną przez kupującego na stronie sklepu.

                    {
                        "payMethods": {
                            "payMethod":    {
                                "type":"PBL",
                                "value":"m",
                                //opcjonalne dla BLIK (blik) i Visa Checkout (vc), zob. niżej
                                "authorizationCode":"123456",
                                //opcjonalne dla Visa Checkout, zob. niżej
                                "specificData": [] 
                            }
                        }
                    }
                    

Dla metody "blik" możliwe jest zarówno przekierowanie na stronę BLIK jak i pobranie 6-cyfrowego kodu autoryzacji na stronie sklepu. W tym ostatnim przypadku, parametr authorizationCode musi być podany w sekcji payMethods. Ponadto kod HTTP dla udanego żądania to 201 zamiast standardowego 302.

Wszystkie usługi BLIK poza opcją Przekierowanie na stronę płatności BLIK wymagają specjalnej konfiguracji punktu płatności (POS) ze strony PayU. Konfiguracja pozwalająca na Transparentną płatność kodem autoryzacyjnym BLIK nie jest kompatybilna z wariantem Przekierowanie na stronę płatności BLIK, przez co wymaga obsługi na osobnym punkcie płatności.

Więcej informacji: Tworzenie nowego zamówienia przez API, Kody statusów i Visa Checkout.

Przykład pozytywnej odpowiedzi

{
    "orderId":"VVLR1HXK2S160929GUEST000P01",
    "status": {
        "statusCode":"SUCCESS"
    },
    "redirectUri":"https://www.platnosci.pl/np/newpayment.resume.action?paymentId=12345678&hash={HashNumber}&js=1"
}
                

Przykład odpowiedzi dla banków: orx, bnx, gbx, nlx.

{
    "orderId":"1BSLZN2FFZ160929GUEST000P01",
    "extOrderId":"number of extOrderId",
    "status": {
        "statusCode":"WARNING_CONTINUE_REDIRECT"
    },
    "redirectUri":"https://secure.getinbank.pl/pbl/#index/index/{index}"
}
                

Aby pobrać aktualnie dostępne metody płatności, należy najpierw uzyskać access token.

Zob. sekcję OAuth w Uwierzytelnienie użytkownika API

Następnie należy wstawić uzyskany access token do nagłówka i metodą GET wysłać żądanie na api/v2_1/paymethods.

W celu uzyskania opisów w konkretnym języku, można użyć opcjonalnego parametru: ?lang={2-literowy kod ISO}, np. 'cs', 'de', 'pl'.

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

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

Przykład pozytywnej odpowiedzi (HTTP 200). Opis poszczególnych pól poniżej przykładu:

{  
   
   "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_off.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_off.png",
         "status":"TEMPORARY_DISABLED"
         "minAmount": 50,
         "maxAmount": 100000
      }
   ]
}          
            

payByLinks

Obowiązki informacyjne wynikają z regulacji obowiązujących w Unii Europejskiej dotyczących usług płatniczych (tzw. PSD od ang. Payment Services Directive) i rozporządzenia o ochronie danych osobowych (RODO lub GDPR od ang. General Data Protection Regulation).

W przypadku standardowej integracji (wybór metody płatności na stronie PayU), informacje te są wyświetlane w stopce strony płatniczej PayU.

W przypadku integracji transparentnej, w celu ułatwienia spełnienia obowiązków wynikających z ww. regulacji, stosowne informacje są wyświetlane:

1. na stronie płatniczej PayU (w przypadku płatności kartą poprzez stronę PayU oraz usług PayU | Raty i PayU | Płacę później)
2. na stronie pośredniej, wyświetlanej przed przekierowaniem do banku (w przypadku szybkiego przelewu lub przelewu tradycyjnego)

Istnieje możliwość rezygnacji ze strony pośredniej, jednak pod warunkiem, że wymagane prawem informacje zostaną wyświetlone na stronie sklepu/odbiorcy płatności. Wymaga to konfiguracji po stronie PayU.

W tym celu należy umieścić poniższe treści i odnośniki oraz skontaktować się z PayU wysyłając wysyłając wiadomość z linkiem do strony i zrzutem ekranu na adres help@payu.pl.

_{Zlecenie realizacji płatności: Zlecenie wykonuje PayU SA; Dane odbiorcy, tytuł oraz kwota płatności dostarczane są PayU SA przez odbiorcę; Zlecenie jest przekazywane do realizacji po otrzymaniu przez PayU SA Państwa wpłaty. Płatność udostępniana jest odbiorcy w ciągu 1 godziny, nie później niż do końca następnego dnia roboczego; PayU SA nie pobiera opłaty od realizacji usługi.}

_{Płacąc akceptujesz Zasady płatności PayU.}

_{Administratorem Twoich danych osobowych jest PayU S.A. z siedzibą w Poznaniu (60-166), przy ul. Grunwaldzkiej 186. Twoje dane osobowe będą przetwarzane w celu realizacji transakcji płatniczej, powiadamiania Cię o statusie realizacji Twojej płatności, rozpatrywania reklamacji, a także w celu wypełnienia obowiązków prawnych ciążących na PayU.}

_{Odbiorcami Twoich danych osobowych mogą być podmioty współpracujące z PayU w procesie realizacji płatności. W zależności od wybranej przez Ciebie metody płatności mogą to być: banki, instytucje płatnicze, instytucje pożyczkowe, organizacje kart płatniczych, schematy płatnicze), ponadto podmioty wspierające działalność PayU tj. dostawcy infrastruktury IT, dostawcy narzędzi do analizy ryzyka płatności a także podmiotom uprawnionym do ich otrzymania na mocy obowiązujących przepisów prawa, w tym właściwym organom wymiaru sprawiedliwości. Twoje dane mogą zostać udostępnione akceptantom celem poinformowania ich o statusie realizacji płatności. Przysługuje Tobie prawo dostępu do danych, a także do ich sprostowania, ograniczenia ich przetwarzania, zgłoszenia sprzeciwu wobec ich przetwarzania, niepodlegania zautomatyzowanemu podejmowaniu decyzji w tym profilowania oraz do przenoszenia i usunięcia danych. Podanie danych jest dobrowolne jednak niezbędne do realizacji płatności, a brak podania danych może skutkować odrzuceniem płatności. Więcej informacji o zasadach przetwarzania Twoich danych osobowych przez PayU znajdziesz w Polityce Prywatności}.

Uwagi:

1. informacja dotycząca zlecenia realizacji płatności powinna zostać wyświetlona tylko w przypadku jeśli strona jest przeznaczona dla użytkowników z Polski. Jeśli przyjmujesz płatności na stronie skierowanej do użytkowników z innych krajów i w innej wersji językowej (np. angielskiej, czeskiej, niemieckiej, węgierskiej itd.), nie ma obowiązku wyświetlania takich informacji. Natomiast zawsze należy pokazać informacje dotyczące przetwarzania danych osobowych.
2. W przypadku informacji o przetwarzaniu danych osobowych, sugerujemy aby pokazać tylko pierwszy z akapitów, a drugi wyświetlić po wykonaniu akcji przez użytkownika (np. kliknięciu w napis "czytaj więcej").
3. Powyższe informacje są dostępne w poniższych wersjach językowych.

Informacje o PayU

Formularz hostowany przez PayU

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 stronie Security Standards Council.

Aby wywołać formularz bezpośrednio, należy dodać poniższy obiekt do żądania OrderCreateRequest:

                    {
                        "payMethods": {
                            "payMethod":    {
                                "type":"PBL",
                                "value":"c"
                            }
                        }
                    }
                

Po utworzeniu zamówienia z użyciem powyższej sekcji, jako "redirectUri" zwrócony zostanie adres strony płatności kartą.

Wersja językowa strony jest wybierana jest zgodnie z logiką podaną poniżej:

1. na podstawie parametru lang dodanego do query string w "redirectUri", np. "&lang=en",
2. na podstawie pola language w obiekcie Buyer. Zob. więcej o obiekcie Buyer,
3. na podstawie języka przeglądarki,
4. a jeśli żaden z powyższych języków nie jest wspierany, użyta będzie wersja angielska. Lista dostępnych języków jest tutaj.

W celu zwiększenia konwersji, formularz ma możliwość przewalutowania dla najbardziej popularnych par walutowych (np. z PLN do EUR). Płatnik może wybrać płatność w innej walucie (np. EUR), podczas gdy sklep nadal otrzyma środki w swojej walucie (np. PLN).

Opcją bardziej zaawansowaną jest użycie Secure Form lub budowa własnego formularza.

Token reprezentujący dane karty zwrócony przez Secure Form należy wysłać do PayU w obiekcie payMethods.

                    {
                        "payMethods": {
                            "payMethod":    {
                                "type":"CARD_TOKEN",
                                "value":"TOK_1IHRPT6HKSSS3H62K0GS8pElP862"
                            }
                        }
                    }
                

Własny formularz

Możliwe jest wykonanie własnego formularza. Jego wygląd i ostylowanie są dowolne, należy jednak pamiętać o obowiązkach informacyjnych opisanych powyżej.

Wskazówki do wykonania własnego formularza zawierającego skrypty PayU są podane tutaj.

Uwaga: w przypadku kiedy karty nie są zapisywane na poczet przyszłych płatności, można pominąć poniższe pole.

 <tr>
    <td>Akceptacja regulaminu Konta PayU i zgoda na zapisanie karty</td>
    <td><input type="checkbox" value="false" class="payu-agreement"></td>
 </tr>               

Token reprezentujący dane karty zwrócony przez Secure Form należy wysłać do PayU w obiekcie payMethods.

                    {
                        "payMethods": {
                            "payMethod":    {
                                "type":"CARD_TOKEN",
                                "value":"TOK_1IHRPT6HKSSS3H62K0GS8pElP862"
                            }
                        }
                    }
                

Dane kartowe w postaci tekstowej

Możliwe jest wysłanie danych kartowych w postaci tekstowej. Dane kartowe należy przekazać w obiekcie payMethods. Przykład:

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

Kod odpowiedzi, jest standardowym kodem odpowiedzi dla kart, najważniejsze to: SUCCES, WARNING_CONTINUE_3DS, WARNING_CONTINUE_CVV. Wyjaśnienie oraz pozostałe kody odpowiedzi zawarto w: Kody statusów.

Uwaga: dane kartowe w postaci tekstowej wymagają dodatkowej konfiguracji. Dlatego przed przystąpieniem do integracji należy skontaktować się z opiekunem handlowym w PayU.

OAuth

Uwierzytelnienie polega na pobraniu tokena OAuth'owego. Token używany jest w dalszej komunikacji z serwerami PayU. Dane potrzebne do autoryzacji znajdują się w panelu menadżerskim. Rozróżniamy dwa tryby dostępów: client_credentials służący do standardowej integracji oraz trusted_merchant służący do uwierzytelniania żądań dla zalogowanych użytkowników sklepu/aplikacji z przypisanym stałym identyfikatorem ext_customer_id.

Pamiętaj, aby dodać nagłówek Content-Type: application/x-www-form-urlencoded, w przeciwnym razie zostanie zwrócony błąd 401.

Przykład requesta pobierającego token w obu trybach:

curl -X POST https://secure.snd.payu.com/pl/standard/user/oauth/authorize \
-d 'grant_type=client_credentials&client_id=460718&client_secret=22f4175da9f0f72bcce976dd8bd7504f'

curl -X POST https://secure.payu.com/pl/standard/user/oauth/authorize \
-d 'grant_type=trusted_merchant&amp;client_id=145227&amp;client_secret=12f071174cb7eb79d4aac5bc2f07563f&amp;email=<customerEmail>&amp;ext_customer_id=<customerId>'

Parametry żądania:

Przykład odpowiedzi:

                    {
                        "access_token":"8f79c971-195e-43f5-bd83-ad2104414acc",
                        "token_type":"bearer",
                        "expires_in":43199, //czas ważności w sekundach
                        "grant_type":"client_credentials"
                    }  
                

Przykład zamówienia z tokenem OAuth'owym:

                    curl -X POST https://secure.payu.com/api/v2_1/orders \
                    -H "Content-Type: application/json" \
                    -H "Authorization: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd" \
                    -d '{
                        "customerIp": "127.0.0.1",
                        "merchantPosId": "145227",
                        "description": "RTV market",
                        "currencyCode": "PLN",
                        "totalAmount": "21000",
                        "products": [
                             {
                                 "name": "Wireless Mouse for Laptop",
                                 "unitPrice": "21000",
                                 "quantity": "1"
                             }
                         ]
                    }'
                

Dopuszczalne funkcje skrótu

Parametr algorithm może przyjmować poniższe wartości:

• SHA-256,
• SHA-384,
• SHA-512.

Algorytm generowania podpisu parametrów formularza

1. Posortuj wszystkie pola formularza alfabetycznie według nazw parametrów (atrybut name elementu input) w porządku rosnącym.
2. Dokonaj konkatenacji kluczy i wartości wszystkich pól formularza zgodnie z wcześniej wyznaczonym porządkiem (klucz=wartość), rozdzielając je znakiem ampersand &. Wartości parametrów muszą być poddane kodowaniu URL (URL encoding, application/x-www-form-urlencoded, znak spacji zamieniany na '+') przy użyciu UTF-8.
3. Do tak powstałego ciągu znaków dodaj swój klucz prywatny (widoczny w Panelu Managera jako Drugi klucz (MD5)).
4. Użyj jednej z dopuszczalnych funkcji skrótu na tak powstałym ciągu znaków.
5. Uzupełnij pole OpenPayU-Signature wartością signature=A;algorithm=B;sender=C, gdzie:
   • A to wynik funkcji skrótu,
   • B to nazwa użytej funkcji skrótu,
   • C to identyfikator POSa.

Pseudokod algorytmu generowania podpisu parametrów formularza

generate_signature(form, secondKey, algorithm, posId) {
    sortedValues = sortValuesByItsName(form)

    foreach value in sortedValues {
        content = content + parameterName + "=" + urlencode(value) + "&"
    }

    content = content + secondKey

    result = "signature=" + algorithm.apply(content) + ";"
    result = result + "algorithm=" + algorithm.name + ";"
    result = result + "sender=" + posId
      
    return result
}
                

Przykład kodu z sdk OpenPayU OpenPayU SDK.

Podpis przykładowego formularza

                    <input type="hidden"name="customerIp" value="123.123.123.123">
                    <input type="hidden"name="merchantPosId" value="145227">
                    <input type="hidden"name="description" value="Opis zamówienia">
                    <input type="hidden"name="totalAmount" value="1000">
                    <input type="hidden"name="currencyCode" value="PLN">
                    <input type="hidden"name="products[0].name" value="Produkt 1">
                    <input type="hidden"name="products[0].unitPrice" value="1000">
                    <input type="hidden"name="products[0].quantity" value="1">
                    <input type="hidden"name="notifyUrl" value="http://shop.url/notify"> 
                    <input type="hidden"name="continueUrl" value="http://shop.url/continue">                

continueUrl=http%3A%2F%2Fshop.url%2Fcontinue&currencyCode=PLN&customerIp=123.123.123.123&description=Opis+zam%C3%B3wienia&merchantPosId=145227&notifyUrl=http%3A%2F%2Fshop.url%2Fnotify&products[0].name=Produkt+1&products[0].quantity=1&products[0].unitPrice=1000&totalAmount=1000&13a980d4f851f3d9a1cfc792fb1f5e50

565f9f4dda43c8e24ccab4472133d680e2aa58e1f58bea845c4cf2926965144d                

<input name="OpenPayu-Signature" value="sender=145227;algorithm=SHA-256;signature=565f9f4dda43c8e24ccab4472133d680e2aa58e1f58bea845c4cf2926965144d">

W przypadku pytań prosimy o kontakt.

Przykładowy nagłówek:

OpenPayu-Signature: 
                sender=checkout;
                signature=c33a38d89fb60f873c039fcec3a14743;
                algorithm=MD5;
                content=DOCUMENT

Postępuj według następujących instrukcji:

1. Należy pobrać nagłówek OpenPayu-Signature z notyfikacji przychodzącej z serwera PayU
2. Wyizolować wartość signature z nagłówka OpenPayu-Signature:

   string incoming_signature = signature_header[signature]

3. Sprawdzić rodzaj funkcji haszującej, którą się posłużono do wygenerowania podpisu (najczęściej md5)
4. Dokonać połączenia treści odebranej notyfikacji oraz wartości drugiego klucza (second_key):

   string concatenated = JSONnotification + second_key;

5. Wyznaczyć oczekiwaną wartość podpisu poprzez zastosowanie wykorzystanej funkcji haszującej(np. md5) na uzyskanym łańcuchu znaków:

   string expected_signature = md5(concatenated)

6. Dokonać porównania łańcuchów: expected_signature oraz incoming_signature:

    if(expected_signature == incoming_signature){
        return true; //podpis jest prawidłowy
    }else{
        return 'Wrong signature' // podpis nie jest prawidłowy
    }
                       

Parametry do wykorzystania w komunikacie OrderCreateRequest

Używanie znaków specjalnych w opisach transakcji nie jest zalecane przez PayU. Niektóre znaki nie są akceptowane przez banki.

Opis możliwych do wykorzystania pól:

Parametr	Opis	Wymagany
extOrderId	Identyfikator zamówienia nadany przez Sprzedającego. Umożliwia Sprzedającemu odnalezienie zamówienia we własnym systemie. Wartość musi być unikalna w ramach jednego punktu płatności.	Nie
notifyUrl	Adres pod który będą przesyłane powiadomienia.	Nie
customerIp	Adres IP płacącego, np. "123.123.123.123" (uwaga: adres "0.0.0.0" nie jest dopuszczalny).	Tak
merchantPosId	Identyfikator punktu płatności na którym zostanie wykonana płatność.	Tak
validityTime	Czas w trakcie którego możliwe jest dokończenie zamówienia w sekundach. Domyślna wartość 86400.	Nie
description	Opis zamówienia.	Tak
additionalDescription	Dodatkowy opis zamówienia.	Nie
visibleDescription	Tekst widoczny na stronie płatniczej PayU (maks. 80 znaków).	Nie
statementDescription	Nazwa odbiorcy płatności i opis płatności (np. nr zamówienia, nr biletu) widoczny na rachunku karty płatniczej (maks. 22 znaki). Powinien zawierać czytelną nazwę obiorcy (np. "sklep.pl zam. 124343"). Jeśli pole nie zostanie przesłane, zastosowana zostanie nazwa skonfigurowana przez PayU.	Nie
currencyCode	Waluta zamówienia w standardzie ISO 4217, np. "PLN".	Tak
totalAmount	Całkowity koszt zamówienia w groszach (np. 1000 to 10,00 EUR). Dotyczy również walut bez groszy (tj. 1000 to 10 HUF).	Tak
cardOnFile	Informuje o stronie inicjującej płatność: FIRST - płatność zainicjowana przez posiadacza karty, który zgodził się na jej zapisanie, w celu przyszłego użycia. Możesz spodziewać się pełnego uwierzytelnienia (3D Secure i/lub CVV). Jeżeli, przy przyszłych płatnościach, chcesz skorzystać z wielorazowego tokenu (TOKC_) pierwsza transakcja musi zakończyć się pomyślnie. Domyślna wartość przy jednorazowym tokenie (TOK_). W przypadku płatności danymi kartowymi parametr firstTransactionId powinien być przesłany w sekcji payMethods.payMethod.card dla transakcji oznaczonych jako STANDARD, STANDARD_CARDHOLDER i STANDARD_MERCHANT; STANDARD_CARDHOLDER – płatność zapisaną kartą zainicjowana przez posiadacza karty. W tym przypadku wykorzystuje się token wielorazowego użytku (TOKC_). W zależności od parametrów transakcji (np. wysoka kwota) możesz oczekiwać silnego uwierzytelnienia (3D Secure i/lub CVV). Domyślna wartość przy wielorazowym tokenie (TOKC_); STANDARD_MERCHANT – płatność zapisaną kartą zainicjowana przez sprzedawcę bez udziału posiadacza karty. W tym przypadku wykorzystuje się token wielorazowego użytku (TOKC_). Ten typ transakcji nie wymaga silnego uwierzytelnienia. Transakcja tego typu nie może być przeprowadzona jeżeli pierwsza transakcja (FIRST) nie została zakończona pomyślnie. Nie może być użyty razem z parametrem recurring.	Nie, powinien być użyty w przypadku płatności z danymi kartowymi lub z wykorzystaniem wielorazowego tokenu (TOKC_).
recurring	Sprawia, że transakcja jest traktowana jako cykliczna:. FIRST - płatność zainicjowana przez posiadacza karty, który zgodził się na jej zapisanie w celu przyszłego użycia. Możesz oczekiwać pełnego uwierzytelnienia (3D Secure i/lub CVV). Jeżeli, przy przyszłych płatnościach, chcesz skorzystać z wielorazowego tokenu (TOKC_) pierwsza transakcja musi zakończyć się pomyślnie. STANDARD - każda kolejna płatność cykliczna (użytkownik nie jest obecny przy transakcji). W tym przypadku wykorzystuje się token wielorazowego użytku (TOKC_). Transakcja tego typu nie może być przeprowadzona jeżeli pierwsza transakcja (FIRST) nie została zakończona pomyślnie. Nie może być użyty razem z parametrem cardOnFile. Sugerowane jest wysłanie również obiektu recurring w sekcji dot. 3DS.	Nie, powinien być użyty jedynie w przypadku płatności cyklicznych z wykorzystaniem wielorazowego tokenu (TOKC_).
continueUrl	Adres na jaki będzie przekierowany płatnik po zakończeniu procesu płatności. Jeśli płatność się nie powiodła, do adresu dodany zostanie parametr error=501, jednak żadna decyzja odnośnie statusu płatności nie powinna być podejmowana na podstawie obecności lub braku tego parametru. Aby uzyskać status płatności, należy poczekać na notyfikację lub pobrać dane zamówienia. WAŻNE: adres musi być zgodny ze strukturą: Ponadto: możliwe schematy to http i https, elementy takie jak port, ścieżka, zapytanie, fragment są opcjonalne, wartości zapytania muszą być zakodowane (URL encoded).	Nie
buyer	Sekcja przechowująca dane kupującego. Jej użycie jest mocno zalecane, ponieważ w przypadku braku podania tej sekcji, użytkownik będzie proszony o uzupełnienie danych na stronie PayU, a płatności typu Raty lub Płacę później nie będą możliwe. Opis pól sekcji <buyer>	Nie, zalecany
products	Sekcja zawiera dane o produktach. Sekcja <products> to tablica obiektów typu <product>. Opis pól obiektu typu <product>	Tak
payMethods	Sekcja pozwala wskazać metodę płatności. Sekcja <payMethods> to jeden obiekt typu <payMethod>. Opis pól obiektu typu <payMethod>	Nie
mcpData	Sekcja umożliwia przesłanie szczegółów przewalutowania dla Multi-Currency Pricing. Opis pól sekcji <mcpData>.	Nie
threeDsAuthentication	Zawiera opcjonalne pola wymagane przez protokół uwierzytelnienia 3DS 2. Szczegóły dotyczące uwierzytelnienia 3DS 2 dla płatności kartowych znajdują się w 3DS 2. Opis pól sekcji <threeDsAuthentication>	Nie
credit	Sekcja przechowująca dane dotyczące procesu kredytowego. Jej użycie jest mocno zalecane, ponieważ w przypadku braku podania tej sekcji, użytkownik będzie proszony o uzupełnienie danych na stronie dostawcy płatności typu Raty lub Płacę później. Opis pól sekcji <credit>	Nie, ale zalecane

OrderCreateResponse - opis pól komunikatu

Powiadomienia - opis pól komunikatu

OrderStatusUpdateRequest - opis pól komunikatu

OrderStatusUpdateResponse - opis pól komunikatu

RefundCreateRequest - opis pól komunikatu

Opis RefundInfoType

RefundCreateResponse - opis pól komunikatu

Opis pól <RefundRecord_Type>

OrderCancelRequest - opis pól komunikatu

OrderCancelResponse - opis pól komunikatu

OrderRetrieveRequest - opis pól komunikatu

OrderRetrieveResponse - opis pól komunikatu

TransactionRetrieveRequest

Jedynym parametrem w tej sekcji jest orderId umieszczany w adresie żądania.

TransactionRetrieveResponse - for PBL

TransactionRetrieveResponse zawiera listę obiektów (transakcji w ramach zamówienia). W tej chwili jest to lista jednoelementowa. W najbliższej przyszłości planowane jest - w przypadku ponowienia płatności - rozszerzenie listy do większej liczby elementów.

Pozostałe (poniższe) pola odnoszące się do PBL są wypełniane w zależności o tego, jak parsowane są dane otrzymywane z banku.

TransactionRetrieveResponse - for cards

Sekcje wspólne

Opis pól obiektu typu <product>

Opis pól obiektu typu <payMethod> w OrderCreateRequest

Opis pól obiektu typu <payMethod> w notyfikacji

<mcpData> fields description

Opis pól sekcji <buyer>

Opis pól w sekcji <delivery>

Opis pól w sekcji <order>

Opis pól w sekcji <status>

OrderCreateRequest - obiekt threeDsAuthentication.

Opisy pól threeDsAuthentication.browser.

Opisy pólthreeDsAuthentication.exemption.

Opisy pól threeDsAuthentication.sdk. Wszystkie pola w poniższej tabeli są generowane przez certyfikowane 3DS SDK.

Opisy pól threeDsAuthentication.merchantRiskIndicator.

Opisy pól threeDsAuthentication.recurring.

Opisy pól threeDsAuthentication.cardholder.

Opisy pól threeDsAuthentication.cardholder.accountInformation.

Opisy pólthreeDsAuthentication.cardholder.billingAddress.

Opis pól sekcji credit

Sekcja credit opisuje dane dotyczące procesu kredytowego. Nie jest wymagana. Jej użycie jest jednak mocno zalecane, ponieważ w przypadku braku podania tej sekcji, użytkownik będzie proszony o uzupełnienie danych na stronie dostawcy płatności typu Raty lub Płacę później.

Opis pól sekcji shoppingCart

Opis pól sekcji shippingMethod

Opis pól sekcji address

Opis pól sekcji credit.applicant

Opis pól sekcji credit.applicant_additionalInfo

Parametry ogólne

Używanie znaków specjalnych w opisach transakcji nie jest zalecane przez PayU. Niektóre znaki nie są akceptowane przez banki.

Adresy URL

Parametr	Wymagany	Opis
continueUrl	Nie	Adres na jaki będzie przekierowany płatnik po zakończeniu procesu płatności. Jeśli płatność się nie powiodła, do adresu dodany zostanie parametr error=501, jednak żadna decyzja odnośnie statusu płatności nie powinna być podejmowana na podstawie obecności lub braku tego parametru. Aby uzyskać status płatności, należy poczekać na notyfikację lub pobrać dane zamówienia). WAŻNE: adres musi być zgodny ze strukturą poniżej: Ponadto: możliwe schematy to http i https, elementy takie jak port, ścieżka, zapytanie, fragment są opcjonalne, wartości zapytania muszą być zakodowane (URL encoded).
notifyUrl	Nie	Adres URL, na który przychodzić będą powiadomienia o zmianie statusu zamówienia lub zwrotu.

Kupujący

Adres do wysyłki

Sekcja buyer.delivery opisuje adres do wysyłki. Nie jest wymagana.

Produkty

Sekcja products jest obowiązkowa i opisuje listę produktów zamówienia. W opisie używany jest iterator. Każdy produkt jest numerowany wartością z przedziału [0..n]. Przykładowo products[0].

W przypadku kontaktu z PayU w związku z nieudanymi żądaniami, prosimy o wysłanie zapytania z podaną wartością Correlation-Id przekazaną jako nagłówek odpowiedzi.

(*) Powód pokazuje, która ze stron zatrzymała transakcję i tym samym z kim należy się kontatkować, aby otrzymać więcej szczegółów dotyczących przyczyny problemu.

Statusy 3Ds:

1. Komunikacja powinna odbywać się szyfrowanym kanałem po protokole HTTPS przy użyciu zweryfikowanego i zaufanego certyfikatu.
2. Komunikaty operacyjne na POS powinny być podpisane funkcją skrotu np. SHA256, jeśli podpisy są wymagane dla danej operacji: restapi.html#references_form_signature
3. Adres na który wysyłane są statusy powiadomień z PayU powinien komunikować się szyfrowanym kanałem HTTPS.
4. Przy odbiorze powiadomień merchant powinien zawsze weryfikować wiarygodność odebranego powiadomienia poprzez sprawdzenie podpisów wiadomości. restapi.html#references_verification_of_notifications_signature
5. Merchant nigdy nie powinien publicznie udostępniać swoich kluczy MD5 dla POS. Jeśli dojdzie do sytuacji udostepnienia kluczy md5 do POS incydentalnie lub poprzez kradzież, merchant powinien niezwłocznie skontaktować się z BOK PayU.