Przejdź do głównej zawartości

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.

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'
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).
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"
}
]
}'
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 HTTPKod statusucodeLiteral/statusDescOpis
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_INVALID
codeLiteral: FEE_AMOUNT_PROVIDED_BUT_FEE_ ACCOUNT_NOT_CONFIGURED
Pole fee w obiektach tablicy shoppingCarts nie może być używane na punktach płatności, na których usługa Marketplace umożliwiająca dodanie prowizji nie jest dostępna.
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.