Uwierzytelnianie i tworzenie zamówienia

Uwierzytelnianie żądań

Aby komunikować się z serwerami PayU, musisz w nagłówku żądania umieścić wygenerowany token OAuth. Istnieją trzy rodzaje tokenów OAuth:

client_credentials dla standardowej integracji.
trusted_merchant używany do uwierzytelniania żądań dla zalogowanych użytkowników sklepu/aplikacji ze stałym extCustomerId.
partner używany do uwierzytelniania żądań wykonanych na poziomie firmy. Ten typ tokenu przeznaczony jest dla sprzedawców uczestniczących w programie parnterskim.

Aby wygenerować token OAuth, potrzebujesz client_id i client_secret, które można znaleźć w punkcie płatności (POS), w panelu menedżerskim.

Pamiętaj!

Bez nagłówka Content-Type: application/x-www-form-urlencoded zwrócony zostanie błąd 401

Generowanie tokena OAuth

Tokeny generujesz wysyłając żądanie POST na endpoint /pl/standard/user/oauth/authorize. Szczegóły dotyczące parametrów wymaganych dla każdego typu uwierzytelnienia możesz znaleźć w naszej referencji API.

client_credentials
trusted_merchant
partner

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

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

curl -X POST https://secure.snd.payu.com/pl/standard/user/oauth/authorize \
    -d 'grant_type=partner' \
    -d 'client_id=egmcvdo5' \
    -d 'client_secret=9e0cad643b2d4f0bc1fe1750b9b706ec' \
    -d 'firm_id=nZzFT4I5'

Notatka

Parametry wyróżnione w powyższych żądaniach, są specyficzne dla dangeo trybu tokena.

Jeśli chcesz dowiedzieć się więcej o typie partner i programie partnerskim odwiedź stronę: Program partnerski.

Po wysłaniu żądania uwierzytelnienia otrzymasz odpowiedź z podstawowymi danymi wygenerowanego tokena.

{
    "access_token": "3e5cac39-7e38-4139-8fd6-30adc06a61bd",
    "token_type": "bearer",
    "expires_in": 43199, //expiration time in seconds
    "grant_type": "client_credentials"
}

Powyżej wyróżniony został parametr access_token, którego wartością jest token uwierzytelniający. Token ten jest użyty w poniższym przykładzie, w nagłówku Authorization, do uwierzytelnienia dalszej komunikacji z systemem PayU:

Przykład żądania z wygenerowanym tokenem OAuth
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"
        }
    ]
}'

Tworzenie nowego zamówienia

Aby utworzyć nowe zamówienie, wyślij żądanie przy użyciu metody POST na endpoint /api/v2_1/orders, na jeden z dostępnych adresów url:

https://secure.payu.com - (środowisko produkcyjne) - jeżeli jest to faktyczne zamówienie z przemieszczeniem realnych funduszy.
https://secure.snd.payu.com - (środowisko testowe) - jeżeli jest to testowe zamówienie wysłane na środowisku sandbox (więcej informacji na temat środowiska sandbox możesz znaleźć w sekcji Testowanie).

Produkcja
Sandbox

Przykład standardowego żądania na środowisku produkcyjnym
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",
        "extOrderId":"2uikc6gjd99b4lxc75ip4k",
        "buyer": {
            "email": "john.doe@example.com",
            "phone": "654111654",
            "firstName": "John",
            "lastName": "Doe",
            "language": "pl"
        },
        "products": [
            {
                "name": "Wireless Mouse for Laptop",
                "unitPrice": "15000",
                "quantity": "1"
            },
            {
                "name": "HDMI cable",
                "unitPrice": "6000",
                "quantity": "1"
            }
        ]
    }'

Przykład standardowego żądania na środowisku sandbox
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",
        "extOrderId":"2uikc6gjd99b4lxc75ip4k",
        "buyer": {
            "email": "john.doe@example.com",
            "phone": "654111654",
            "firstName": "John",
            "lastName": "Doe",
            "language": "pl"
        },
        "products": [
            {
                "name": "Wireless Mouse for Laptop",
                "unitPrice": "15000",
                "quantity": "1"
            },
            {
                "name": "HDMI cable",
                "unitPrice": "6000",
                "quantity": "1"
            }
        ]
    }'

