REST API

Najprostszy i najwygodniejszy protokół integracji z PayU.

1 Wprowadzenie

Zanim zaczniesz zapoznawać się z poniższym dokumentem, warto przeczytać wprowadzenie, gdzie znajdują się informacje o tym jak zacząć współpracę z PayU i integrację API, jaki model integracji wybrać i jak ją testować.

Informacje o aktualnej wersji

Dokument zawiera informacje o protokole REST API w wersji 2.1.

Jeżeli poszukujesz informacji o starszej wersji API napisz na adres tech@payu.pl.

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.

2 Tworzenie nowego zamówienia

2.1 Tworzenie nowego zamówienia przez API

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.
Przykład zamówienia z podstawowymi danymi:
Produkcja  Sandbox

                  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": "21000",
                      "buyer": {
                          "email": "john.doe@example.com",
                          "phone": "654111654",
                          "firstName": "John",
                          "lastName": "Doe",
                          "language": "pl"
                      },
                      "settings":{
                          "invoiceDisabled":"true"
                      },
                      "products": [
                          {
                              "name": "Wireless Mouse for Laptop",
                              "unitPrice": "15000",
                              "quantity": "1"
                          },
                          {
                              "name": "HDMI cable",
                              "unitPrice": "6000",
                              "quantity": "1"
                          }
                      ]
                  }'
            

                        curl -X POST https://secure.snd.payu.com/api/v2_1/orders \
                        -H "Content-Type: application/json" \
                        -H "Authorization: Bearer d9a4536e-62ba-4f60-8017-6053211d3f47" \
                        -d '{
                            "notifyUrl": "https://your.eshop.com/notify",
                            "customerIp": "127.0.0.1",
                            "merchantPosId": "300746",
                            "description": "RTV market",
                            "currencyCode": "PLN",
                            "totalAmount": "21000",
                            "buyer": {
                                "email": "john.doe@example.com",
                                "phone": "654111654",
                                "firstName": "John",
                                "lastName": "Doe",
                                "language": "pl"
                            },
                            "settings":{
                                "invoiceDisabled":"true"
                            },
                            "products": [
                                {
                                    "name": "Wireless Mouse for Laptop",
                                    "unitPrice": "15000",
                                    "quantity": "1"
                                },
                                {
                                    "name": "HDMI cable",
                                    "unitPrice": "6000",
                                    "quantity": "1"
                                }
                            ]
                        }'
                    

apiary

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}",
}
         
Odpowiedź zwraca kod HTTP 302 oraz nagłówek Location ustawiony na redirectUri. Może być to powodem automatycznych przekierowań.

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.

2.2 Integracja formularza zamówienia

Sekcja zawiera minimalny przykład formularza umożliwiający kupującemu dokonanie płatności. Integracja poprzez formularz nie jest zalecana i prezentowana jedynie w celach informacyjnych dla istniejących implementacji.
                <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.

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

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

3 Powiadomienia

Każda płatność w systemie PayU podlega cyklowi życia. Poszczególne etapy cyklu życia związane są z konkretnymi sytuacjami takimi jak: przyjęcie, rozliczenie, odrzucenie itd. PayU oferuje mechanizmy, które powiadamiają system sprzedawcy o zmianie stanu płatności.

Aby uruchomić otrzymywanie powiadomień dla konkretnej płatności, należy uzupełnić parametr notifyUrl w formularzu 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. Oznacza to, ze możliwa jest sytuacja, gdy po otrzymaniu informacji o przejściu zamówienia w status COMPLETED lub CANCELED zostanie wysłana informacja o statusie PENDING. W takim przypadku należy zignorować wszystkie komunikaty otrzymane po wiadomości o statusie COMPLETED.

Po wysłaniu notyfikacji system PayU oczekuje wyłącznie HTTP status 200 od klienta. W przypadku każdego innego statusu nastąpi ponowne wysłanie notyfikacji.

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 oraz REJECTED.

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.

Status Opis
PENDING Płatność jest w trakcie rozliczenia.
WAITING_FOR_CONFIRMATION system PayU oczekuje na akcje ze strony sprzedawcy w celu wykonania płatności. Ten status występuje w przypadku gdy auto-odbiór na POSie sprzedawcy jest wyłączony.
COMPLETED Płatność została zaakceptowana w całości. Środki są dostępne do wypłaty.
CANCELED Płatność została anulowana. Płacący nie został obciążony (nie nastąpił przepływ środków między płacącym a Payu).
REJECTED Płatność została odrzucona, ale płacący został obciążony (nastąpił przepływ środków między płacącym a Payu). Taką płatność można odebrać (środki zostaną przekazane do sklepu) lub anulować (środki zostaną zwrocone płacącemu).

