Authorize and Order

At its core, sending the payment request comprises two simple steps. Firstly, obtaining an authentication token through OAuth, ensuring secure communication. Secondly, sending a payment request to the appropriate endpoint.

Authorizing the Request

When communicating with PayU servers, the first step is to authenticate using the OAuth standard to obtain a token. PayU offers three different grant types for OAuth tokens. These grant types are:

client_credentials for standard integration.
trusted_merchant used for authentication of requests made for logged-in shop/application users with fixed extCustomerId.
partner used for authentication of requests made on firm entity level, by merchants participating in the referral program.

To generate OAuth token, you will need client_id and client_secret, which can be found in any of your points of sale (POS), in your management panel.

Remember!

Without the Content-Type: application/x-www-form-urlencoded header, authentication request will return error 401.

Generating OAuth token

To generate tokens, send a POST request to the /pl/standard/user/oauth/authorize endpoint. You can find specific parameters required for each authorization type in Authorize section, in the PayU API Reference.

client_credentials
trusted_merchant
partner

Request Example for client_credentials Type
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'

Request Example for trusted_merchant Type
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>'

Request Example for partner Type
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'

Notes

Type-specific parameters are highlighted.

If you're interested in learning more about the partner type and the referral program, you can find additional information in the Referral Program section.

After sending authentication request you will receive response with basic data on the generated token.

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

Highlighted above is the access_token parameter, which is used in the Authorization header to authenticate further communication with the PayU system. Below you can see an example of access_token parameter used in the order request:

Order Example with OAuth access_token
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"
        }
    ]
}'

Creating a New Order

To create a new order, use the POST method to send an OrderCreateRequest to the https://secure.payu.com URL with the /api/v2_1/orders endpoint. If you want to send a request on the sandbox (test) environment, use the https://secure.snd.payu.com URL instead (you can find more information about sandbox in the Testing Your Integration section).

Production
Sandbox

Basic OrderCreateRequest Example on Production Environment
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"
            }
        ]
    }'

Basic OrderCreateRequest example on sandbox environment
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"
            }
        ]
    }'

Notes

Specify prices using the lowest currency unit. For instance, in the case of PLN (Polish Złoty), the lowest currency unit is the penny, which equals 1/100 PLN. Therefore, if the price is 1000 in the lowest currency unit, it would be equivalent to 10 PLN. However, HUF (Hungarian Forint) is an exception to this rule. For HUF, you should multiply the amount by 100.

If included in the order request, the extOrderId parameter must be unique within each point of sale (POS).

For details on parameters, please refer to Create an Order section in PayU API Reference.

Response Example

Notes

The HTTP status code of the response is 302 and Location header is set to redirectUri, which - depending on the software used - may sometimes trigger an automatic redirect as well as receiving responses in HTML format.

Once you submit a request, the API will swiftly respond with an OrderCreateResponse containing essential data about the created order. This response encompasses crucial details such as the order's status, unique orderId, and the redirectUri (which is used for the user redirection to the payment summary page).

Sample OrderCreateResponse
{
    "status": {
        "statusCode": "SUCCESS"
    },
    "redirectUri": "{payment_summary_redirection_url}",
    "orderId": "WZHF5FFDRJ140731GUEST000P01",
    "extOrderId": "{YOUR_EXT_ORDER_ID}"
}

For more details on possible status codes, please refer to the Status Codes section. For details on parameters and possible status codes, please refer to Create an Order section in our API Reference.

Notes

The redirect process allows you to define the language of a PayU webpage. To set the language of the page displayed after redirection, we recommend using the language parameter value in the buyer section (see our API Reference). You can also modify redirectUri adding as the query parameter lang:

{redirectUri from the order response}&lang=en

The value of sessionId and merchantPosId parameters are set by the PayU system.

For more information on the available lang values refer to the Languages section.

Retrieving Order Data

You can retrieve order data by sending GET request to the api/v2_1/orders/{orderId} endpoint. In response you will get an object with data for specified orderId.

GET Request Body

When making GET requests, please remember not to include any data in the request body, as specified in the RFC 9110 standard. Requests that do not adhere to this requirement will be rejected by PayU with an HTTP 403 status.

Request Example for Retrieving Order Data
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" \

Response Example for Retrieving Order Data
{
    "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"
        }
    ]
}

For details on parameters, please refer to Retrieve an Order section in the PayU API Reference.

Status Codes

Below is a list of status codes sent by the PayU system. Some status codes may be sent with a more detailed message.

If you need for PayU technical support to investigate an unsuccessful API call, please and provide the value of the Correlation-Id header returned in the response.

Status Codes

