REST API

Protocol version

This document describes integration with the REST API 2.1 protocol. It presents various methods of implementing online payments via different PayU services and is dedicated primarily to developers wanting to implement the PayU payment services.

For information on older versions of the API contact us.

Configuration and testing

Click here to find out how to configure Shop and POS in your PayU merchant account.

Before integrating with the PayU payment system, ensure the Point of Sale of type REST API (Checkout) is enabled for processing payments (you can check this in the Management Panel).

Testing guidelines and test POS details (sandbox and prod) are in the Testing section.

Service description

There are two stages to processing a payment via PayU:

1. Customer places an order on your webpage.
2. PayU confirms the payment has been processed successfully.

Stage 1: customer places an order.

The process is shown below:

1. The customer clicks on a button that is linked to the PayU payment service.
2. The PayU system presents an order summary webpage, where the buyer confirms the payment, then redirects the buyer to a bank website.
3. The buyer accepts the payment on the bank website. The buyer is redirected back to the PayU system.
4. The merchant system confirms the transaction was successful and thanks the buyer.

Stage 2: payment capture (optional).

1. The PayU system notifies the merchant system that the payment order status has changed as per its lifecycle.
2. The merchant system confirms receipt of the notification.

Current payment status is also available in the Management Panel.

For information on the supported authentication methods, see Signing API calls parameters.

To create a new order, use the POST method to send OrderCreateRequestto endpoint /api/v2_1/orders.

Note: specify prices using the lowest currency unit e.g. in lowest currency unit for PLN, so 1000 is equal to 10 PLN. HUF is the exception – multiply this by 100.

Note: 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.

The following is a basic sample order:

The following is a sample single-product order, with basic buyer data and an 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",
                   "language": "en"
                          },
                 "products": [
                     {
                         "name": "Wireless Mouse for Laptop",
                         "unitPrice": "15000",
                         "quantity": "1"
                    }
                 ]
              }'
            

Note: if included, the extOrderId must be unique within each point of sale (POS).

After sending a request for a new order, a response will be returned by the API. The following is an example of an OrderCreateResponse:

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

Check Status codes to learn more about possible response status codes.

The redirect process allows you to define the language of a PayU webpage by using the optional lang parameter.

To set the language of the page displayed after redirection, either use the lang parameter (see the section <buyer> for more information) or modify redirectUri:

{redirectUri from OrderCreateResponse}&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 section Language versions..

                 <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="Order description">
                    <input type="hidden" name="totalAmount" value="1000">
                    <input type="hidden" name="currencyCode" value="PLN">
                    <input type="hidden" name="products[0].name" value="Product 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" value="sender=145227;algorithm=SHA-256;signature=bc94a8026d6032b5e216be112a5fb7544e66e23e68d44b4283ff495bdb3983a8">
                    <button type="submit" formtarget="_blank" >Pay with PayU</button>
                </form >
            

Customizing your form

• You can include optional parameters, such as URLs for redirects and notifications or to set the payment page language. A full list of available parameters is available in the section Form parameters section.
• You should enter a signature element. For more information on how to design a signature, see the Signing the form section.
• For styling the form button, you can find some useful graphic resources here.

Overview

To enable notifications for a specific payment, specify the notifyUrl parameter in the payment form. Each payment can receive a different URL to which notifications will be sent.

Every notification is sent asynchronously. After your system receives a notification with the status COMPLETED, instruct it to ignore any further notifications.

After sending a notification, PayU system requires a 200 HTTP status code in response. If it receives a different status code, it will resend the notification. Your system should also take account of situations where a notification is sent several times with the same status. For each repeated notification, response with code 200 should be sent as well.

To ensure trusted communication between PayU and your shop, you must verify the signature value available in the OpenPayu-Signature header each time your system receives any notification from a PayU server. Refer to the Verification of notifications signature for more information.

Notifications are sent for orders in the following statuses: PENDING, WAITING_FOR_CONFIRMATION, COMPLETED, CANCELED.