3.1 Status zamówienia

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

              OpenPayu-Signature: sender=checkout;signature=b1000189a1ddeafb3cfb4b35d2c35a3d;algorithm=MD5;content=DOCUMENT
              X-OpenPayU-Signature: sender=checkout;signature=b1000189a1ddeafb3cfb4b35d2c35a3d;algorithm=MD5;content=DOCUMENT
              PayU-Processing-Time: 1000
           

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

3.2 Status zwrotu

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

4 Zwroty

Płatności procesowane przez system PayU umożliwiają wykonanie zwrotu środków na konto kupującego (tzw. refund).

Żądanie zwrotu środków do kupującego może być wykonane w dwóch trybach: pełne lub częściowe. Dla zwrotów częściowych należy podać kwotę, która jest wyrażona w najmniejszych jednostkach monetarnych dla danej waluty. Natomiast sama waluta zgodna jest z pierwotnym zamówieniem.

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 zamówienia. Ponadto system PayU dopuszcza wysłanie żądania o zwrot częściowy raz na minutę.

Aby zrealizować zwrot środków na konto kupującego wywołaj usługę /api/v2_1/orders/{orderId}/refunds przy użyciu metody POST. Przykłady takiego wywołania zaprezentowano poniżej

Przykład żądania o pełen zwrot:

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"
  }
}'
            
Metody uwierzytelnienia znajdują się w: Uwierzytelnienie użytkownika API

Przykład żądania o zwrot częściowy

Przykład prezentuje 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: Uwierzytelnienie użytkownika API

Przyjęcie żądania przez system PayU zostanie potwierdzone odpowiedzią zawierającą odpowiedni status (opis .

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 niemożności utworzenia zwrotu, pole status w odpowiedzi będzie zawierać opis problemu. Znaczenie poszczególnych pól przedstawia tabela poniżej:

StatusCode Code CodeLiteral Opis
OPENPAYU_BUSINESS_​ERROR TRANS_NOT_​ENDED 9101 Transakcja nie jest zakończona.
OPENPAYU_BUSINESS_​ERROR NO_BALANCE 9102 Brak środków na koncie do zwrotu.
OPENPAYU_ERROR_VALUE_​INVALID AMOUNT_TO_​BIG 9103 Za duża wartość.
OPENPAYU_ERROR_VALUE_​INVALID AMOUNT_TO_​SMALL 9104 Za mała wartość.
OPENPAYU_BUSINESS_​ERROR REFUND_​DISABLED 9105 Zwroty są nieaktywne.
OPENPAYU_BUSINESS_​ERROR REFUND_TO_​OFTEN 9106 Za częsty zwrot.
OPENPAYU_ERROR_VALUE_​INVALID PAID 9108 Zwrot już został wykonany.
OPENPAYU_ERROR_​INTERNAL UNKNOWN_​ERROR 9111 Nieznany błąd.
OPENPAYU_BUSINESS_​ERROR REFUND_IDEMPOTENCY_MISMATCH 9112 Użyto ponownie tę samą wartość parametru extRefundId, ale inne parametry żądania się różnią.
OPENPAYU_BUSINESS_​ERROR TRANS_BILLING_​ENTRIES_NOT_COMPLETED 9113 Billing sklepu nie jest jeszcze kompletny.

5 Anulowanie

Zamówienie procesowane przez PayU może zostać anulowane (odrzucone), np. w przypadku braku możliwości dostarczenia towaru lub usługi. (tzw. cancel).

Żą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.

Aby skutecznie zwrócić środki do płacącego, w przypadku zamówienia w statusie WAITING_FOR_CONFIRMATION należy wykonać dwa żądania DELETE.

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

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

6 Odebranie zamówienia

Zamówienia w statusie WAITING_FOR_CONFIRMATION lub REJECTED można odebrać bądź anulować (zob. Anulowanie). Niewykonanie żadnej z tych akcji skutkuje autoanulowaniem zamówienia. Autoanulowanie następuje po czasie wskazanym dla danej metody płatności.

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"
}'
            
Metody uwierzytelnienia znajdują się w: Uwierzytelnienie użytkownika API

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

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

7 Pobieranie danych zamówienia i transakcji

Można pobrać dane zamówień i transakcji (płatności) używając poniższych żądań.

7.1 Pobranie danych zamówienia

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

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