Notatka

Wszystkie kwoty należy podawać w najmniejszej jednostce walutowej np. najniższą jednostką walutową dla PLN jest grosz (1/100PLN), więc 1000 jest równe 10PLN. HUF jest wyjątkiem - należy go pomnożyć przez 100.
Jeśli jest uwzględniony, parametr extOrderId musi być unikalny w zakresie punktu sprzedaży (POS).

Szczegółowe informacje na temat parametrów znajdziesz w sekcji Create an Order w naszej referencji API.

Przykład odpowiedzi

Notatka

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.

Po wysłaniu żądania nowego zamówienia, API zwróci odpowiedź z jego statusem i podstawowymi informacjami opisującymi zamówienie, w tym z adresem url, na który musisz przekierować kupujacego.

Odpowiedź na żądanie utworzenia nowego zamówienia
{
    "status": {
        "statusCode": "SUCCESS"
    },
    "redirectUri": "{payment_summary_redirection_url}",
    "orderId": "WZHF5FFDRJ140731GUEST000P01",
    "extOrderId": "{YOUR_EXT_ORDER_ID}"
}

Szczegółowe informacje na temat parametrów znajdziesz w sekcji Create an Order w naszej referencji API.

Notatka

Proces przekierowania pozwala zdefiniować język strony płatniczej PayU, na którą zostanie przekierowany płatnik. Aby ustawić język strony zalecamy użycie wartości parametru language w sekcji buyer (zobacz nasze API Reference). Inną opcją jest zmodyfikowanie redirectUri dodając do niego parametr lang, jak pokazano poniżej:

{redirectUri from the order response}&lang=en

Jeżeli żaden z podanych języków nie jest wspierany, użyty zostanie język angielski. Listę dostępnych języków najdziesz w sekcji Dostępne języki.

Wartość parametrów sessionId i merchantPosId jest ustawiana przez system PayU.

Pobieranie danych zamówienia

Ciało żądania metody GET

Wysyłając żądania z metodą GET upewnij się, że w ciele żądania nie przesyłasz żadnych danych. Zgodnie ze standardem RFC 9110 żądania, które nie spełniają tego wymogu, zostaną odrzucone przez PayU i zwrócony zostanie kod HTTP 403.

Dane zamówienia możesz pobrać wysyłając żądanie GET na endpoint api/v2_1/orders/{orderId}. W odpowiedzi otrzymasz obiekt z danymi dla określonego orderId.

Przykład żądania pobrania danych zamówienia
curl -X GET https://secure.payu.com/api/v2_1/orders/{orderId} \
-H "Content-Type: application/json" \
-H "Authorization: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd" \

Przykład odpowiedzi na żądanie pobrania danych zamówienia
{
    "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"
        }
    ]
}

Szczegółowe informacje na temat parametrów znajdziesz w sekcji Retrieve an Order w naszej referencji API.

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 o wysłanie zapytania z podaną wartością Correlation-Id przekazaną jako nagłówek odpowiedzi.

Kody statusów