Note: if you filter IP addresses, remember to allow IPs used by PayU to send the notifications. These are:

PRODUCTION

185.68.12.10, 185.68.12.11, 185.68.12.12, 185.68.12.26, 185.68.12.27, 185.68.12.28

SANDBOX

185.68.14.10, 185.68.14.11, 185.68.14.12, 185.68.14.26, 185.68.14.27, 185.68.14.28 

Payment lifecycle

You can configure a separate auto-receive / automatic collection parameter for each payment method via the Management Panel.

By default, auto-receive is enabled. The basic payment sequence is as follows:

1. Each successfully authorized payment for an order is captured.
2. The buyer is charged with the order amount.
3. The shop balance is increased by the order amount.
4. PayU calculates its commission to the order.

If the auto-receive is turned off, you should capture each order using a PUT method (Order capture) or cancel using DELETE method (Cancellation).

If no such action is taken the order is auto-canceled. Automatic cancellation occurs after a number of days indicated for the payment method.

Notifications are sent immediately after a payment status changes. If the notification is not received by the Shop application, it will be sent again in accordance with the table below:

Sample notifications for updated order status

• Notifications are sent in JSON format using POST method.
• For more information about parameters, refer to the JSON requests description section.
• The following sample notifications are all examples of notifications sent by PayU to a merchant.

Completed order

Below is a sample notification of a completed Order.

Headers:

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

Body:

{
   "order":{
      "orderId":"LDLW5N7MF4140324GUEST000P01",
      "extOrderId":"Order id in your shop",
      "orderCreateDate":"2012-12-31T12:00:00",
      "notifyUrl":"http://tempuri.org/notify",
      "customerIp":"127.0.0.1",
      "merchantPosId":"{POS ID (pos_id)}",
      "description":"My order description",
      "currencyCode":"PLN",
      "totalAmount":"200",
      "buyer":{
         "email":"john.doe@example.org",
         "phone":"111111111",
         "firstName":"John",
         "lastName":"Doe",
         "language":"en"
      },
      "payMethod": {
         "amount": "200",
         "type": "PBL" //or "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"
         }
      ]
   }       
            

Note:

• "localReceiptDateTime" is only present for the status completed.
• "PAYMENT_ID" is the payment identifier, displayed on transaction statements as "Trans ID" and within the transaction search option in the Management Panel.
• PayU-Processing-Time (headers section) shows time spent at PayU side for processing given request till first notification try. Some notifications are intentionally suspended, because merchant can receive only limited number of notification in parallel (throttling). Then, the throttling time is excluded from PayU-Processing-Time. Moreover, this parameter does not include time spent at bank or card organization side.
• "payMethod.type" means payment method type used. "PBL" stands for online or standard transfer, "CARD_TOKEN" is card payment (incl. Masterpass and Visa Checkout), and "INSTALLMENTS" is a payment via PayU|Installments.

Cancelled order:

The folllowing is a sample notification for cancelled order:

{
   "order":{
      "orderId":"LDLW5N7MF4140324GUEST000P01",
      "extOrderId":"Order id in your shop",
      "orderCreateDate":"2012-12-31T12:00:00",
      "notifyUrl":"http://tempuri.org/notify",
      "customerIp":"127.0.0.1",
      "merchantPosId":"{POS ID (pos_id)}",
      "description":"My order description",
      "currencyCode":"PLN",
      "totalAmount":"200",
      "products":[
         {
            "name":"Product 1",
            "unitPrice":"200",
            "quantity":"1"
         }
      ],
      "status":"CANCELED"
   }
}
            

The following is a sample notification for when a payment status is updated to refund:

                {
                   "orderId": "2DVZMPMFPN140219GUEST000P01",
                   "extOrderId": "Order id in your shop",
                   "refund":{
                      "refundId": "912128",
                      "amount": "15516",
                      "currencyCode": "PLN",
                      "status": "FINALIZED",
                      "statusDateTime": "1395677071799",
                      "reason": "refund",
                      "reasonDescription": "on customer’s request",
                      "refundDate": "1395677071799"
                   }
                }
            

