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

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

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": "pl"
        },
        "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"
        },
        "products": [
            {
                "name": "Wireless Mouse for Laptop",
                "unitPrice": "15000",
                "quantity": "1"
            },
            {
                "name": "HDMI cable",
                "unitPrice": "6000",
                "quantity": "1"
            }
        ]
    }'

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

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

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

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

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:

Attempt Time since the change od payment's status
1 immediately
2 1 minute
3 2 minutes
4 5 minutes
5 10 minutes
6 30 minutes
7 1 hour
8 2 hours
9 3 hours
10 6 hours
11 9 hours
12 12 hours
13 15 hours
14 18 hours
15 21 hours
16 24 hours
17 36 hours
18 48 hours
19 60 hours
20 72 hours

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

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"
                   }
                }
            
Two statuses can be returned via this notification:
  • FINALIZED - refund was completed successfully,
  • CANCELED - refund was cancelled.

4 Refunds

4.1 Creating Refund

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

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"
                        }
                    }'
            
For information on the supported authentication methods, see section: Signing API calls parameters

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.

StatusCode CodeLiteral Code Description
ERROR_VALUE_MISSING MISSING_REFUND_SECTION 8300 Request lacks "refund" object.
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
OPENPAYU_BUSINESS_​ERROR TRANS_TOO_​OLD 9114 The available time for refund has passed.
OPENPAYU_ERROR_VALUE_​INVALID REMAINING_TRANS_​AMOUNT_TOO_SMALL 9115 Transaction amount that remains after refund creation will be too small to make another refund.

4.2 Retrieving refund data

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:

ErrorCode ErrorCodeDescription Procedure for merchant
BANK_DECLINED Bank rejected refund. Please register a refund again. If the error occurs repeatedly please contact PayU support so that a refund to a bank account can be registered.
PROVIDER_DECLINED Provider rejected refund. Please register a refund again. If the error occurs repeatedly please contact PayU support so that a refund to a bank account can be registered.
PROVIDER_LIMIT_ERROR Some limit was exceeded on Provider side Please register a refund again. If the error occurs repeatedly please contact PayU support.
PROVIDER_SECURITY_ERROR Some security rule was broken Please register a refund again. If the error occurs repeatedly please contact PayU support.
PROVIDER_TECHNICAL_ERROR Temporary problem on Provider Side. Please register a refund again. If the error occurs repeatedly please contact PayU support.
BANK_UNAVAILABLE_ERROR Bank supplied by provider is temporary unavailable. Please register a refund again after some time.
REFUND_TOO_LATE Time to register refund was exceeded. Please contact PayU support so that a refund to a bank account can be registered.
TECHNICAL_ERROR Some technical problem occured. Please contact PayU support.
REFUND_TOO_FAST Provider cannot permit to register too many refunds in given period of time. Please register a refund again after some time.
REFUND_IMPOSSIBLE Provider permanently rejected refund. Please contact PayU support so that a refund to a bank account can be registered.

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

6 Order capture

You can capture or cancel orders with the status WAITING_FOR_CONFIRMATION 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.

To enable WAITING_FOR_CONFIRMATION status, payment methods on your POS need to have auto-receive turned off. Otherwise, all successful payments for an order will automatically trigger COMPLETED status.

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 and Transactions (payments) or shop data 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"
                                    },
                                    "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.

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.

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

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 any of below fields
            "city":"WARSZAWA",
            "postalCode":"02-638",
            "street":"UL.NOWOWIEJSKIEGO 8",
            "address":"Warszawa Nowowiejskiego 8"
         }
      }
   ]
}
                

7.3 Retrieving shop data

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.

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

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

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'. If not specified it will be set by default to 'pl'.

.
Sample request (production):
curl -X GET https://secure.payu.com/api/v2_1/paymethods \
    -H "Authorization: Bearer 87ad751f-7ea5-4023-a16f-04b6647a07f5" 
    -H "Cache-Control: no-cache" 
            
Sample request (sandbox):
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

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

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

