REST API

Simplest and most convenient PayU integration protocol.

1 Introduction

Before you read this document, we advise you to go through API Overview where you can information on how to create a PayU merchant account, what integration model to choose and how to test your integration.

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, email PayU technical support tech@payu.pl.

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.

2 Creating a new order

2.1 Creating a new order via the API

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.
The following is a basic sample order:
Production  Sandbox

                       curl -X POST https://secure.payu.com/api/v2_1/orders \
                       -H "Content-Type: application/json" \
                       -H "Authorization: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd" \
                       -d '{
                           "notifyUrl": "https://your.eshop.com/notify",
                           "customerIp": "127.0.0.1",
                           "merchantPosId": "145227",
                           "description": "RTV market",
                           "currencyCode": "PLN",
                           "totalAmount": "21000",
                           "buyer": {
                               "email": "john.doe@example.com",
                               "phone": "654111654",
                               "firstName": "John",
                               "lastName": "Doe",
                               "language": "en"
                           },
                           "settings":{
                        	   "invoiceDisabled":"true"
                           },
                           "products": [
                               {
                                   "name": "Wireless Mouse for Laptop",
                                   "unitPrice": "15000",
                                   "quantity": "1"
                               },
                               {
                                   "name": "HDMI cable",
                                   "unitPrice": "6000",
                                   "quantity": "1"
                               }
                           ]
                       }'
                    

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

apiary

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

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.

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

2.2 Integration of payment form

The code snippet below is an example of a simple form that enables the buyer to make a payment. Integration via form is not recommended and presented only for informational purposes for legacy implementations.
                 <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 .
  • Optionally enter a signature element. For more information on how to design a signature, see the section
  • For styling the form button, you can find some useful graphic resources here.

3 Notifications

Each payment in the PayU system has a lifecycle, which is comprised of stages related to key events such as acceptance, settlement, and cancellation. PayU provides you with a mechanism that notifies your system of all changes to the payment status.

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, the PayU system requires a 200 HTTP status code in response. If it receives a different status code, it will resend the notification.

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.

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

Status Description
PENDING Payment is currently being processed.
WAITING_FOR_CONFIRMATION PayU is currently waiting for the merchant system to receive (capture) the payment. This status is set if auto-receive is disabled on the merchant system.
COMPLETED Payment has been accepted. PayU will pay out the funds shortly.
CANCELED Payment has been cancelled and the buyer has not been charged (no money was taken from buyer's account).
REJECTED Payment has been rejected, but the buyer was charged (the money was transferred from the buyer to PayU). The merchant can either complete the order and receive the money or cancel it to return the money to the buyer.

3.1 Order status

Sample notifications for updated order status

  • Notifications are sent in JSON format using POST method.
  • For more information about parameters, refer to the 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:

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

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

3.2 Refund status

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

4 Refunds

The PayU system fully supports refunds for processed payments, the balance of which is transferred directly to the buyer’s account.

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.

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 you to send a partial refund request once every minute.

Refunding a buyer account

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

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

The following is an example of a 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"
  }
}'
            

The following is an example of a partial refund request, for a value of 10 in the order currency:

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

As soon as the PayU system receives a request, it will confirm this fact with a message containing a relevant status (see the section Status Codes).

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

Refund error codes

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

StatusCode Code CodeLiteral Description
OPENPAYU_BUSINESS_ERROR TRANS_NOT_ENDED 9101 Transaction has not been finalized
OPENPAYU_BUSINESS_ERROR NO_BALANCE 9102 Lack of funds in account
OPENPAYU_ERROR_VALUE_INVALID AMOUNT_TO_BIG 9103 Refund amount exceeds transaction amount
OPENPAYU_ERROR_VALUE_INVALID AMOUNT_TO_SMALL 9104 Refund value is too small
OPENPAYU_BUSINESS_ERROR REFUND_DISABLED 9105 Refunds have been disabled
OPENPAYU_BUSINESS_ERROR REFUND_TO_OFTEN 9106 Too many refund attempts have been made
OPENPAYU_ERROR_VALUE_INVALID PAID 9108 Refund was already created
OPENPAYU_ERROR_INTERNAL UNKNOWN_ERROR 9111 Unknown error
OPENPAYU_BUSINESS_​ERROR REFUND_IDEMPOTENCY_MISMATCH 9112 extRefundId was re-used and other params do not match the values sent during the first call.
OPENPAYU_BUSINESS_​ERROR TRANS_BILLING_​ENTRIES_NOT_COMPLETED 9113 Shop billing has not yet been completed