Comment: For "PayU | Pay later" payment method funds are transferred to a credit provider.

Refund request can be made in two modes: full and partial.

To refund the buyer account, call the endpoint /api/v2_1/orders/{orderId}/refunds using the POST method. Example calls are shown below.

Full refund request

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

Partial refund request

You can process refund requests as either full or partial. For partial refunds, always specify the amount in the lowest unit of a given currency, which must be the same currency as the initial order (e.g. for Poland lowest currency unit is “grosz” so 10 pln should be given as 1000).

You can send several partial refund requests for each single order. The total value of the requests must not exceed the order value.

The payu system allows multiple partial refunds to be executed at the same time. To do so, the extRefundId parameter must be sent in the request. In situations where partial refunds will not be executed more than once per second, the extRefundId parameter is not required.

Following example shows partial refund request with for 10 units in the currency of the order:

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

For information on the supported authentication methods, see section: Signing API calls parameters

As soon as the PayU system receives a request, it will confirm this fact with a message containing a relevant status.

Accepted request will be confirmed by a response with containing appropriate status:

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

Or in case of rejection due to one of the errors:

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

A refund request that has been properly accepted by the PayU system may be cancelled in the Management Panel.

Refund creation error codes

The status field included in each response contains an error code which provides information about the problem. A list of possible error codes is shown below.

To retrieve refund data call endpoint /api/v2_1/orders/<orderId>/refunds using the GET method. In response you will receive list of refunds made for specific Order:

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

You can also download data about specific refund. To do so call endpoint /api/v2_1/orders/<orderId>/refunds/<refundId> using the GET method. In response you will receive data about refund with the given refundId:

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

Refund authorization error codes

After retrieving data of incorrectly made refund, you will also receive information about error that have occurred:

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

The table contains error codes that may occur while processing refund:

A cancellation request always relates to the entire order. After cancellation, all funds are returned to the buyer account.

To cancel an order and proceed with a refund to the Payer’s account, call the endpoint /api/v2_1/orders/{orderId} using the DELETE method. An example call is shown below.

Note: only orders which are not COMPLETED can be canceled.

The following is an example response from the API after successful cancellation of an order:

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

Order capture request always concerns the whole order. Capturing an order updates its status to COMPLETED (ended).

To update the order status, call the endpoint /api/v2_1/orders/{orderId}/status using the PUT method.

Below is an example of order capture via the 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"
}'     
            

For information on the supported authentication methods, see Signing API calls parameters.

Below is a sample response after a successful order status update.

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

The OrderRetrieveRequest message enables you to retrieve the status and details of an order.

Simply make a HTTP GET call to https://secure.payu.com/api/v2_1/orders/{orderId}

Below is a sample response after retreving 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 more information in regard to the fields specified in the above sample, please refer to JSON requests description, sections OrderRetrieveRequest and OrderRetrieveResponse.

The TransactionRetrieveRequest message enables you to retrieve the details of transactions created for an order.

Simply make a HTTP GET call to https://secure.payu.com/api/v2_1/orders/{orderId}/transactions

Using this endpoint is extremely useful if you would like to get bank account details or card details.

Explanations of parameters used in TransactionRetrieveRequest and TransactionRetrieveResponse can be found here.

Please note that although card details are available right after transaction has been processed, the bank details may be available either after few minutes or on the next business day, depending on the bank.