Language Information Text
cs Payment Order info not applicable
cs PayU Payment Terms not applicable
cs PayU Privacy Policy Správcem vašich osobních údajů je společnost PayU S.A. se sídlem v Poznani (60-166), ul. Grunwaldzka 186, Polsko. Vaše osobní údaje budeme zpracovávat proto, abychom mohli provést platební transakci, informovali Vás o jejím stavu, mohli vyřídit případnou reklamaci a také abychom splnili zákonné povinnosti, které jako společnost PayU máme.
Subjekty, které spolupracují se společností PayU na realizaci platebních transakcí, se také mohou stát příjemci Vašich osobních údajů. V závislosti na platební metodě, kterou jste si vybrali, to mohou být: banky, platební instituce, úvěrové instituce, organizace pro platební karty, platební modely), dále subjekty, které podporují činnost PayU, tj. dodavatelé IT infrastruktury, dodavatele nástrojů pro analýzu rizika plateb, a dále subjekty, které jsou oprávněné je získat na základě platných právních předpisů, včetně příslušných orgánů činných v trestním řízení. Vaše údaje můžeme zpřístupnit Partnerům, abychom je informovali o průběhu realizace platby.
Máte právo přistupovat k Vašim osobním údajům, opravovat je, omezit jejich zpracování, vznést námitku proti jejich zpracování, omezit automatizované individuální rozhodování, včetně profilování, a přenášet je nebo odstranit. Vaše osobní údaje nám poskytujete dobrovolně. Mějte však na paměti, že jejich uvedení je nezbytné pro provedení platby a že bez nich může dojít k jejímu odmítnutí. Více informací o pravidlech pro zpracování Vašich osobních údajů u nás v PayU naleznete zde v zásadach ochrany osobních údajů.
en PayU Payment Terms By paying you accept "PayU Payment Terms".
en Data Privacy Policy 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 https://static.payu.com/sites/terms/files/payu_privacy_policy_en_en.pdf.
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 PayU Payment Terms Akceptuję "Regulamin pojedynczej transakcji płatniczej PayU".
pl Data privacy policy Administratorem Twoich danych osobowych jest PayU S.A. z siedzibą w Poznaniu (60-166), przy ul. Grunwaldzkiej 186. Twoje dane osobowe będą przetwarzane w celu realizacji transakcji płatniczej, powiadamiania Cię o statusie realizacji Twojej płatności, rozpatrywania reklamacji, a także w celu wypełnienia obowiązków prawnych ciążących na PayU.
sk Data privacy policy Administrátorom Vašich osobných údajov je PayU S.A. so sídlom v Poznani (60-166), ul. Grunwaldzka 186. Vaše osobné údaje budú spracované za účelom realizácie platobnej transakcie, informovania Vás o stave realizácie Vašej platby, vybavovania reklamácie, a taktiež za účelom splnenia právnych povinností nachádzajúcich sa na strane PayU.
Príjemcami Vašich osobných údajov môžu byť subjekty spolupracujúce s PayU počas realizácie platby. V závislosti od Vami zvolenej platobnej metódy to môžu byť: banky, platobné inštitúcie, pôžičkové inštitúcie, organizácie platobných kariet, platobné schémy), okrem toho subjekty podporujúce činnosť PayU, t. j. dodávatelia infraštruktúry IT, dodávatelia nástrojov na analýzu rizika platby, a taktiež subjekty oprávnené na ich prijímanie na základe platných právnych predpisov, vrátane príslušných justičných orgánov. Vaše údaje môžu byť sprístupnené príjemcom, aby boli informovaní o stave realizácie platby.
Máte právo na prístup k údajom, a taktiež na ich opravu, obmedzenie ich spracovania, oznámenie nesúhlasu voči ich spracovaniu, nepodliehaniu zautomatizovanému individuálnemu rozhodovaniu, vrátane profilovania ako aj prenosu a odstránenia údajov. Uvedenie údajov je dobrovoľné, ale potrebné na realizáciu platby, neposkytnutie údajov môže mať vplyv na odmietnutie platby. Viac informácií o pravidlách spracovania Vašich osobných údajov zo strany PayU nájdete tu.

8.3 Card payments

There are several options to process card payments via PayU.

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.

9 References

9.1 Signing API calls

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:

Parameter Required for Description
grant_type client_credentails, trusted_merchant Authorization mode.
client_id client_credentails, trusted_merchant Merchant's POS identifier in PayU's system. Can be found in PayU's merchant panel.
client_secret client_credentails, trusted_merchant Merchant's secret key. Can be found in PayU's merchant panel.
email trusted_merchant Customer's email address in merchant's system.
ext_customer_id trusted_merchant Customer's identifier in the merchant's system.

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

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 in the lowercase,
  • 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:

  • 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

Form values to be signed:
                    <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">
                
Sort all form params alphabetically by param name and concatenate key-value pairs according to the sort order, separating them with ampersand & adding your private key (available in the Panel as Second key (MD5)):
                    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
                
The above value should be hashed with SHA-256:
                    565f9f4dda43c8e24ccab4472133d680e2aa58e1f58bea845c4cf2926965144d
                
Form param with the signature:
                    <input name="OpenPayu-Signature" value="sender=145227;algorithm=SHA-256;signature=565f9f4dda43c8e24ccab4472133d680e2aa58e1f58bea845c4cf2926965144d">
                

In case of further questions, please contact us.

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

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

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
localReceiptDateTime Moment of accepting the transaction and adding funds from the transaction to the Shop balance. Format: "%Y-%M-%DT%h:%m:%s%z." Example: "2020-06-09T17:52:04.644+02:00". If the millisecond counter is "000" then milliseconds are not sent and the format changes to: "%Y-%M-%DT%h:%m:%s". Is present only for the status "COMPLETED".
properties Array of objects related to transaction identification. In case of statuses:
  • "WAITING_FOR_CONFIRMATION" and "COMPLETED" - Contains one element with two parameters: name and value,
  • "PENDING" - may contain object with aforementioned parameters or it can be empty.
.
properties.name Static value. The payment identifier, displayed on transaction statements as "Trans ID" and within the transaction search option in the Management Panel.
properties.value Transaction ID in PayU system (data type - string).