5 Cancellation

You can cancel (reject) orders processed by the PayU system, for example if a product or service is not delivered.

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 T /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.

To return money to buyer's bank account for an order in WAITING_FOR_CONFIRMATIONstatus, you need to send DELETE request twice.

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

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

6 Order capture

You can capture or cancel orders with the status WAITING_FOR_CONFIRMATION or REJECTED status (see Cancellation). If no capture or cancel action is taken, the order is cancelled automatically, after the number of days indicated by the payment method.

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

7 Order and transaction data retrieve

You may get the details of your Orders or Transactions (payments) via below requests.

7.1 Order data retrieve

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

For more information in regard to the fields specified in the above sample, please refer to JSON requests description, sections OrderRetrieveRequest and OrderRetrieveResponse.

7.2 Transaction data retrieve

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.

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": "CARD", 
      // also MASTERPASS, VISA_CHECKOUT, ONE_CLICK_CARD, ONE_CLICK_CARD_RECURRING etc.
      "card": {
        "cardData": {
          "cardNumberMasked": "543402******4014",
          "cardScheme": "MC", //MC (MasterCard/Maestro), VS (Visa)
          "cardProfile": "CONSUMER", // CONSUMER or BUSINESS
          "cardClassification": "DEBIT", //DEBIT or CREDIT
          "cardResponseCode":"000", //details are described below
          "cardResponseCodeDesc":"000 - OK", //details are described below
          "cardEciCode":"5", //details are described below
          "card3DsStatus":"AY", //details are described below
          "cardBinCountry":"PL" 
        }
      }
    }
  ]
}
              

Check Card status codes to learn more about card codes.

Below is a sample response after retreving pay-by-link or bank transfer transaction data:

{  
   "transactions":[  
      {  
         "payMethod":{  
            "value":"m"
         },
         "bankAccount":[  
            "number":"80607787095718703296721164",
            "name":"JAN KOWALSKI", 
            //note: depending on the bank, the name
            //and address may be all included in "name" 
            "city":"WARSZAWA",
            "postalCode":"02-638",
            "street":"UL.NOWOWIEJSKIEGO 8",
            "address":"Warszawa Nowowiejskiego 8"
         ]
      }
   ]
}
                

8 Transparent integration

Transparent (or "white label") integration allows you to display payment methods on your website and create orders in the PayU system with an already defined payment method.
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.

For example:
                    {
                        "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":[] 
                            }
                        }
                    }
                 

Note: for payment method "blik" it is possible to either 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 payMethods section and the HTTP success response code is 201 instead of standard 302.

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

8.1 Payment methods retrieve

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

.

apiary

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

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

payByLinks

payByLinks are payment methods which always require redirection of the user. Therefore this section includes online bank transfers (pay-by-links), traditional bank transfer, installments and non-tokenized cards.
Parameter Description
value payType value. Available values are here.
name Name of payType set by PayU
brandImageUrl Link to payType logo graphic on PayU server.
status Possible values: 'ENABLED', 'DISABLED', 'TEMPORARY_DISABLED'.

8.2 Information requirements

There are legal requirements to be met for the transparent integration model.

You need to put the following text and links on your website, so the payer is aware that PayU is the payment service provider.