Below is a sample response after retreving card transaction data:

                  
                  {
                    "transactions": [
                      {
                        "payMethod": {
                          "value": "c"
                        },
                        "paymentFlow": "FIRST_ONE_CLICK_CARD",
                        "card": {
                          "cardData": {
                            "cardNumberMasked": "543402******4014",
                            "cardScheme": "MC",
                            "cardProfile": "CONSUMER",
                            "cardClassification": "DEBIT",
                            "cardResponseCode":"000",
                            "cardResponseCodeDesc":"000 - OK",
                            "cardEciCode":"2",
                            "card3DsStatus": "Y",
                            "card3DsStatusDescription": "MessageVersion=2.1.0,browser flow,3DS method not available,dynamic authentication,no cancel indicator,no status reason",
                            "cardBinCountry":"PL",
                            "firstTransactionId": "MCC0111LL1121"
                          },
                          "cardInstallmentProposal": { //optional object, see note below
                            "proposalId": "5aff3ba8-0c37-4da1-ba4a-4ff24bcc2eed"
                          }
                        },
                        "resultCode": "AUT_ERROR_NO_AUTHORIZATION" // optional parameter
                      }
                    ]
                  }              
                

cardInstallmentProposal only applies to Pay in installments with Mastercard

In order to generate shop data, first generate an authentication token.

POS which is used to generate the oAuth token must belong to the shop whose data is being downloaded.

Then make a HTTP GET call to https://secure.payu.com/api/v2_1/shops/{public_shop_id}

Sample request to retrieve shop data

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

Sample response to retrieving shop data

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

total shows the current shop balance.

available shows the funds on the shop's balance after deduction of the payout block/reserve.

In order to display the payment methods icons or buttons as you see fit, you need to retrieve them. Additionally, you would need to place some information about PayU on your website to satisfy the legal requirements. This is discussed in further sections.

Transparent order request and response

To create orders with an already defined payment method you need to add payMethod section.

                    {
                        "payMethods": {
                            "payMethod":    {
                                "type":"PBL",
                                "value":"m",
                                //optional for BLIK (blik) and Visa Checkout (vc), see below
                                "authorizationCode":"123456",
                                //optional for Visa Checkout (vc), see below
                                "specificData":[] 
                            }
                        }
                    }
                 

For the "blik" payment method, it is possible either to redirect the payer to an external page or to capture a 6-digit authorization code directly on your page. In the latter case, the authorizationCode parameter must be present in the payMethods section. In this case, the HTTP success response code will be 201 instead of the standard 302.

All BLIK services except for the Redirect to the BLIK Payment Page option require special configuration of the payment point (POS) by PayU. The configuration for Transparent Payment with BLIK Authorization Code is not compatible with the Redirect to the BLIK Payment Page option, so it requires a separate payment point.

For more details see Creating a new order via the API, Status codes and Visa Checkout sections.

Example of a successful response

{
   "orderId":"VVLR1HXK2S160929GUEST000P01",
   "status":{
      "statusCode":"SUCCESS"
   },
   "redirectUri":"https://some_uri.com"
}
                

Example of a successful response for banks: orx, bnx, gbx, nlx

{
   "orderId":"1BSLZN2FFZ160929GUEST000P01",
   "extOrderId":"number of extOrderId",
   "status":{
      "statusCode":"WARNING_CONTINUE_REDIRECT"
   },
   "redirectUri":"https://some_uri.com"
}
                

In order to retrieve the payment methods, you need first to obtain OAuth access token, see Signing API calls.

Then you need to insert the access token into header and use the GET method to send request to endpoint api/v2_1/paymethods.

In order to retrieve description in a specific language, you may use optional parameter: ?lang={2-letter ISO code}, e.g. 'cs', 'de', 'pl'. If not specified it will be set by default to 'pl'.

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

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

Sample postive response (HTTP 200). Description of fields are below the sample:

{  
   
   "payByLinks":[  
      {  
         "value":"c",
         "name":"Płatność online kartą płatniczą",
         "brandImageUrl":"http://static.payu.com/images/mobile/logos/pbl_c.png",
         "status":"ENABLED"
         "minAmount": 50,
         "maxAmount": 100000
      },
      {  
         "value":"o",
         "name":"Pekao24Przelew",
         "brandImageUrl":"http://static.payu.com/images/mobile/logos/pbl_o_off.png",
         "status":"DISABLED"
         "minAmount": 50,
         "maxAmount": 100000
      },
      {  
         "value":"ab",
         "name":"Płacę z Alior Bankiem",
         "brandImageUrl":"http://static.payu.com/images/mobile/logos/pbl_ab_off.png",
         "status":"TEMPORARY_DISABLED"
         "minAmount": 50,
         "maxAmount": 100000
      }
   ]
}          
            