Kod statusu HTTP	Kod statusu	codeLiteral/statusDesc	Opis
200 OK	SUCCESS		Żądanie zostało wykonane poprawnie.
201 Created	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(),/code>).`
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. Wspieranym formatem jest - JSON.
400 Bad request	ERROR_VALUE_INVALID		Jedna lub więcej wartości jest nieprawidłowa.
400 Bad request	ERROR_VALUE_INVALID	statusDesc: INVALID_BLIK_CODE	Kod autoryzacyjny BLIK powinien mieć 6 cyfr.
400 Bad request	ERROR_VALUE_INVALID	statusDesc: OPENPAYU_PAYMENT_CREATE_ BLOCKED_CHECKOUT_PAY_METHOD	Wybrana metoda płatności jest obecnie niedostępna. Dostępność metod płatności możesz sprawdzać korzystając z Pobrania metod płatności.
400 Bad request	ERROR_VALUE_INVALID	codeLiteral: SINGLE_CLICK_DISABLED	Usługa zapisu tokenów kartowych jest obecnie niedostępna.
400 Bad request	ERROR_VALUE_INVALID	codeLiteral: SINGLE_CLICK_ RECURRING_DISABLED	Płatności cykliczne są obecnie niedostępne.
400 Bad request	ERROR_VALUE_INVALID	statusDesc: General MCP processing error	Ogólny błąd usługi MCP.
400 Bad request	ERROR_VALUE_INVALID	statusDesc: Fx Rate Table is outdated	Tabela kursowa określona przez `mcpFxTableId` jest nieaktualna.
400 Bad request	ERROR_VALUE_INVALID	statusDesc: MCP is not supported for merchant	Usługa MCP jest niedostępna dla podanego sklepu.
400 Bad request	ERROR_VALUE_INVALID	statusDesc: Rate is null	Pole `mcpRate` jest puste.
400 Bad request	ERROR_VALUE_INVALID	statusDesc: Fx Table Id is null	Pole `mcpFxTableId` jest puste.
400 Bad request	ERROR_VALUE_INVALID	statusDesc: Amount is null	Pole `mcpAmount` jest puste.
400 Bad request	ERROR_VALUE_INVALID	statusDesc: Currency is null	Pole `mcpCurrency` jest puste.
400 Bad request	ERROR_VALUE_INVALID	statusDesc: Partner Id is null	Pole `mcpPartnerId` jest puste.
400 Bad request	ERROR_VALUE_INVALID	statusDesc: Invalid currency pair for given Fx Table	Nieprawidłowa para walutowa określona przez `mcpCurrency` i `currencyCode` dla podanej tabeli kursowej.
400 Bad request	ERROR_VALUE_INVALID	statusDesc: Invalid rate value for given Fx Table	Nieprawidłowy kurs określony przez `mcpRate` dla podanej tabeli kursowej.
400 Bad request	ERROR_VALUE_INVALID	statusDesc: Invalid amount value for given Fx Table (amount was not calculated properly)	Nieprawidłowa kwota określona przez `mcpAmount` dla podanej tabeli kursowej, kwota została wyliczona nieprawidłowo.
400 Bad request	ERROR_VALUE_INVALID	statusDesc: Currency is not supported	Waluta określona przez `mcpCurrency` nie jest obsługiwania w usłudze MCP.
400 Bad request	ERROR_VALUE_INVALID	statusDesc: Wrong params. You're trying to send MIT/Recurring request for non-verified first Payment	Próba płatności MIT/recurring tokenem, który nie został w pełni uwierzytelniony 3DSecure. Z danym tokenem, w zależności od typu płatności, należy najpierw wykonać płatność z odpowiednim parametrem: MIT (`cardOnFile=FIRST`), recurring (`recurring=FIRST`).
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 parametr `extOrderId`.
400 Bad request	ERROR_INTERNAL	codeLiteral: CARD_CARD_EXPIRED	Koniec ważności karty płatniczej.
400 Bad request	BUSINESS_ERROR	codeLiteral: ERROR_VALUE_INVALID statusDesc: Order was rejected by antifraud system	Zamówienie zostało odrzucone przez system zapobiegający oszustwom.
400 Bad request	ERROR_INCONSISTENT_CURRENCIES	statusDesc: Order and pos currencies are inconsistent	Sprawdź walutę przesyłaną w żądaniu.
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.
403 Forbidden	ERROR_VALUE_INVALID	codeLiteral: INVALID_AUTH_ FOR_THIS_ORDER	Niezgodność parametru POS ID w żądaniu OAauth z wartością parametru POS ID w żądaniu OrderCreateRequest. Wartości POS ID w obu żądaniach muszą być zgodne.
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.

Uwierzytelnianie żądań​

Generowanie tokena OAuth​

Tworzenie nowego zamówienia​

Przykład odpowiedzi​

Pobieranie danych zamówienia​

Kody statusów​

Na tej stronie

Uwierzytelnianie żądań

Generowanie tokena OAuth

Tworzenie nowego zamówienia

Przykład odpowiedzi

Pobieranie danych zamówienia

Kody statusów