7.2 Pobranie danych transakcji

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

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": "CARD", 
      // także MASTERPASS, VISA_CHECKOUT, ONE_CLICK_CARD, ONE_CLICK_CARD_RECURRING etc.
      "card": {
        "cardData": {
          "cardNumberMasked": "543402******4014",
          "cardScheme": "MC", //MC (MasterCard/Maestro), VS (Visa)
          "cardProfile": "CONSUMER", // CONSUMER lub BUSINESS
          "cardClassification": "DEBIT", //DEBIT lub CREDIT
          "cardResponseCode":"000", //szczegóły opisano poniżej 
          "cardResponseCodeDesc":"000 - OK", //szczegóły opisano poniżej
          "cardEciCode":"5", //szczegóły opisano poniżej
          "card3DsStatus":"AY", //szczegóły opisano poniżej
          "cardBinCountry":"PL"
        }
      }
    }
  ]
}
                

Sprawdź Statusy dla kart, aby dowiedzieć się więcej o statusach tranksacji kartowych.

Przykład odpowiedzi po pobraniu informacji o transakcji pay-by-linkiem:

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

8 Transparentna integracja

Transparentna (white label) integracja polega na umieszczeniu ikonek metod płatności wprost na stronie sklepu i tworzenie zamówień w systemie PayU ze z góry określoną metodą płatności.
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.

Na przykład:
                    {
                        "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": [] 
                            }
                        }
                    }
                    

Uwaga: dla metody "blik" możliwe jest zarówno przekierowanie na stronę BLIK lub pobrania 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.

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

8.1 Pobranie metod płatności

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

.

apiary

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

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

payByLinks

payByLinks to metody płatności, które zawsze wymagają przekierowania poza stronę sklepu.
Parametr Opis
value Oznaczenie typu płatności. Dostępne wartości są tutaj.
name Nazwa (opis) typu płatności.
brandImageUrl Odnośnik do pliku graficznego na serwerze PayU reprezentującego typ płatności.
status Możliwe wartości: 'ENABLED', 'DISABLED', 'TEMPORARY_DISABLED'.

8.2 Obowiązki informacyjne

Transparentna integracja wiąże się z obowiązkami informacyjnymi.

Należy umieścić poniższy tekst i odnośnik na stronie sklepu, aby płacący był świadomy, że operatorem płatności jest PayU.

Poniższa informacja powinna zostać wyświetlona tylko w przypadku jeśli sprzedaż skierowana jest do konsumentów z Czech lub Polski. Jeśli sprzedaż jest skierowana do konsumentów z innych krajów UE (np. Niemcy, Węgry itd.), nie ma obowiązku wyświetlania poniższych informacji.

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.

[tutaj należy wstawić checkbox] Akceptuję "Regulamin pojedynczej transakcji płatniczej PayU".

Administratorem Twoich danych osobowych w rozumieniu ustawy z dnia 29 sierpnia 1997 r. o ochronie danych osobowych (tj. Dz.U. z 2002 roku, nr 101, poz. 926 z późn. zm.) jest PayU SA z siedzibą w Poznaniu (60-166), przy ul. Grunwaldzkiej 182. Twoje dane osobowe będą przetwarzane zgodnie z obowiązującymi przepisami prawa, w celu świadczenia usług i archiwizacji. Twoje dane nie będą udostępniane innym podmiotom, z wyjątkiem podmiotów upoważnionych na podstawie przepisów prawa. Przysługuje Tobie prawo dostępu do treści swoich danych oraz ich poprawiania. Podanie danych jest dobrowolne, ale niezbędne do realizacji ww. celu.

Checkbox może być od razu zaznaczony. Jego odznaczenie oznacza, że płacący nie może dokonać płatności. Należy wówczas wyświetlić komunikat

Należy zaakceptować "Regulamin pojedynczej transakcji płatniczej PayU"

Dostępne wersje językowe powyższych informacji znajdują się tutaj.

8.3 Formatka kartowa

Istnieje kilka wariantów akceptacji kart płatniczych poprzez system PayU.

Formularz hostowany przez PayU

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 przekierowujący do strony płatności kartą.

Ważne: w celu zwiększenia konwersji, formularz ma następujące funkcjonalności:
  • 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).
  • automatyczne wykrywanie wersji językowej na podstawie ustawień przeglądarki płatnika spośród dostępnych wersji językowych. Domyślnym językiem (użytym jeśli PayU nie obsługuje danego języka) jest angielski.

Opcją bardziej zaawansowaną jest użycie widgeta hostowanego przez PayU lub budowa własnego formularza.

Widget

Szczegóły integracji i przykład widgeta znajdują się tutaj:

  1. widget wlewany
  2. widget nad stroną

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

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

Uwaga: widget wymaga dodatkowej konfiguracji (tokenizacja musi być włączona dla danego POSa). Dlatego przed przystąpieniem do integracji należy skontaktować się z opiekunem handlowym w PayU.

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 widget należy wysłać do PayU w obiekcie payMethods.

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

Uwaga: własny formularz wymaga dodatkowej konfiguracji (tokenizacja musi być włączona dla danego POSa). Dlatego przed przystąpieniem do integracji należy skontaktować się z opiekunem handlowym w PayU.

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.