The below information should be displayed only if the sales are targeted at consumers in Czech Rep. or Poland. If you target consumers on other EU markets (e.g. Germany, Hungary etc.), there is no obligation to provide the information below.

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.

[insert a checkbox, here] I accept Terms and Conditions of the single transaction in of PayU

The administrator of your personal data within the meaning of the Personal Data Protection Act of 29 August 1997 (Journal of Laws of 2002, No. 101, item 926 as amended) is PayU SA with the registered office in Poznań (60-166) at ul. Grunwaldzka 182. Your personal data will be processed according to the applicable provisions of law for archiving and service provision purposes. Your data will not be made available to other entities, except of entities authorized by law. You are entitled to access and edit your data. Data provision is voluntary but required to achieve the above-mentioned purposes.

The checkbox may be already checked. It should not be possible to pay with the checkbox unchecked - in such a case the user should be shown a message like:

You have to accept "Terms and Conditions of the single transaction in of PayU".

Available language versions of the above information can be found here.

8.3 Card form

There are several options to process card payments via PayU.

PayU hosted payment form

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.

Note: in order to increase payment conversion rate, PayU offers the following features on the hosted payment form:
  • 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).
  • automated language detection. The language of the form is detected basing on browser setting from the available languages. The default language (used when PayU does not support particular language) is English.

A more advanced option is to use a widget hosted by PayU or build your own form.

PayU hosted widget

Integration details and widget example can be found here:

  1. Inline widget
  2. Pop-up widget

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

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

Please note: widget requires a configuration change (tokenization service must be enabled for your POS). Therefore, before starting the integration process, please contact PayU via your Account Manager.

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

Please note: custom form requires a configuration change (tokenization service must be enabled for your POS). Therefore, before starting the integration process, please contact PayU via your Account Manager.

Plain card data in Order request

PayU supports card transaction, 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: plain card data in OrderRequest requires a configuration change. Therefore, before starting the integration process, please contact PayU via your Account Manager.

9 References

9.1 Signing API calls

The REST API supports two authentication method: OAuth (recommended by PayU) and HTTP Basic.

OAuth

You authenticate with OAuth standard by obtaining a token, which is used for further communication with PayU servers. You can veiw authorization data from the management panel. There are two grant types: client_credentials for standard integration (for standard integration) and trusted_merchant (for use with token payments).

Request example for obtaining access token in client_credentials mode:

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

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

apiary

HTTP Basic

HTTP Basic is not recommended.

In order to receive documentation for this method please refer to: tech@payu.pl.

9.2 Signing the form

If you use SDK, you do not need to implement your signature individually.
To ensure data integrity, order parameters are signed in the OpenPayu-Signature field. The field structure is as follows:
signature=...;algorithm=...;sender=...

Note that the order of these elements is irrelevant.

The meaning of the elements is as follows:
  • signature - it contains a signature generated in compliance with the algorithm,
  • algorithm - it defines an hash function used to generate a signature,
  • sender - a POS identifier.
The following is an excerpt from a form containing a sample signature:
<input name="OpenPayu-Signature" value="sender=45654;algorithm=MD5;signature=aeb032c66779a4de34ec7b7f597b5058">

Available hash functions

The algorithm parameter may take the following values:

  • MD5,
  • SHA1,
  • SHA256.

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
                    }

9.3 Verification of notifications signature

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
                            }
                        

9.4 JSON requests description

This section details all parameters (both required and optional) supported by the payment form.

OrderCreateRequest - fields description

Parameter Description Required
extOrderId ID of an order used in merchant system No
notifyUrl The address for sending notifications Yes
customerIp Customer IP address Yes
merchantPosId Point of sale ID Yes
validityTime Duration for the validity of an order (in seconds), during which time payment must be made No
description Description of the an order Yes
additionalDescription Additional description of the order No
currencyCode Currency code (e.g PLN, EUR) Yes
totalAmount Total price of the order No
continueUrl Address for redirecting the customer after successful payment. If there is no authentication, an error=501 parameter is automatically added to URL. The return to shop address is for information purposes only; no decision is made on its basis No
settings A section containing 1 field: "invoiceDisabled". Field which supports values true/false, default is 'false'. Setting 'true' removes the option I want to receive an invoice from the payment summary page. Setting 'false' or lack of this section enables the buyer to require an invoice from the merchant. Billing details collected by PayU form are sent via notification for the order. No
buyer Section containing buyer data. For a list of parameters, see section <buyer> No
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