HTTP Status Code	Status Code	codeLiteral/statusDesc	Description
200 OK	SUCCESS		Request has been processed correctly.
201 Created	SUCCESS		Order with `payMethods` array with card token or BLIK auth code has been created.
302 Found	SUCCESS		Request has been processed correctly. `redirectUri` is provided in the response Location header and in the response body (in JSON payload).
302 Found	WARNING_CONTINUE_REDIRECT		Request has been processed correctly. `redirectUri` is provided in the response, in the `Location` header and in the response body (in JSON payload). Applies to transparent integration, if order request contains `payMethods` with following payment type values: orx, bnx, gbx, nlx.
302 Found	WARNING_CONTINUE_3DS		3DS authorization is required. Redirect the buyer to perform 3DS authentication process.
302 Found	WARNING_CONTINUE_CVV		CVV/CVC authorization required. Call the OpenPayU.authorizeCVV() method described here.
400 Bad request	ERROR_SYNTAX		Incorrect request syntax. Supported format is JSON.
400 Bad request	ERROR_VALUE_INVALID		One or more required values are incorrect.
400 Bad request	ERROR_VALUE_INVALID	statusDesc: INVALID_BLIK_CODE	BLIK authorization code must have 6 digits.
400 Bad request	ERROR_VALUE_INVALID	statusDesc: OPENPAYU_PAYMENT_CREATE_ BLOCKED_CHECKOUT_PAY_METHOD	Chosen payment method is currently unavailable. Payment methods availability can be checked by using Payment Methods Retrieval service.
400 Bad request	ERROR_VALUE_INVALID	codeLiteral: SINGLE_CLICK_DISABLED	Card token storing service is not available.
400 Bad request	ERROR_VALUE_INVALID	codeLiteral: SINGLE_CLICK_ RECURRING_DISABLED	Recurring payments service not available.
400 Bad request	ERROR_VALUE_INVALID	statusDesc: General MCP processing error	General MCP processing error.
400 Bad request	ERROR_VALUE_INVALID	statusDesc: Fx Rate Table is outdated	Fx Rate Table specified by `mcpFxTableId` is outdated.
400 Bad request	ERROR_VALUE_INVALID	statusDesc: MCP is not supported for merchant	MCP is not supported for merchant.
400 Bad request	ERROR_VALUE_INVALID	statusDesc: Rate is null	Field `mcpRate` is empty.
400 Bad request	ERROR_VALUE_INVALID	statusDesc: Fx Table Id is null	Field `mcpFxTableId` is empty.
400 Bad request	ERROR_VALUE_INVALID	statusDesc: Amount is null	Field `mcpAmount` is empty.
400 Bad request	ERROR_VALUE_INVALID	statusDesc: Currency is null	Field `mcpCurrency` is empty.
400 Bad request	ERROR_VALUE_INVALID	statusDesc: Partner Id is null	Field `mcpPartnerId` is empty.
400 Bad request	ERROR_VALUE_INVALID	statusDesc: Invalid currency pair for given Fx Table	Invalid currency pair specified by `mcpCurrency` and `currencyCode` for given Fx Table.
400 Bad request	ERROR_VALUE_INVALID	statusDesc: Invalid rate value for given Fx Table	Invalid rate value specified by `mcpRate` for given Fx Table.
400 Bad request	ERROR_VALUE_INVALID	statusDesc: Invalid amount value for given Fx Table (amount was not calculated properly)	Invalid amount value specified by `mcpAmount` for given Fx Table, amount was not calculated properly.
400 Bad request	ERROR_VALUE_INVALID	statusDesc: Currency is not supported	Currency specified by `mcpCurrency` is not supported.
400 Bad request	ERROR_VALUE_INVALID	statusDesc: Wrong params. You're trying to send MIT/Recurring request for non-verified first Payment	MIT/recurring payment attempt with a token that has not been fully authenticated with 3DSecure. With a given token, depending on the payment type, you must first make a payment with the appropriate parameter: MIT (`cardOnFile=FIRST`), recurring (`recurring=FIRST`).
400 Bad request	ERROR_VALUE_INVALID	codeLiteral: FEE_AMOUNT_PROVIDED_BUT_FEE_ ACCOUNT_NOT_CONFIGURED	The `fee` field in the objects within the `shoppingCarts` array cannot be used in points of sale at which the Marketplace service for adding a commission is not available.
400 Bad request	ERROR_VALUE_MISSING		One or more required values are missing.
400 Bad request	ERROR_ORDER_NOT_UNIQUE		Order already exists. This error may be caused by a not unique `extOrderId` parameter.
400 Bad request	ERROR_INTERNAL	codeLiteral: CARD_CARD_EXPIRED	Card expired.
400 Bad request	BUSINESS_ERROR	codeLiteral: ERROR_VALUE_INVALID statusDesc: Order was rejected by antifraud system	Order was rejected by antifraud system.
400 Bad request	ERROR_INCONSISTENT_CURRENCIES	statusDesc: Order and pos currencies are inconsistent	Please check currency passed in the order.
401 Unauthorized	UNAUTHORIZED		Incorrect authentication. Check signature parameters and implementation of the signature algorithm
403 Forbidden	UNAUTHORIZED_REQUEST		No privileges to perform the request
403 Forbidden	ERROR_VALUE_INVALID	codeLiteral: INVALID_AUTH_ FOR_THIS_ORDER	POS ID parameter in OAuth request does not match `posId` in OrderCreateRequest. Both values must be the same.
404 Not found	DATA_NOT_FOUND		Data indicated in the request is not available in the PayU system.
408 Request timeout	TIMEOUT		Permitted time to process the request has expired.
500 Internal server error	BUSINESS_ERROR		PayU system is unavailable. Try again later.
500 Internal server error	ERROR_INTERNAL		PayU system is unavailable. Try again later.
500 Internal server error	GENERAL_ERROR		Unexpected error. Try again later.
500 Internal server error	WARNING		Minor unexpected error. Try again later.
503 Service unavailable	SERVICE_NOT_AVAILABLE		PayU system is unavailable. Try again later.

Authorizing the Request​

Generating OAuth token​

Creating a New Order​

Response Example​

Retrieving Order Data​

Status Codes​

On this page

Authorizing the Request

Generating OAuth token

Creating a New Order

Response Example

Retrieving Order Data

Status Codes