9 Referencje

9.1 Uwierzytelnienie użytkownika API

Możliwe są dwie metody uwierzytelnienia: OAuth oraz HTTP Basic. Metodą rekomendowaną jest OAuth.

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 komunikacji tokenowej (PayU | Express).

Przykład requesta pobierającego token w trybie client_credentials:

                    curl -X POST https://secure.payu.com/pl/standard/user/oauth/authorize \
                    -d 'grant_type=client_credentials&client_id=145227&client_secret=12f071174cb7eb79d4aac5bc2f07563f'
                

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

apiary

HTTP Basic

Metoda HTTP Basic jest niezalecana.

W przypadku konieczności otrzymania specyfikacji użycia tej metody prosimy o kontakt z tech@payu.pl.

9.2 Podpisywanie parametrów formularza

Dla zapewnienia integralności danych, parametry zamówienia są podpisywane w polu OpenPayu-Signature. Struktura pola:
signature=...;algorithm=...;sender=...
Kolejność składowych nie jest istotna.
Znaczenie poszczególnych składowych:
  • signature - zawiera podpis wygenerowany zgodnie z algorytmem,
  • algorithm - określa funkcję skrótu wykorzystaną do wygenerowania podpisu,
  • sender - identyfikator POSa.
Element formularza zawierający przykładowy podpis:
<input name="OpenPayu-Signature" value="sender=145227;algorithm=SHA-256;signature=565f9f4dda43c8e24ccab4472133d680e2aa58e1f58bea845c4cf2926965144d">

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

Przykładowe wartości formularza do podpisu:
                    <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">                
Posortowanie wszystkich pól formularza alfabetycznie według nazw parametrów oraz dokonanie konkatenacji kluczy i wartości wszystkich pól formularza zgodnie z wcześniej wyznaczonym porządkiem (klucz=wartość), rozdzielając je znakiem ampersand & z dodanym na końcu swoim kluczem prywatnym (widocznym w Panelu Managera jako Drugi klucz (MD5)):
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
Powyższa wartość jest użyta do podpisu za pomocą funkcji skrótu SHA-256:
565f9f4dda43c8e24ccab4472133d680e2aa58e1f58bea845c4cf2926965144d                
Element formularza zawierający wygenerowany podpis:
<input name="OpenPayu-Signature" value="sender=145227;algorithm=SHA-256;signature=565f9f4dda43c8e24ccab4472133d680e2aa58e1f58bea845c4cf2926965144d">

W przypadku pytań prosimy o kontakt z zespołem wsparcia IT: tech@payu.pl.

9.3 Weryfikacja podpisu notyfikacji

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
     }
                        

9.4 Parametry komunikatów JSON

Poniżej znajdują się opisy pól w komunikatach wchodzących w skład REST API.

Parametry do wykorzystania w komunikacie OrderCreateRequest

Opis możliwych do wykorzystania pól:

Rekord Opis Wymagany
extOrderId Identyfikator zamówienia w systemie sprzedawcy Nie
notifyUrl Adres pod który będą przesyłane powiadomienia Tak
customerIp IP kupującego 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. Nie
description Opis zamówienia Tak
additionalDescription Dodatkowy opis zamówienia Nie
currencyCode Symbol waluty używanej przez sklep w standardzie ISO 4217, np. "PLN". Tak
totalAmount Całkowity koszt zamówienia Tak
continueUrl Adres na który kupujący zostanie przekierowany po zakończeniu procesu płatności. W przypadku braku autoryzacji do URL'a doklejany jest parametr error=501. Adres powrotu do Sklepu ma tylko charakter informacyjny, nie można na jego podstawie podejmować żadnych decyzji. Nie
settings Sekcja zawiera 1 pole: "invoiceDisabled". Pole przyjmujące wartości z zakresu {true, false}. Ustawienie wartości true umożliwia usunięcie przełącznika "Chcę otrzymać fakturę" ze strony podsumowania płatności. Nie
buyer Sekcja przechowująca dane kupującego.
Opis pól sekcji <buyer>
Nie
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

OrderCreateResponse - opis pól komunikatu

Rekord Opis
redirectUri Adres pod który należy przekierować kupującego
orderId Identyfikator zamówienia nadany przez system PayU
extOrderId Zewnętrzny identyfikator zamówienia (nadawany przez sklep)
status Obiekt typu status odpowiedzi.
Opis pól sekcji <status>.

Powiadomienia - opis pól komunikatu

Rekord Opis
order Sekcja przechowująca obiekt typu <order>.
Opis pól obiektu typu <order>

OrderStatusUpdateRequest - opis pól komunikatu