payByLinks

European Union regulations such as Payment Services Directive and General Data Processing Regulation impose certain information requirements, described below.

In case of a standard integration (payment method is chosen on a PayU hosted page), the information is displayed in the footer of PayU payment page.

In order to help you stay compliant with these requirements, this information is also displayed for transparent integrations, in the following way:

1. on a PayU hosted page (in case of card payments via PayU hosted form or services like PayU | Installments an PayU | Pay Later)
2. on an intermediary page, displayed before redirection to bank's page (in case of online and traditional transfers or alternative payment methods)

It is possible not to display the intermediary page, provided that the required information are presented on your website. It requires a configuration change performed by PayU.

You need to include the below information and links and contact us at help@payu.pl by sending an email with link to your page and a screenshot.

Below is the information to be displayed:

_{Payment order: Payment is processed by PayU SA;The recipient's data, the payment title and the amount are provided to PayU SA by the recipient; The order is sent for processing when PayU SA receives your payment. The payment is transferred to the recipient within 1 hour, not later than until the end of the next business day;PayU SA does not charge any service fees.}

_{By paying you accept PayU Payment Terms}

_{The controller of your personal data is PayU S.A. with its registered office in Poznan (60-166), at Grunwaldzka Street 186 ("PayU"). Your personal data will be processed for purposes of processing payment transaction, notifying You about the status of this payment, dealing with complaints and also in order to fulfill the legal obligations imposed on PayU.}

_{The recipients of your personal data may be entities cooperating with PayU during processing the payment. Depending on the payment method you choose, these may include: banks, payment institutions, loan institutions, payment card organizations, payment schemes), as well as suppliers supporting PayU’s activity providing: IT infrastructure, payment risk analysis tools and also entities that are authorised to receive it under the applicable provisions of law, including relevant judicial authorities. Your personal data may be shared with merchants to inform them about the status of the payment. You have the right to access, rectify, restrict or oppose the processing of data, not to be subject to automated decision making, including profiling, or to transfer and erase Your personal data. Providing personal data is voluntary however necessary for the processing the payment and failure to provide the data may result in the rejection of the payment. For more information on how PayU processes your personal data, please click PayU Privacy Policy.}

Notes:

1. payment order information should be displayed only if your website is in Polish and targeted to Polish users (and you should obviously display the Polish version, the text above is only to help you understand the requirement). In case you accept payments via website in other language versions (Czech, English, Hungarian etc.) you are not required to display this information. However, you are always required to present the data processing disclaimer.
2. You are advised, to initially display only the first paragraph and make the second one available via some action from the user (e.g. by clicking "read more").
3. The above information is available in language versions provided below.

Legal disclaimers

PayU hosted payment form

If you have enabled payments via credit cards, you are obliged to be PCI DSS compliant.

You should annually complete a Self-Assessment Questionnaire (SAQ) and conduct on a quarterly basis network scan by an Approved Scan Vendor (ASV).

Additionally if you process over 6 million card transactions annually you should complete Report on Compliance (ROC) by Qualified Security Assessor (QSA).

You can find more information at Security Standards Council.

To invoke the form, add the following object to OrderCreateRequest:

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

After the order is created with the above, the redirectUri will contain a link to the card payment form.

The language version of the card form is taken from:

1. from lang param added to query string in redirectUri, e.g. "&lang=en",
2. from language field added to Buyer object in OrderCreateRequest. For more information, see the Buyer Section Fields Description.,
3. basing on the language setting of the buyer's browser
4. and none of the languages above is supported, English version will be displayed. Full list of available languages is here.

In order to increase payment conversion rate, PayU offers currency conversion for most popular currency pairs. The payer may choose to pay in different currency (e.g. EUR) while you will get paid in your currency (e.g. PLN).