OrderCreateResponse - fields description

Parameter Description
redirectUri Address to redirect the buyer
orderId Order ID generated by the PayU system
extOrderId External order ID (assigned by the shop)
status Response status object. For a list of parameters, see section <status>

Notifications - fields description

Parameter Description
order Section containing <order> object. For a list of parameters, see section <order>

OrderStatusUpdateRequest - fields description

Parameter Description Required
orderId Order id in PayU system Yes
orderStatus New order status. Possible values are:
  • NEW
  • PENDING
  • CANCELED
  • REJECTED
  • COMPLETED
  • WAITING_FOR_CONFIRMATION
Yes

OrderStatusUpdateResponse - fields description

Parameter Description
status Response status object. For a list of parameters, see section <status>.

RefundCreateRequest - fields description

Parameter Description Required
orderId ID of refunded order Yes
refund Element of <RefundInfoType>. Contains detailed information about a refund Yes

Description of <RefundInfoType>

Parameter Description Required
description Refund description Yes
amount Amount of the refund. If this is left blank, all funds will be returned to the buyer No
extRefundId External refund ID No
currencyCode Currency code (e.g. PLN, EUR) No
bankDescription Bank operation description No
type Operation type (possible value: REFUND_PAYMENT_STANDARD) No

RefundCreateResponse - fields description

Parameter Description
orderId ID of refunded order
refund Element of <RefundRecord_Type>.
status Response status object. For a list of parameters, see section <status>

Description of <RefundRecord_Type>

Parameter Description
refundId Refund ID
extRefundId External refund ID
amount Amount of the refund. If this is left blank, all money will be returned
currencyCode Currency code (e.g PLN, EUR)
description Refund description
creationDateTime Date of refund creation
status Refund status code (PENDING, CANCELED, FINALIZED)
statusDateTime Timestamp of the status

OrderCancelRequest - fields description

Parameter Description Required
orderId Order ID generated by the PayU system Yes

OrderCancelResponse - opis pól komunikatu

Parameter Description
orderId Order ID generated by the PayU system
extOrderId External order ID (assigned by the shop)
status Response status object. For a list of parameters, see section <status>

OrderRetrieveRequest - fields description

Parameters Description Required
orderId Order ID generated by the PayU system Yes

OrderRetrieveResponse - fields description

Parameters Description
orders Array of <order> objects. For a list of parameters, see section <order>
status Response status object. For a list of parameters, see section <status>

Common sections

<product> fields description

Parameters Description Required
name Name of the product Yes
unitPrice Unit price Yes
quantity Quantity Yes
virtual Product type, which can be virtual or material; (possible values true or false). No
listingDate Marketplace date from which the product (or offer) is available, for example: "2016-01-26T17:35:37+01:00" No

<payMethod> fields description

Parameters Description Required
type Payment method type, possible values:
  • PBL (payment requires redirection)
  • CARD_TOKEN
  • BANK_TOKEN
  • PAYMENT_WALL (payment requires redirection)
Yes
value Payment type for PBL, CARD_TOKEN, BANK_TOKEN. Yes/No (not required for PAYMENT_WALL)
authorizationCode Optional, usage differs depending on payment method. For BLIK integrated transparently: enables to collect 6-digit BLIK code on your website instead of redirecting to BLIK. See more about transparent integration. For Visa Checkout integrated transparently: carries callId param. See more about Visa Checkout. No

<mcpData> fields description