Rekord Opis Wymagany
orderId Identyfikator zamówienia w systemie PayU Tak
orderStatus Nowy status zamówienia. Możliwa wartość: COMPLETED Tak

OrderStatusUpdateResponse - opis pól komunikatu

Rekord Opis
status Obiekt typu status odpowiedzi.
Opis pól sekcji <status>.

RefundCreateRequest - opis pól komunikatu

Rekord Opis Wymagany
orderId Identyfikator zamówienia dla którego będzie realizowany zwrot Tak
refund Element typu RefundInfoType, zawierający szczegółowe dane na temat uznania Tak

Opis RefundInfoType

Rekord Opis Wymagany w obrębie typu
description Opis wykonywanego uznania Tak
amount Kwota uznania. Jeśli zostanie pusta, zostanie wykonany zwrot całości zapłaconych środków Nie
extRefundId Identyfikator zwrotu w systemie klienta, unikalny w obrębie zamówienia Nie
bankDescription Tytuł przelewu bankowego Nie
type Typ operacji (możliwa wartość: REFUND_PAYMENT_STANDARD) Nie

RefundCreateResponse - opis pól komunikatu

Rekord Opis
orderId Identyfikator zamówienia dla którego będzie realizowany zwrot
refund Element typu <RefundRecord_Type>, zawierający szczegółowe dane na temat uznania
status Obiekt typu status odpowiedzi.
Opis pól sekcji <status>.

Opis pól <RefundRecord_Type>

Rekord Opis
refundId Identyfikator zwrotu
extRefundId Zewnetrzny identyfikator zwrotu nadany w komunikacie RefundCreateRequest
amount Kwota uznania
currencyCode Kod waluty (ISO 4217)
description Opis wykonywanego uznania
creationDateTime Data utworzenia zwrotu
status Kod statusu przetwarzania (PENDING, CANCELED, FINALIZED)
statusDateTime Data statusu

OrderCancelRequest - opis pól komunikatu

Rekord Opis Wymagany
orderId Identyfikator zamówienia dla którego będzie realizowany zwrot Tak

OrderCancelResponse - opis pól komunikatu

Rekord Opis
orderId Identyfikator zamówienia dla którego będzie realizowany zwrot
extOrderId Zewnętrzny identyfikator zamówienia (nadawany przez sklep)
status Obiekt typu status odpowiedzi.
Opis pól sekcji <status>.

OrderRetrieveRequest - opis pól komunikatu

Rekord Opis Wymagany
orderId Identyfikator zamówienia dla którego będzie realizowany zwrot Tak

OrderRetrieveResponse - opis pól komunikatu

Rekord Opis
order Sekcja przechowująca tablicę elementów typu <order>
Opis pól elementu typu <order>.
status Obiekt typu status odpowiedzi.
Opis pól sekcji <status>.

Sekcje wspólne

Opis pól obiektu typu <product>

Rekord Opis Wymagany w obrębie sekcji
name Nazwa Tak
unitPrice Cena jednostkowa Tak
quantity Liczba sztuk Tak
virtual Produkt może być wirtualny lub materialny; przyjmuje wartości true i false. Nie
listingDate (marketplace) Data wystawienia produktu, przykład: "2016-01-26T17:35:37+01:00" Nie

Opis pól obiektu typu <payMethod>

Rekord Opis Wymagany w obrębie sekcji
type Typ metody płatności, możliwe wartości:
  • PBL (płatność wymaga przekierowania)
  • CARD_TOKEN
  • BANK_TOKEN
  • PAYMENT_WALL (płatność wymaga przekierowania)
Tak
value Symbol typu płatności dla PBL, CARD_TOKEN, BANK_TOKEN. Tak/Nie (nie wymagany dla PAYMENT_WALL)
authorizationCode Opcjonalny. Dla transparentnej integracji metody płatności BLIK: pozwala pobrać 6-cyfrowy kod na stronie sklepu bez przekierowania na stronę BLIK. Zobacz więcej o transparentnej integracji. Dla transparentnej integracji Visa Checkout: zawiera parametr callId. Zobacz więcej o Visa Checkout. Nie

<mcpData> fields description

Rekord Opis Wymagany w obrębie sekcji
mcpCurrency "termCurrency" z tabeli kursowej. tak
mcpAmount kwota w walucie bazowej ("baseCurrency") przeliczona do "termCurrency". tak
mcpRate Użyty kurs przewalutowania. tak
mcpFxTableId Id użytej tabeli kursowej. tak
mcpPartnerId Identyfikator przekazany przez PayU. tak

Opis pól sekcji <buyer>