A more advanced option is to use a Secure Form or build your own form.

The card token returned by the widget should be sent to PayU in the payMethods object.

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

Custom payment form

PayU supports full integration of a card form. Card fields may be customized and placed in any manner.

Custom card form implementing scripts provided by PayU is described here.

Note: in case you do not want PayU to tokenize the card and store it for future payments, the agreement for card storage should be skipped.

 <tr>
    <td>PayU terms of condition and acceptance to save credit card</td>
    <td><input type="checkbox" value="false" class="payu-agreement"></td>
 </tr>               

The card token returned by the form should be sent to PayU in the payMethods object.

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

Card data in plain text

PayU supports card transactions, where card data is sent as plain text. The card data must be sent to PayU in the payMethods object. Example:

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

Responses are standard responses for cards, the most important ones are: SUCCES, WARNING_CONTINUE_3DS, WARNING_CONTINUE_CVV. For details and other response codes please refer to: Status codes.

Please note: to send card data as plain text, you must be PCI DSS compliant. It also requires a configuration change. Therefore, before starting the integration process, please contact PayU via your Account Manager.

OAuth

You authenticate with OAuth standard by obtaining a token, which is used for further communication with PayU servers. You can view authorization data from the management panel. There are two grant types: client_credentials for standard integration and trusted_merchant used for authentication of requests made for logged-in shop/application users with fixed ext_customer_id.

Remember to add a Content-Type: application/x-www-form-urlencoded header, otherwise a 401 error will be returned.

Request example for obtaining access token in both modes:

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

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

Request parameters:

Response example:

                    {
                        "access_token":"7524f96e-2d22-45da-bc64-778a61cbfc26",
                        "token_type":"bearer",
                        "expires_in":43199, //expiration time in seconds
                        "grant_type":"client_credentials"
                    }  
                

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

signature=...;algorithm=...;sender=...

Note that the order of these elements is irrelevant.

<input name="OpenPayu-Signature" value="sender=45654;algorithm=MD5;signature=aeb032c66779a4de34ec7b7f597b5058">

Available hash functions

The algorithm parameter may take the following values:

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

Algorithm for signing parameters in the form

1. Sort all the fields available in the form in alphabetic, ascending order according to the names of parameters and the (name attribute of the input element).
2. Concatenate values of all the fields in the indicated order.
3. Assign your private key to this sequence of characters.
4. Use one of the available abbreviation functions.
5. Complete the OpenPayU-Signature field with values signature=A;algorithm=B;sender=C, where:
   • A is the result of the abbreviation function,
   • B is the name of an applied abbreviation function,
   • C is a POS identifier.

Below is the pseudo-code of an algorithm for signing parameters in the form

generate_signature(form, privateKey, algorithm, posId) {
                    
                    sortedValues = sortValuesByItsName(form)
                    
                    foreach value in sortedValues {
                    content = content + value
                    }
                    content = content + privateKey
                    
                    result = "signature=" + algorithm.apply(content) + ";"
                    result = result + "algorithm=" + algorithm.name + ";"
                    result = result + "sender=" + posId
                    
                    return result
                    }

Below is a code example from OpenPayU SDK.

Signature of an exemplary form

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

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

                    565f9f4dda43c8e24ccab4472133d680e2aa58e1f58bea845c4cf2926965144d
                

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

In case of further questions, please contact us.

The following is a sample header:

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

To verify the header:

1. Retrieve the OpenPayU-Signature header from a notification received from a PayU server.
2. Extract the “signature” value from the header:

   string incoming_signature = signature_header[signature]

3. Check the type of a hashing function used to generate the signature (this is usually md5)
4. Combine the body of the incoming notification with the value of second_key:

   string concatenated = JSONnotification + second_key;

5. Select an expected signature value by applying the hashing function (e.g. md5) in the received chain of characters:

   string expected_signature = md5(concatenated)