Parameters Description Required
mcpCurrency "termCurrency" from the rate table. Yes
mcpAmount "baseCurrency" amount converted to termCurrency. Yes
mcpRate Applied conversion rate. Yes
mcpFxTableId Applied FX rate table id. Yes
mcpPartnerId Id provided by PayU. Yes

<buyer> section fields description

Parameter Description Required
customerIp Customer's IP address No
extCustomerId ID of the customer used in merchant system No
email Buyer's email address Yes
phone Buyer's telephone number No
firstName Buyer's first name No
lastName Buyer's last name No
nin National Identification Number No
language Buyer's language - determines language version of the payment page. For a list of accepted language values, see section Language values No
buyer.delivery Section containing delivery address. For a list of parameters, see section <buyer.delivery> No

<buyerDelivery> fields description

Parameter Description Required
street Street Yes
postalBox Postal box No
postalCode Postal code Yes
city city Yes
state State No
countryCode Country code Yes
name Address description No
recipientName Recipient name Yes
recipientEmail Recipient email No
recipientPhone Recipient phone number No

<order> fields description

Parameter Description
orderId Order ID generated by the PayU system
extOrderId External order ID (assigned by the shop)
orderCreateDate Order creation timestamp
notifyUrl Address for sending notifications
orderUrl URL of order
customerIp Customer's IP address
merchantPosId Point of sale ID
description Description for order
validityTime Duration for the validity of an order (in seconds), during which time payment must be made
currencyCode Currency code (e.g PLN, EUR)
totalAmount Total price of the order
buyer Section containing buyer data. For a list of parameters, see section <buyer>
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>

<status> section fields description

Parameter Description
statusCode Response code
statusDesc Response status description

9.5 Form parameters

This section details all parameters (both required and optional) supported by the payment form.

General parameters

Parameter Required Description
customerIp Yes Payer’s IP address, e.g. 123.123.123.123
extOrderId No Order identifier assigned by the merchant. It enables merchants to find a specific order in their system
merchantPosId Yes POS identifier
description Yes Order description
currencyCode Yes Order currency compliant with ISO 4217, e.g. PLN
totalAmount Yes The entire order value specified in the lowest currency unit, e.g. for PLN “1000” is equal to 10 PLN. HUF is the exception, this must be multiplied by 100
OpenPayu-Signature Yes Parameter signature. For more information, see section

URL addresses

Parameter Required Description
continueUrl No URL to which a user will be redirected if an error occurs while placing an order. The following parameters may be sent:
  • status - error code,
  • desc - error description,
  • field - patch indicating a field to which the error refers
notifyUrl No URL to which notifications of a changed order status will be sent

Buyer

The buyer section stores basic information about the buyer. This information is not required.

Parameter Required Description
buyer.email Yes Buyer’s e-mail address
buyer.phone Yes Buyer’s phone number
buyer.firstName Yes Buyer’s first name
buyer.lastName Yes Buyer’s surname

Shipping address

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

Parameter Required Description
buyer.delivery.street Yes Street name
buyer.delivery.postalBox No Postal box number
buyer.delivery.postalCode Yes Postal code
buyer.delivery.city Yes City
buyer.delivery.state No Province
buyer.delivery.countryCode Yes Two-letter country code compliant with ISO-3166
buyer.delivery.name No Address description
buyer.delivery.recipientName Yes Recipient’s name
buyer.delivery.recipientEmail No Recipient’s e-mail address
buyer.delivery.recipientPhone No Recipient’s phone number

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

Parameter Required Description
products[0].name Yes Product name
products[0].unitPrice Yes Product unit price
products[0].quantity Yes Quantity of products