Rekord Opis Wymagany w obrębie sekcji
customerId Id kupującego Nie
extCustomerId Identyfikator kupującego używany w systemie klienta Nie
email Adres email kupującego Tak
phone Numer telefonu Nie
firstName Imię kupującego Nie
lastName Nazwisko kupującego Nie
nin PESEL lub zagraniczny ekwiwalent Nie
language Język kupującego. Określa język strony płatniczej - dostępne parametry są tutaj Nie
buyer.delivery Sekcja zawierająca dane adresowe do wysyłki towaru
Opis pól sekcji <buyer.delivery>
Nie

Opis pól w sekcji <buyerDelivery>

Rekord Opis Wymagany w obrębie sekcji
street Ulica Tak
postalBox Skrytka pocztowa Nie
postalCode Kod pocztowy Tak
city Miasto Tak
state Województwo Nie
countryCode Kod kraju Tak
name Nazwa adresu Nie
recipientName Nazwisko adresata Tak
recipientEmail Adres email adresata Nie
recipientPhone Numer telefonu adresata Nie

Opis pól w sekcji <order>

Rekord Opis
orderId Identyfikator zamówienia nadany przez system PayU
extOrderId Zewnętrzny identyfikator zamówienia (nadawany przez sklep)
orderCreateDate Znacznik czasu dla utworzenia zamówienia
notifyUrl Adres pod który będą przesyłane powiadomienia
orderUrl URL zamówienia na stronie sklepu
customerIp IP kupującego
merchantPosId Identyfikator punktu płatności na którym zostanie wykonana płatność
validityTime Czas w trakcie którego możliwe jest dokończenie zamówienia w sekundach
description Opis wykonywanego uznania
additionalDescription Dodatkowy opis zamówienia
currencyCode Symbol waluty używanej przez sklep w standardzie ISO 4217, np. "PLN".
totalAmount Całkowity koszt zamówienia
status Status zamówienia
buyer Sekcja przechowująca dane kupującego.
Opis pól sekcji <buyer>
products Sekcja zawiera dane o produktach. Sekcja <products> jest tablicą obiektów typu <product>.
Opis pól obiektu typu <product>

Opis pól w sekcji <status>

Rekord Opis
statusCode Kod odpowiedzi
statusDesc Opis statusu odpowiedzi

9.5 Parametry formularza

Poniższa tabela przedstawia wszystkie wymagane i opcjonalne parametry, które mogą być użyte w formularzu zamówienia.

Parametry ogólne

Parametr Wymagany Opis
customerIp Tak Adres IP Kupującego, np. "123.123.123.123".
extOrderId Nie 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.
merchantPosId Tak Identyfikator POSa.
description Tak Opis zamówienia.
additionalDescription Nie Dodatkowy opis zamówienia.
currencyCode Tak Waluta zamówienia w standardzie ISO 4217, np. "PLN".
totalAmount Tak Całkowita wartość zamówienia podana 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.
OpenPayu-Signature Tak Podpis parametrów. Więcej informacji w rozdziałach 7.1 i 7.2

Adresy URL

Parametr Wymagany Opis
continueUrl Nie Adres na który kupujący zostanie przekierowany po zakończeniu procesu płatności. W przypadku braku autoryzacji do URL'a doklejany jest parametr error=501. Adres powrotu do Sklepu ma tylko charakter informacyjny, nie można na jego podstawie podejmować żadnych decyzji.
notifyUrl Nie Adres URL, na który przychodzić będą powiadomienia o zmianie statusu zamówienia lub zwrotu.

Kupujący

Sekcja buyer opisuje dane Kupującego. Nie jest wymagana.

Parametr Wymagany Opis
buyer.email Tak Adres e-mail Kupującego.
buyer.phone Nie Numer telefonu Kupującego.
buyer.firstName Tak Imię Kupującego.
buyer.lastName Tak Nazwisko Kupującego.
buyer.language Nie Język Kupującego. Określa język strony płatniczej - dostępne parametry są tutaj.

Adres do wysyłki

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

Parametr Wymagany Opis
buyer.delivery.street Tak Nazwa ulicy.
buyer.delivery.postalCode Tak Kod pocztowy.
buyer.delivery.city Tak Miejscowość.
buyer.delivery.countryCode Tak Dwuliterowy kod kraju zgodny z ISO-3166.
buyer.delivery.name Nie Opis adresu.
buyer.delivery.recipientName Nie Nazwa adresata.
buyer.delivery.recipientEmail Nie Adres e-mail adresata.
buyer.delivery.recipientPhone Nie Numer telefonu adresata.

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

Parametr Wymagany Opis
products[0].name Tak Nazwa produktu.
products[0].unitPrice Tak Cena jednostkowa produktu.
products[0].quantity Tak Liczba produktów.
products[0].virtual Nie Produkt może być wirtualny lub materialny; przyjmuje wartości true i false.
products[0].listingDate Nie (marketplace) Data wystawienia produktu, przykład: "2016-01-26T17:35:37+01:00"