6. Compare the strings: expected_signature and incoming_signature:

                           if(expected_signature == incoming_signature){
                               return true; //signature is correct
                           }else{
                               return 'Wrong signature' // signature is incorrect
                           }
                       

OrderCreateRequest - fields description

We recommend to not use special characters in transaction description. Certain characters are not allowed by the banks.

Parameter	Description	Required
extOrderId	ID of an order used in merchant system. Order identifier assigned by the merchant. It enables merchants to find a specific order in their system. This value must be unique within a single POS.	No
notifyUrl	The address for sending notifications	No
customerIp	Payer’s IP address, e.g. 123.123.123.123. Note: 0.0.0.0 is not accepted.	Yes
merchantPosId	Point of sale ID.	Yes
validityTime	Duration for the validity of an order (in seconds), during which time payment must be made. Default value 86400.	No
description	Description of the an order.	Yes
additionalDescription	Additional description of the order.	No
visibleDescription	Text visible on the PayU payment page (max. 80 chars).	No
statementDescription	Payment recipient name followed by payment description (order ID, ticket number etc) visible on card statement (max. 22 chars). The name should be easy to recognize by the cardholder (e.g "shop.com 124343"). If field is not provided, static name configured by PayU will be used.	No
currencyCode	Currency code compliant with ISO 4217 (e.g EUR).	Yes
totalAmount	Total price of the order in pennies (e.g. 1000 is 10.00 EUR). Applies also to currencies without subunits (e.g. 1000 is 10 HUF).	Yes
cardOnFile	Information about party initializing order: FIRST - payment initialized by the card owner who agreed to save card for future use. You can expect full authentication (3D Secure and/or CVV). If you want to use multi-use token (TOKC_) later, you have to be confident, that first payment was successful. Default value for single-use token (TOK_). In case of plain card data payments you should retrieve transaction data to obtainfirstTransactionId. It should be passed in payMethods.payMethod.card section for transactions marked as STANDARD, STANDARD_CARDHOLDER and STANDARD_MERCHANT; STANDARD_CARDHOLDER - payment with already saved card, initialized by the card owner. This transaction has multi-use token (TOKC_). Depending of payment parameters (e.g. high transaction amount) strong authentication can be expected (3D Secure and/or CVV). Default value for multi-use token (TOKC_); STANDARD_MERCHANT - payment with already saved card, initialized by the shop without the card owner participation. This transaction has multi-use token (TOKC_). By the definition, this payment type does not require strong authentication. You cannot use it if FIRST card-on-file payment failed. cardOnFileparameter cannot be used with recurring parameter.	No, should be used for multi-use token (TOKC_) or plain card data payments.
recurring	Marks the order as recurring payment. FIRST - payment initialized by the card owner who agreed to save card for future use in recurring plan. You can expect full authentication (3D Secure and/or CVV). If you want to use multi-use token (TOKC_) later, you have to be confident, that first recurring payment was successful. STANDARD - subsequent recurring payment (user is not present). This transaction has multi use token (TOKC_). You cannot use it if FIRST recurring payment failed. recurringparameter cannot be used with cardOnFile parameter. It is recommended to also send 3DS 2 recurring data.	No, should be used only for multi-use token (TOKC_) recurring payments.
continueUrl	Address for redirecting the customer after payment is commenced. If the payment has not been authorized, error=501 parameter will be added. Please note that no decision regarding payment status should be made depending on the presence or lack of this parameter (to get payment status, wait for notification or retrieve order details). IMPORTANT: the address must be compliant with the structure below: Please keep in mind: accepted schemas are http and https, such elements as port, path, query and fragment are optional, query values must be encoded.	No
buyer	Section containing buyer data. This information is not required, but it is strongly recommended to include it. Otherwise the buyer will be prompted to provide missing data on PayU page and payment via Installments or Pay later will not be possible. For a list of parameters, see section buyer.	No, recommended
products	Section containing data of the ordered products. Section products is an array of objects of type product. For a list of parameters, see section product.	Yes
payMethods	Section allows to directly invoke payment method. Section payMethods is one object of payMethod type. For a list of parameters, see section payMethod.	No
mcpData	Section allows to pass currency conversion details if you chose to use Multi-Currency Pricing. For a list of parameters, see section mcpData.	No
threeDsAuthentication	Contains optional fields required by 3DS 2 authentication protocol. To learn how to tackle 3DS 2 authentication for card payments see 3DS 2 page. For a list of parameters, see section threeDsAuthentication.	No
credit	Section containing credit data. This information is not required, but it is strongly recommended to include it. Otherwise the buyer will be prompted to provide missing data on provider page when payment by Installments or Pay later. For a list of parameters, see section <credit>.	No, recommended