OrderStatusUpdateRequest - fields description

Parameter Description Required
orderId Order id in PayU system Yes
orderStatus New order status. Possible values are:
  • NEW
  • PENDING
  • CANCELED
  • 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 compliant with ISO 4217 (e.g 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 compliant with ISO 4217 (e.g 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 - fields description

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
properties Array of objects related to transaction identification. In case of statuses:
  • "WAITING_FOR_CONFIRMATION" and "COMPLETED" - Contains one element with two parameters: name and value,
  • "PENDING" - may contain object with aforementioned parameters or it can be empty.
.
properties.name Static value. The payment identifier, displayed on transaction statements as "Trans ID" and within the transaction search option in the Management Panel.
properties.value Transaction ID in PayU system (data type - string).

TransactionRetrieveRequest

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

Parameters Description Required
orderId Order identifier to which the given transaction was made. Yes

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.

Parameters Description
payMethod.value Chosen payment method.
bankAccount.number Bank account number from which payment was made.
bankAccount.name Name of the account holder from which payment was made (or full data – name, surname and address).
resultCode Optional informaction about transaction result code. Possible values:
  • AUT_ERROR_NO_AUTHORIZATION - authorization was not received, transaction cancelled.
  • AUT_ERROR_ANTIFRAUD_DECLINED - transaction rejected at the authoriztion stage by the antifraud system.
  • REG_ERROR_ANTIFRAUD_DECLINED - transaction rejected at registration stage by antifraud system.

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

bankAccount.address Account holder address.
bankAccount.city City included in account holder address.
bankAccount.postalCode Postal code included in account holder address.
bankAccount.street Street name and house number included in account holder address.

TransactionRetrieveResponse - for cards

Parameters Description
payMethod.value Chosen payment method.
paymentFlow Possible values:
  • CARD - card payment on PayU hosted payment page,
  • MASTERPASS, VISA_CHECKOUT, APPLE_PAY, GOOGLE_PAY, GOOGLE_PAY_TOKENIZED - card payment taken from appropriate external service (in case of APPLE_PAY and GOOGLE_PAY_TOKENIZED card was tokenized by Visa/MasterCard, i.e. cardNumberMasked field does not contain real card number),
  • ONE_CLICK_CARD - card payment with card saved in PayU,
  • ONE_CLICK_CARD_RECURRING - recurring payment with card saved in PayU,
  • FIRST_ONE_CLICK_CARD - payment which saves card in PayU.
card.cardData.cardNumberMasked Masked card number (real number or token - in case of Apple Pay and Google Pay Tokenized).
card.cardData.cardScheme Payment organization: MC (MasterCard/Maestro), VS (Visa).
card.cardData.cardProfile Card profile (CONSUMER lub BUSINESS).
card.cardData.cardClassification Card classification (CREDIT/DEBIT)
card.cardData.cardBinCountry Country in which card was issued. Two-letter country code compliant with ISO-3166.
card.cardData.firstTransactionId Identifier of the first of recurring payments or Card-on-File, granted by the payment organisation.
resultCode Optional informaction about transaction result code. Possible values:
  • AUT_ERROR_NO_AUTHORIZATION - authorization was not received, transaction cancelled.
  • AUT_ERROR_ANTIFRAUD_DECLINED - transaction rejected at the authoriztion stage by the antifraud system.
  • REG_ERROR_ANTIFRAUD_DECLINED - transaction rejected at registration stage by antifraud system.
card.cardData.cardResponseCode Response code. Explanation is available here
card.cardData.cardResponseCodeDesc Response code with description.
card.cardData.cardEciCode Electronic Commerce Indicator. Explanation is available here.
card.cardData.card3DsStatus 3DS verification status. Explanation is available here.
card.cardData.card3DsFrictionlessIndicator Indicates whether the authentication was frictionless or with challenge. Explanation is available here.
card.cardData.card3DsStatusDescription Description of 3DS status.Explanation is available here.

Common sections

Product

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, ISO format applies, e.g. "2019-03-27T10:57:59.000+01:00". No

payMethod object in OrderCreateRequest.

Parameters Description Required
type Payment method type, possible values:
  • PBL (payment requires redirection)
  • CARD_TOKEN
  • PAYMENT_WALL (payment requires redirection)
Yes
value Payment type for PBL, CARD_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

payMethod object in notification.

Parameters Description
type Payment method type, possible values:
  • PBL (payment requires redirection)
  • CARD_TOKEN
  • PAYMENT_WALL (payment requires redirection)
amount Payment amount. Field is not guaranteed to appear.

mcpData

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

The buyer section stores basic information about the buyer. 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.
Parameter Description Required
extCustomerId ID of the customer used in merchant system No
email Buyer's email address Yes – for Installments (PL), Pay Later (PL), Pay Later with Twisto (CZ) and 3DS 2 authentication.
phone Buyer's telephone number. Please use +[country code] [number] format, e.g. +48 225108001 Yes - for Pay Later with Twisto (CZ) and 3DS 2 authentication.
firstName Buyer's first name Yes - for Pay Later with Twisto (CZ)
lastName Buyer's last name Yes - for Pay Later with Twisto (CZ)
nin National Identification Number No
language Language code, ISO-639-1 compliant. Denotes the language version of PayU hosted payment page and of e-mail messages sent from PayU to the payer (supported values are here) No
delivery Section containing delivery address. For a list of parameters, see section delivery No, recommended for 3DS 2 authentication.

delivery

Parameter Description Required
street Full street address, incl. apartment number. No - recommended for 3DS 2 authentication
postalBox Postal box No
postalCode Postal code No - recommended for 3DS 2 authentication
city city No - recommended for 3DS 2 authentication
state Country principal subdivision like "state" or "province". If provided, must be a valid ISO 3166-2 code (e.g. "UT" for Utah in the USA or "30" for "Wielkopolskie" in Poland). No - recommended for 3DS 2 authentication
countryCode Two-letter country code compliant with ISO-3166. No - recommended for 3DS 2 authentication
name Address description No
recipientName Recipient name No
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
customerIp Customer's IP address, e.g. 123.123.123.123. Note: 0.0.0.0 is not accepted.
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. Default value 86400.
currencyCode Currency code compliant with ISO 4217 (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

OrderCreateRequest - threeDsAuthentication object

Parameter Description Required
challengeRequested Merchant's preference regarding 3DS 2 challenge. Exclusive with exemption. Maybe overridden by PayU. Possible values: YES, NO, MANDATE. No
exemption Merchant's preference regarding SCA exemption to be used to exempt card payment from 3DS authentication. Exclusive with challengeRequested. Requires additional configuration to be enabled. For a list of parameters, see exemption. No
browser Browser data required for 3DS 2 browser flow. If not provided, these data will be collected by PayU. It is strongly recommended to include it when charging a stored card (multi-use token), because in some cases it will spare you redirection to PayU's authentication page. For a list of parameters, see browser. No, recommended
sdk Required if 3DS 2 is to be natively supported in your mobile app. Content needs to be generated by a certified 3DS 2 SDK. This information is not required, but it is strongly recommended to include it when charging a stored card (multi-use token). For a list of parameters, see sdk. Yes (if 3DS 2 SDK used)
merchantRiskIndicator Set of fields helping to assess risk connected with the order itself (type of goods purchased, shipping method etc.). For a list of parameters, see merchantRiskIndicator. No
recurring Additional information in case of a recurring payment. For a list of parameters, see recurring. No
cardholder Describes cardholder's account data in merchant's possession, including details of account run for the cardholder in merchant's system. For a list of parameters, see cardholder. No, recommended

threeDsAuthentication.browser fields description.

Parameters Description Required
acceptHeaders Exact content of the HTTP accept headers as sent from the payer's browser. Yes
requestIP IP address of the browser as returned by the HTTP headers. Yes
screenWidth Total width of the payer's screen in pixels. Obtained from the screen.width HTML DOM property. Yes
javaEnabled Obtained from the navigator HTML DOM object. Yes
timezoneOffset Obtained from the getTimezoneOffset() method applied to Date object. Yes
screenHeight Obtained from the navigator HTML DOM object. Yes
userAgent Exact content of the HTTP user-agent header. Yes
colorDepth Obtained from payer's browser using the screen.colorDepth HTML DOM property. Yes
language Obtained from payer's browser using the navigator.language HTML DOM property. Max. 8 chars. Yes

threeDsAuthentication.exemption fields description.

Parameters Description Required
value Either LOW_RISK (also known as TRA - transaction risk analysis compliant with SCA requirements has been performed by the merchant) or LOW_VALUE (low value payment, up to 30 EUR or equivalent in other currency). Yes
rejectionHandling Either PERFORM_AUTHENTICATION (PayU will return response with WARNING_CONTINUE_3DS and redirection URL code if exemption cannot be applied) or DECLINE (PayU will decline the payment if exemption cannot be applied - error message will be returned synchronously in OrderCreateResponse). Yes
riskScore Risk score assigned by merchant's antifraud tool. A string up to 128 chars. For informative purposes only. No

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

Parameters Description Required
sdkReferenceNumber Example: DS_LOA_SDK_ADBV_739485_94783 Yes
sdkMaxTimeout Indicates the maximum amount of time (in minutes) for all exchanges. The field shall have value greater or equal to 05. Yes
sdkAppID Example: 9063b12c-fcde-43c7-b28e-8d0af5520e8a Yes
sdkEncData Data encrypted by the 3DS SDK. Yes
sdkTransID Example: b60c9879-ac77-4918-a317-7b01c4317053/8Q==.. Yes
sdkEphemPubKey Public key component of the ephemeral key pair generated by the 3DS SDK and used to establish session keys between the 3DS SDK and the issuer. Yes

threeDsAuthentication.merchantRiskIndicator fields description.

Parameters Description Required
orderType Possible values:
  • PURCHASE,
  • ACC_FUNDING,
  • QUASI-CASH,
  • LOAN.
No
shipIndicator Indicates shipping method chosen for the order. Possible values:
  • BILLING_ADDRESS,
  • VERIFIED_ADDRESS,
  • OTHER_ADDRESS,
  • SHIP_TO_STORE,
  • DIGITAL_GOODS,
  • TICKETS,
  • NOT_SHIPPED.
No
preOrdered Indicates order for merchandise with a future availability or release date.

Data Type: boolean.
No
preOrderDate ISO format applies, e.g. "2019-03-27T10:57:59.000+01:00". No
deliveryTimeFrame Possible values:
  • ELECTRONIC,
  • SAME_DAY,
  • OVERNIGHT,
  • TWO_OR_MORE_DAYS.
No
reordered Indicates if the same purchase has been ordered again.

Data Type: boolean.
No
merchantFunds Indicates whether merchant's own funding (e.g. a gift card) has been used to partially pay for the order. Sum of amounts provided here and of "totalAmount" field denote the real value of order in merchant's system. Object consisting of two fields: amount (in pennies) and currencyCode (ISO code). No

threeDsAuthentication.recurring fields description.

Parameters Description Required
frequency Minimum number of days between recurring payments (e.g. 7 for a weekly cycle). According to recommendation by the card schemes, in case of recurring payments with a variable frequency value "1" should be used. No
expiry Date after no further recurring payments will be performed. ISO format applies, e.g. "2025-03-27T00:00:00.000Z". According to recommendation by the card schemes, in cases like subscriptions, where there is no established expiry or end date of recurring transactions value "9999-12-31T00:00:00Z" should be used. No

threeDsAuthentication.cardholder fields description.

Parameters Description Required
name Cardholder name and surname. No
accountInformation Object. For a list of parameters, see accountInformation. No
billingAddress Object. For a list of parameters, see billingAddress. No

threeDsAuthentication.cardholder.accountInformation fields description.

Parameters Description Required
createDate Date when the account has been created for the cardholder. ISO format applies, e.g. "2019-03-27T10:57:59.000+01:00". No
suspiciousActivity Indicates whether merchant has experienced suspicious/fraudulent activity for this account. Boolean. No
deliveryAddressFirstUsedDate Date when the shipping address used for this order was first used. ISO format applies, e.g. "2019-03-27T10:57:59.000+01:00". No
deliveryAddressUsageIndicator Indicates when this shipping address was first used. Possible values:
  • THIS_TRANSACTION,
  • LESS_THAN_30_DAYS,
  • 30_TO_60_DAYS,
  • MORE_THAN_60_DAYS.
No
pastOrdersYear Orders created in merchant's system for this account in the past 12 months (number within 1-9999 range). No
pastOrdersDay Orders created in merchant's system for this account in the last 24 hours (number within 1-9999 range). No
purchasesLastSixMonths Fulfilled (successful) orders created in merchant's system for this account in the past 6 months (number within 1-9999 range). No
changeDate Date when account details were last changed. ISO format applies, e.g. "2019-03-27T10:57:59.000+01:00". No
changeIndicator Indicates time when account information was last changed. Possible values:
  • THIS_TRANSACTION,
  • LESS_THAN_30_DAYS,
  • 30_TO_60_DAYS,
  • MORE_THAN_60_DAYS.
No
passwordChanged Date when account password was last changed. ISO format applies, e.g. "2019-03-27T10:57:59.000+01:00". No
passwordChangeIndicator Indicates whether and when the password was last changed. Possible values:
  • NO_CHANGE,
  • THIS_TRANSACTION,
  • LESS_THAN_30_DAYS,
  • 30_TO_60_DAYS,
  • MORE_THAN_60_DAYS.
No
nameToRecipientMatch Indicates whether cardholder's name matches recipient's name. Boolean. No
addCardAttemptsDay Indicates attempts to add a card to cardholder's account in merchant's system within last 24 hours. No
authMethod Authentication method used to recognize cardholder. Possible values: GUEST, LOGIN, FEDERATED_ID, THIRD_PARTY, ISSUER, FIDO. No
authDateTime Date and time when authentication was performed. ISO format applies, e.g. "2019-03-27T10:57:59.000+01:00". No
cardAddedDate Date when card account has been stored with merchant. ISO format applies, e.g. "2019-03-27T10:57:59.000+01:00". No
cardAddedIndicator Indicates if and when the card was stored with merchant. Possible values:
  • GUEST,
  • THIS_TRANSACTION,
  • LESS_THAN_30_DAYS,
  • 30_TO_60_DAYS,
  • MORE_THAN_60_DAYS.
No

threeDsAuthentication.cardholder.billingAddress fields description.

Parameters Data Type Description Required
street STR {1,50} Full street address, incl. apartment number. No
postalCode STR {1,16} Postal/ZIP code. No
city STR {1,50} City name. No
state STR {1,3} Country principal subdivision like "state" or "province". If provided, must be a two-letter country code compliant with ISO-3166 (e.g. "UT" for Utah in the USA or "30" for "Wielkopolskie" in Poland). No
countryCode STR {1,2} Two-letter country code compliant with ISO-3166, e.g. "CZ", "PL" or "US". No

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..
Parameters Description Required
credit.shoppingCarts Section containing data of the ordered products. Section <credit.shoppingCarts> is an array of objects of type shoppingCart. For a list of parameters, see section <shoppingCart>. No
credit.applicant Section containing data of person applying for a credit. For a list of parameters, see section <applicant>. No

shoppingCart fields description

Parameters Description Required
shippingMethod Section containing data of shipping method. Section <shippingMethod> is a single object of type shippingMethod. For a list of parameters, see section <shippingMethod>. No, but recommended
products Section containing data about ordered products. Section <products> is an array of objects of type product. For a list of parameters, see section <product> (Note: product objects in the <shoppingCart.products> section do not have a listingDate field) No, but recommended
extCustomerId Submerchant identifier. This field should be consistent with field extCustomerId in shoppingCarts section when order is placed in marketplace. Required when order is placed in marketplace and credit section is sent.

shippingMethod fields description

Parameters Description Required
type

Type of shipment, possible values are:

  • COURIER
  • COLLECTION_POINT_PICKUP
  • PARCEL_LOCKER
  • STORE_PICKUP
No, but recommended
price Shipping cost No, but recommended
address Section containing data about shipping address. Section <shippingMethod.address> is a single object of type address. For a list of parameters, see section <address>. No, but recommended

address fields description

Parameters Description Required
pointId The full name of the pickup point, including its unique identifier, e.g. „Parcel locker POZ29A”. No
street Street name, possibly including house and flat number. No, but recommended
streetNo Street number No, but recommended
flatNo Flat number No, but recommended
postalCode Postal code No, but recommended
city City No, but recommended
countryCode Two-letter country code compliant with ISO-3166. No, but recommended

credit.applicant fields description

Parameters Description Required
email Applicant’s email address No, but recommended
phone Applicant’s phone number No, but recommended
firstName Applicant’s first name No, but recommended
lastName Applicant’s last name No, but recommended
language KLanguage code, ISO-639-1 compliant. Denotes the language version of PayU hosted payment page and of e-mail messages sent from PayU to the payer (supported values are here). No, but recommended
nin National Identification Number No, but recommended
address Section containing data about applicant’s address. Section <applicant.address> is a single object of type address For a list of parameters, see section <address>. (uwaga: obiekt typu address w sekcji <applicant> nie posiada pola pointId) No, but recommended
additionalInfo

Additional information about person applying for credit.

For a list of parameters, see section <applicant.additonalInfo>.
No, but recommended

credit.applicant.additionalInfo fields description

Parameters Description Required
hasSuccessfullyFinishedOrderInShop Information whether there were previous, successfully completed orders for applicant. No, but recommended

9.5 Form parameters

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

General parameters

We recommend to not use special characters in transaction description. Certain characters are not allowed by the banks.
Parameter Required Description
customerIp Yes Payer’s IP address, e.g. 123.123.123.123. Note: 0.0.0.0 is not accepted.
extOrderId No 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.
merchantPosId Yes POS identifier.
description Yes Order description.
additionalDescription No Additional description of the order.
visibleDescription No Text visible on the PayU payment page (max. 80 chars).
statementDescription No 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.
currencyCode Yes Currency code compliant with ISO 4217 (e.g EUR).
totalAmount Yes 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).
OpenPayu-Signature Yes Parameter signature. For more information, see section 7.1 and 7.2

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

The buyer section stores basic information about the buyer. 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.
Parameter Required Description
buyer.email No Buyer’s e-mail address
buyer.phone No Buyer’s phone number
buyer.firstName No Buyer’s first name
buyer.lastName No Buyer’s surname
buyer.language No Denotes the language version of PayU hosted payment page and of e-mail messages sent from PayU to the payer (supported values are here)

Shipping address

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

Parameter Required Description
buyer.delivery.street No Street name
buyer.delivery.postalBox No Postal box number
buyer.delivery.postalCode No Postal code
buyer.delivery.city No City
buyer.delivery.state No Province
buyer.delivery.countryCode No Two-letter country code compliant with ISO-3166.
buyer.delivery.name No Address description
buyer.delivery.recipientName No 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 for PayU technical support to investigate some unsuccessful API call, please contact us 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 Created SUCCESS Order with payMethods array with card token or BLIK auth code has been created.
302 Found SUCCESS Request has been processed correctly. redirectUri is provided in the response Location header and in the response body (in JSON payload).
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_INVALID (statusDesc: INVALID_BLIK_CODE) BLIK authorization code must have 6 digits.
ERROR_VALUE_INVALID (statusDesc: OPENPAYU_PAYMENT_CREATE_ BLOCKED_CHECKOUT_PAY_METHOD) Chosen payment method is currently unavailable.Payment methods availability can be checked by using Payment methods retrieval.
ERROR_VALUE_INVALID ("codeLiteral": "SINGLE_CLICK_DISABLED") Card token storing service is not available.
ERROR_VALUE_INVALID ("codeLiteral": "SINGLE_CLICK_RECURRING_DISABLED") Recurring payments service not available.
ERROR_VALUE_INVALID (statusDesc: General MCP processing error) General MCP processing error.
ERROR_VALUE_INVALID (statusDesc: Fx Rate Table is outdated) Fx Rate Table specified by mcpFxTableId is outdated.
ERROR_VALUE_INVALID (statusDesc: MCP is not supported for merchant) MCP is not supported for merchant.
ERROR_VALUE_INVALID (statusDesc: Rate is null) Field mcpRate is empty.
ERROR_VALUE_INVALID (statusDesc: Fx Table Id is null) Field mcpFxTableId is empty.
ERROR_VALUE_INVALID (statusDesc: Amount is null) Field mcpAmount is empty.
ERROR_VALUE_INVALID (statusDesc: Currency is null) Field mcpCurrency is empty.
ERROR_VALUE_INVALID (statusDesc: Partner Id is null) Field mcpPartnerId is empty.
ERROR_VALUE_INVALID (statusDesc: Invalid currency pair for given Fx Table) Invalid currency pair specified by mcpCurrency and currencyCode for given Fx Table.
ERROR_VALUE_INVALID (statusDesc: Invalid rate value for given Fx Table) Invalid rate value specified by mcpRate for given Fx Table.
ERROR_VALUE_INVALID (statusDesc: Invalid amount value for given Fx Table (amount was not calculated properly)) Invalid amount value specified by mcpAmount for given Fx Table, amount was not calculated properly.
ERROR_VALUE_INVALID (statusDesc: Currency is not supported) Currency specified by mcpCurrency is not supported.
ERROR_VALUE_INVALID (statusDesc: Wrong params. You're trying to send MIT/Recurring request for non-verified first Payment) MIT/recurring payment attempt with a token that has not been fully authenticated with 3DSecure. With a given token, depending on the payment type, you must first make a payment with the appropriate parameter: MIT (cardOnFile=FIRST), recurring (recurring=FIRST).
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.
ERROR_INTERNAL ("codeLiteral": "CARD_CARD_EXPIRED") Card expired.
BUSINESS_ERROR ("codeLiteral": "ERROR_VALUE_INVALID" | “statusDesc”:”Order was rejected by antifraud system.”) Order was rejected by antifraud system.
401 Unauthorized UNAUTHORIZED Incorrect authentication. Check signature parameters and implementation of the signature algorithm
403 Forbidden UNAUTHORIZED_REQUEST No privileges to perform the request
ERROR_VALUE_INVALID ("codeLiteral": "INVALID_AUTH_FOR_THIS_ORDER") POS ID parameter in OAuth request does not match POS ID in OrderCreateRequest. Both values must be the same.
404 Not found DATA_NOT_FOUND Data indicated in the request is not available in the PayU system
408 Request timeout TIMEOUT Permitted time to process the request has expired
500 Internal server error BUSINESS_ERROR PayU system is unavailable. Try again later
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 Card status codes

List of card status codes sent by the PayU system, 3-D Secure codes.
Card transaction response codes:
Card ResponseCode Card ResponseCodeDesc Reason(*) Additional information Public communication
000 000 - OK Successful authorization. Funds were transferred to the recipient.
S01 S01 - Refer to card issuer Bank Authorization error. We are sorry, but your card's issuer rejected this transaction. If you would like to learn about the reason for this transaction to be rejected, please contact your bank. Please try again, choosing a different payment method.
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 No authorization. We are sorry, but your card's issuer rejected this transaction. Check if you can use your card to pay online or contact your bank. Please try again, choosing a different payment method.
S13 S13 - Invalid amount Bank Currency conversion field overflow or amount exceeds maximum for Card program. No authorization. We are sorry, but your card's issuer rejected this transaction. Check your card's limits or contact your bank. Please try again, choosing a different payment method.
S30 S30 - Message format error Bank Authorization error. We are sorry, but your card's issuer rejected this transaction. If you would like to learn about the reason for this transaction to be rejected, please contact your bank. Please try again, choosing a different payment method.
S43 S43 - Pickup card (stolen card) Bank
S51 S51 - Insufficient funds Bank Not enough funds or attempt to exceed limits (at the bank side). Insufficient funds. Check funds available on your card or contact your bank. Please try again, choosing a different payment method.
S54 S54 - Expired card Bank Card is expired or Customer made a mistake giving card dates. No authorization. We are sorry, but your card's issuer rejected this transaction. Check your card's expiration date or contact your bank. Please try again, choosing a different payment method.
S57 S57 - Card disabled for e-commerce or cross-border transactions Bank No authorization. We are sorry, but your card's issuer rejected this transaction. Check if you can use your card to pay online or contact your bank. Please try again, choosing a different payment method.
S61 S61 - Exceeds approval amount Bank Attempt to exceed limits (at the bank side).
S62 S62 - Restricted card / Country exclusion table Bank Authorization error. We are sorry, but your card's issuer rejected this transaction. If you would like to learn about the reason for this transaction to be rejected, please contact your bank. Please try again, choosing a different payment method.
S65 S65 - Exceeds withdrawal frequency limit. Bank Attempt (bank side) to exceed the limit. Authorization error. We are sorry, but your card's issuer rejected this transaction. Check the limit settings on your card or contact your bank. Please try again using a different payment method.
S90 S90 - Destination not available Bank Authorization error. We are sorry, but your card's issuer rejected this transaction. If you would like to learn about the reason for this transaction to be rejected, please contact your bank. Please try again, choosing a different payment method.
S93 S93 - Card disabled for e-commerce transactions Bank
S99 S99 - authorization error – default Bank Authorization error. We are sorry, but your card's issuer rejected this transaction. If you would like to learn about the reason for this transaction to be rejected, please contact your bank. Please try again, choosing a different payment method.
SN0 SN0 - Unable to authorize / Force STIP Bank
SSD SSD - Soft decline (strong authentication required) Bank Payment can be retried, but 3DS authentication must be used.
ST3 ST3 - Card not supported Bank
ST5 ST5 - Card inactive or closed (updated information needed) Bank Payment can be retried, but card data needs to be updated (e.g. expiry date).
ST8 ST8 - Invalid account Bank No authorization. We are sorry, but your card's issuer rejected this transaction. Check if you can use your card to pay online or contact your bank. Please try again, choosing a different payment method.
SIN SIN - No such issuer Bank
SP1 SP1 - Over daily limit (try again later) Bank Payment can be retried, preferrably after 24 hours. Authorization error. We are sorry, but your card's issuer rejected this transaction. If you would like to learn about the reason for this transaction to be rejected, please contact your bank. Please try again, choosing a different payment method.
SAC SAC - Account closed (do not try again) Bank Payment must not be retried, all further attempts will be declined.
SPF SPF - Possible fraud (do not try again) Bank Payment must not be retried, all further attempts will be declined.
SP9 SP9 - Enter lesser amount Bank No authorization. We are sorry, but your card's issuer rejected this transaction. Check your card's limits or contact your bank. Please try again, choosing a different payment method.
114 114 - 3ds authentication error (global) PayU Incorrect 3DS result (default configuration). No authorization. Your card's issuer did not confirm the transaction. Please try again.
115 115 - 3ds authentication error (company) PayU Incorrect 3DS result (company configuration).
116 116 - 3ds authentication error (merchant) PayU Incorrect 3DS result (merchant configuration).
117 117 - 3ds authentication error (fallback) PayU Incorrect 3DS result (fallback configuration).
120 120 - 3ds processing error PayU Error during 3DS processing.
123 123 - Missing cryptogram for Network Token's authorization. Visa/Mastercard Authorization error. We are sorry, but the attempt to confirm this transaction took too long. Please try again.
130 130 - Non-compliant prepaid card PayU Card recognized as not compliant with AMLD5. No authorization. We are sorry, but this card is not accepted within the European Economic Area. Please try again, choosing a different payment method.
131 131 - Credit card not allowed for debt merchants PayU Card recognized as not allowed for this transaction. No authorization. We are sorry, but credit card cannot be used to repay debt. Please try again, choosing a different payment method.
132 132 - Issuer will never approve PayU Card recognized as not allowed for this transaction. No authorization. We are sorry, but your card's issuer rejected this transaction. Please, do not attempt to pay with this card again. Select a different payment method and try again.
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, 998, 999 different messages PayU Contact PayU for details Authorization error. We are sorry, but the attempt to confirm this transaction took too long. Please try again.
(*) 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 Card Issuer Additional information
5 / 2 Visa / Mastercard Cardholder authenticated by the Issuer. Issuer Liability.
6 / 1 Visa / Mastercard Merchant attempted to authenticate the cardholder but either the cardholder or Issuer is not participating in 3DS or the Issuer’s ACS is currently unavailable. Issuer Liability.
7 / 0 Visa / Mastercard Payment authentication has not been performed. Merchant Liability.
Transactions are protected against risk of chargeback frauds with ECI codes:
  • 1 i 2 in case of Mastercard,
  • 5 i 6 in case of Visa.
Additionally response is supplemented with the following 3DS statuses:

Card 3Ds statuses:

card3DsStatus 3DS version Additional information
AY / Y 3DS / 3DS2 Authentication successful.
AA / A 3DS / 3DS2 Authentication attempted.
AU / U 3DS / 3DS2 Authentication could not be performed due to technical or other problem.
AN / N 3DS / 3DS2 Authentication failed. Authorization denied.
VE 3DS An error occurred during verification whether the card supports 3ds.
AE 3DS An error has occurred in the authentication process.
R 3DS2 Authentication rejected. Authorization denied.
I 3DS2 Informational status (the card issuer has accepted an exception to strong authentication).
A0 3DS Error on the card organization side.

9.8 Security

Security integration checklist with PayU:
  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.
When contacting PayU due to unsuccessful requests, please send us a message and provide Correlation-Id conveyed as a header of a response.

9.9 Integration guidelines

PayU can and will extend existing API messages with new fields and API with new methods. In order to integrate correctly, please make sure You are prepared for such a possibility.