9.6 Kody statusów

Poniższa tabela przedstawia kody statusów, które Sklep może otrzymać od PayU. Niektóre ze statusów mogą być opatrzone dodatkowymi komentarzami.
W przypadku kontaktu z PayU w związku z nieudanymi żądaniami, prosimy używać adresu tech@payu.pl oraz podać wartość Correlation-Id przekazaną jako nagłówek odpowiedzi.
Kody statusu
Kod HTTP statusu Kody statusu Opis
200 OK SUCCESS Żądanie zostało wykonane poprawnie.
201 OK SUCCESS Poprawnie utworzono zamówienie z użyciem tokena kartowego lub kodu BLIK w sekcji payMethods.
302 Found SUCCESS Żądanie wykonano poprawnie. Parametr redirectUri został przekazany w nagłówku Location i w treści odpowiedzi w formacie JSON.
302 Found WARNING_CONTINUE_REDIRECT Żądanie wykonano poprawnie. Parametr redirectUri został przekazany w nagłówku Location i w treści odpowiedzi w formacie JSON. Dotyczy transparentnej integracji z użyciem sekcji payMethods i zamówienia z użyciem metod płatności: orx, bnx, gbx, nlx.
302 Found WARNING_CONTINUE_3DS Wymagana autoryzacja 3DS. Należy wykonać przekierowanie w celu kontynuacji procesu płatności (można skorzystać z metody OpenPayU.authorize3DS()).
302 Found WARNING_CONTINUE_CVV Wymagane podanie kod CVV2/CVC2. Wywołaj metodę OpenPayU.authorizeCVV() opisaną tutaj.
400 Bad request ERROR_SYNTAX Błędna składnia żądania.
400 Bad request ERROR_VALUE_INVALID Jedna lub więcej wartości jest nieprawidłowa.
400 Bad request ERROR_VALUE_MISSING Brakuje jednej lub więcej wartości.
400 Bad request ERROR_ORDER_NOT_UNIQUE Zamówienie już zostało utworzone. Ten błąd może występować w sytuacji w której podano nieunikalny parametrextOrderId.
401 Unauthorized UNAUTHORIZED Błędne uwierzytelnienie. Należy sprawdzić parametry podpisu i prawidłowość wdrożenia algorytmu podpisu.
403 Forbidden UNAUTHORIZED_REQUEST Brak uprawnień do wykonania żądania.
404 Not found DATA_NOT_FOUND W systemie PayU brak danych, które wskazano w żądaniu.
408 Request timeout TIMEOUT Upłynął okres ważności dla realizacji żądania.
500 Internal server error BUSINESS_ERROR System PayU jest niedostępny. Spróbuj ponownie później.
500 Internal server error ERROR_INTERNAL System PayU jest niedostępny. Spróbuj ponownie później.
500 Internal server error GENERAL_ERROR Wystąpił niespodziewany błąd. Spróbuj ponownie później.
500 Internal server error WARNING Wystąpił drobny niespodziewany błąd. Spróbuj ponownie później.
503 Service unavailable SERVICE_NOT_AVAILABLE System PayU jest niedostępny. Spróbuj ponownie później.

9.7 Wersje językowe

Poniższe tabele przedstawiają parametry językowe, które mogą być użyte zarówno w formularzu zamówienia, jak i poprzez API.

Ogólne parametry językowe

Mogą być użyte do określenia języka strony wyboru metod płatności (tj. w sytuacji, kiedy podczas tworzenia zamówienia nie została jeszcze zdefiniowana metoda płatności).

Wartość Język
pl polski
en angielski
cs czeski

Dostępne języki formularza płatności kartą

Poniższe wersje językowe są dostępne na formularzu hostowanym przez PayU. Wersja językowa wykrywana jest automatycznie na podstawie ustawień przeglądarki płatnika. Domyślnym językiem (użytym jeśli PayU nie obsługuje danego języka) jest angielski.

Wartość Język strony płatności kartą
bg bułgarski
de niemiecki
ee estoński
el grecki
es hiszpański
fi fiński
fr francuski
hr chorwacki
hu węgierski
it włoski
lt litewski
lv łotewski
pt portugalski
ro rumuński
ru rosyjski
sk słowacki
sl słoweński
uk ukraiński

Informacje o PayU