9.6 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.
In case you need to contact PayU technical support to investigate some unsuccessful API call, please use tech@payu.pl address and provide the value of Correlation-Id header returned in the response.
Status codes
HTTP Status Code Status code Description
200 OK SUCCESS Request has been processed correctly.
201 OK 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).
WARNING_CONTINUE_REDIRECT Request has been processed correctly. redirectUri is provided in the response 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.
WARNING_CONTINUE_3DS 3DS authorization is required. Redirect the buyer to perform 3DS authentication process.
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.
ERROR_VALUE_INVALID One or more required values are incorrect
ERROR_VALUE_MISSING One or more required values are missing
ERROR_ORDER_NOT_UNIQUE Order already exists. This error may be caused by a not unique extOrderId parameter.
401 Unauthorized UNAUTHORIZED Incorrect authentication. Check signature parameters and implementation of the signature algorithm
403 Forbidden UNAUTHORIZED_REQUEST No privileges to perform the request
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
ERROR_INTERNAL PayU system is unavailable. Try again later
GENERAL_ERROR Unexpected error. Try again later
WARNING Minor unexpected error. Try again later
503 Service unavailable SERVICE_NOT_AVAILABLE PayU system is unavailable. Try again later

9.7 Available language versions

This section details the language settings for the payment form.

General language parameters

Use these parameters to define the language version of the standard payment page, in the event that no payment method was defined.

Value Language
pl Polish
en English
cs Czech

Card payment form parameters

Below languages apply to the PayU-hosted card form. They are applied automatically, basing on payer's browser settings. The default language (used when PayU does not support particular language) is English.

Value Card form language
bg Bulgarian
de German
ee Estonian
el Greek
es Spanish
fi Finnish
fr French
hr Croatian
hu Hungarian
it Italian
lt Lithuanian
lv Latvian
pt Portuguese
ro Romanian
ru Russian
sk Slovak
sl Slovenian
uk Ukrainian

Legal disclaimers

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

9.8 Card status codes

List of card status codes sent by the PayU system, 3-D Secure codes.
Card transaction response codes:
CardResponseCode CardResponseCodeDesc Reason(*) Additional information
000 000 - OK
S01 S01 - Refer to card issuer Bank
S04 S04 - Pickup card Bank
S05 S05 - Do not honor Bank Ask yor Customer to call the bank and clear up any problems that are causing the card to be declined.
S12 S12 - Invalid transaction Bank
S13 S13 - Invalid amount Bank Currency conversion field overflow or amount exceeds maximum for Card program.
S30 S30 - Message format error Bank
S43 S43 - Pickup card (stolen card) Bank
S51 S51 - Insufficient funds Bank Not enough funds or attempt to exceed limits (at the bank side).
S54 S54 - Expired card Bank Card is expired or Customer made a mistake giving card dates.
S62 S62 - Restricted card / Country exclusion table Bank
S90 S90 - Destination not available Bank
S93 S93 - Card disabled for e-commerce transactions Bank
S99 S99 - authorization error – default Bank
SN0 SN0 - Unable to authorize / Force STIP Bank
SP9 SP9 - Enter lesser amount Bank
ST3 ST3 - Card not supported Bank
ST8 ST8 - Invalid account Bank
114 114 - 3ds authentication error Check 3ds status.
222 222 - Transaction not received by merchant Merchant Merchant has not received transaction; status possible when auto-receive option is off.
001, 002, 003, 004, 005, 110, 111, 112, 113, 121, 122, 221, 223 different messages PayU Contact PayU for details
(*) Reason shows which side stopped the transaction and who should be contacted to give more information about the source of problem.

ECI (Electronic Commerce Indicator) response codes:
cardEciCode Additional information
0 Transaction processed without 3DS call (MasterCard).
1 Authentication attempt (MasterCard). The issuer does not participate in the verification or the card is not eligible for authentication.
2 Full authentication (MasterCard).
5 Full authentication.
6 Authentication attempt (MasterCard). The issuer does not participate in the verification or the card is not eligible for authentication.
7 Transaction processed without 3DS call.

Card 3Ds statuses:
card3DsStatus Additional information
AY 3DS result: success.
AN Authentication attempt. The issuer does not participate in the verification or the card is not eligible for authentication.
A0 Error on the card organization side.