OrderCreateResponse - fields description

Notifications - fields description

OrderStatusUpdateRequest - fields description

OrderStatusUpdateResponse - fields description

RefundCreateRequest - fields description

Description of RefundInfoType

RefundCreateResponse - fields description

Description of RefundRecord_Type

OrderCancelRequest - fields description

OrderCancelResponse - fields description

OrderRetrieveRequest - fields description

OrderRetrieveResponse - fields description

TransactionRetrieveRequest

The only parameter in this section is orderId which should be placed in the request.

TransactionRetrieveResponse - for PBL

TransactionRetrieveResponse consists of list of objects(transactions under given order). At present time it is a single element list. However in the near future there are plans to expand it - in case of re-payments - to support more than one element.

Fields below, that reffers to PBL's, are filled based of the data given by bank.

TransactionRetrieveResponse - for cards

Common sections

Product

payMethod object in OrderCreateRequest.

payMethod object in notification.

mcpData

buyer

delivery

order fields description

status section fields description

OrderCreateRequest - threeDsAuthentication object

threeDsAuthentication.browser fields description.

threeDsAuthentication.exemption fields description.

threeDsAuthentication.sdk fields description. All below fields are generated by a certified 3DS SDK.

threeDsAuthentication.merchantRiskIndicator fields description.

threeDsAuthentication.recurring fields description.

threeDsAuthentication.cardholder fields description.

threeDsAuthentication.cardholder.accountInformation fields description.

threeDsAuthentication.cardholder.billingAddress fields description.

credit fields description.

The credit section stores data needed for credit process. This information is not required, but it is strongly recommended to include it. Otherwise the buyer will be prompted to provide missing data on provider page when payment by Installments or Pay later..

shoppingCart fields description

shippingMethod fields description

address fields description

credit.applicant fields description

credit.applicant.additionalInfo fields description

General parameters

We recommend to not use special characters in transaction description. Certain characters are not allowed by the banks.

URL addresses

Parameter	Required	Description
continueUrl	No	Address for redirecting the customer after payment is commenced. If the payment has not been authorized, error=501 parameter will be added. Please note that no decision regarding payment status should be made depending on the presence or lack of this parameter (to get payment status, wait for notification or retrieve order details). IMPORTANT: the address must be compliant with the structure below: Please keep in mind: accepted schemas are http and https, such elements as port, path, query and fragment are optional, query values must be encoded.
notifyUrl	No	URL to which notifications of a changed order status will be sent

Buyer

Shipping address

The buyer.delivery section stores the shipping address. The information is nor required.

Products

The products section is mandatory and stores a list of products ordered. The list uses an iterator. Every product is numbered with a value in the range [0..n], for example products[0].

Card 3Ds statuses:

1. Communication should be carried out with encrypted channel following the HTTPS protocol using verified and trusted certificate.
2. If signatures are needed for given operation, then operational messages on POS should be signed with hash function, e.g. SHA256. restapi.html#references_form_signature
3. The address, to which notification statuses from PayU are sent, should communicate with encrypted HTTPS channel.
4. After receiving notification merchant should always verify credibility of given notification by checking message signature. restapi.html#references_verification_of_notifications_signature
5. Merchant should never publicly share their MD5 keys for POS. In case of accidental leak or theft of MD5 keys, Merchant should immediately contact PayU's customer service.