Język Informacja Tekst
cs Zlecenie płatności Platební přikaz PayU SA: Službu poskytuje PayU SA; data příjemce, titul platby a sumu poskytuje PayU SA příjemce; přikaz je odeslán ke zapracování, když PayU SA obdrží platbu; platba je k dispozici příjemci během 1 holdiny, nejpozději do konce dalšího pracovního dne; PayU SA si neúčtuje žádný související poplatek za služby.
cs Regulamin pojedynczej transakcji Přijímám "Podmínky pro provedení jednorázové platební transakce v PayU".
cs Ochrona danych osobowych Správcem vašich osobních údajů ve smyslu Zákona o ochraně osobních údajů ze dne 29. srpna 1997 (Sbírka zákonů 2002, č. 101, položka 926, ve znění pozdějších úprav) je PayU SA se sídlem registrovaným na adrese Grunwaldzka 182, Poznaň (60-166), Polsko. Vaše osobní údaje budou zpracovány a archivovány v souladu s příslušnými ustanoveními uvedeného zákona. Vaše údaje nebudou zpřístupněny třetím osobám, s výjimkou osob k tomu autorizovaných zákonem. Máte právo k vašim údajům přistupovat a upravovat je. Poskytnutí údajů je dobrovolné, ale je požadováno k účelům uvedeným výše.
pl Zlecenie płatności 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.
pl Regulamin pojedynczej transakcji Akceptuję "Regulamin pojedynczej transakcji płatniczej PayU".
pl Ochrona danych osobowych Administratorem Twoich danych osobowych w rozumieniu ustawy z dnia 29 sierpnia 1997 r. o ochronie danych osobowych (tj. Dz.U. z 2002 roku, nr 101, poz. 926 z późn. zm.) jest PayU SA z siedzibą w Poznaniu (60-166), przy ul. Grunwaldzkiej 182. Twoje dane osobowe będą przetwarzane zgodnie z obowiązującymi przepisami prawa, w celu świadczenia usług i archiwizacji. Twoje dane nie będą udostępniane innym podmiotom, z wyjątkiem podmiotów upoważnionych na podstawie przepisów prawa. Przysługuje Tobie prawo dostępu do treści swoich danych oraz ich poprawiania. Podanie danych jest dobrowolne, ale niezbędne do realizacji ww. celu.

9.8 Statusy dla kart

Lista statusów transakcji kartowych odsyłana przez PayU, kody 3-D Secure.
Statusy transakcji kartowych:
CardResponseCode CardResponseCodeDesc Powód(*) Informacje dodatkowe
000 000 - OK
S01 S01 - Refer to card issuer Bank
S04 S04 - Pickup card Bank
S05 S05 - Do not honor Bank Poproś Płacącego, żeby skontaktował się ze swoim bankiem i rozwiązał przyczynę(y) odrzucenia transakcji.
S12 S12 - Invalid transaction Bank
S13 S13 - Invalid amount Bank Prawdopodobnie limit pojedynczej transakcji po stronie banku został przekroczony.
S30 S30 - Message format error Bank
S43 S43 - Pickup card (stolen card) Bank
S51 S51 - Insufficient funds Bank Brak środków lub próba przekroczenia limitów (po stronie banku).
S54 S54 - Expired card Bank Karta wygasła lub Płacący podał niepoprawne daty ważności karty.
S62 S62 - Restricted card / Country exclusion table Bank
S90 S90 - Destination not available Bank
S93 S93 - Card disabled for e-commerce transactions Bank
S99 S99 - authorization error – default Bank
SN0 SN0 - Unable to authorize / Force STIP Bank
SP9 SP9 - Enter lesser amount Bank
ST3 ST3 - Card not supported Bank
ST8 ST8 - Invalid account Bank
114 114 - 3ds authentication error Check 3ds status.
222 222 - Transaction not received by merchant Merchant Merchant nie odebrał transakcji; status możliwy jedynie przy wyłączonej opcji auto odbioru.
001, 002, 003, 004, 005, 110, 111, 112, 113, 121, 122, 221, 223 different messages PayU Prosimy skontaktować się z PayU w celu uzyskania szczegółów problemu.

(*) 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.

Kody odpowiedzi ECI (Electronic Commerce Indicator):
cardEciCode Informacje dodatkowe
0 Transakcja procesowana bez wywołania 3DS (MasterCard).
1 Próba autentykacji (MasterCard). Wydawca nie uczestniczy w weryfikacji lub karta nie kwalifikuje się do uwierzytelnienia.
2 Pełna autentykacja (MasterCard).
5 Pełna autentykacja.
6 Próba autentykacji. Wydawca karty nie uczestniczy w weryfikacji lub karta nie kwalifikuje się do uwierzytelnienia.
7 Transakcja procesowana bez wywołania 3DS.

Statusy 3Ds:
card3DsStatus Informacje dodatkowe
AY Rezultat obsługi 3DS: pozytywny.
AN Próba autentykacji. Wydawca karty nie uczestniczy w weryfikacji lub karta nie kwalifikuje się do uwierzytelnienia.
A0 Błąd po stronie organizacji kartowej.