Overview

1 Overview

With PayU, you will quickly activate payments on your website or mobile device.

We provide a full set of endpoints which allow you to create, capture, cancel and retrieve orders, perform payouts or download reports.

To simplify the integration, you can simply use one of our plugins or our PHP SDK.

Last but not least, many shopping platforms offer an in-built integration with PayU. If this is the case, follow the instructions of how to configure payments via PayU.

1.1 How to start?

For starters, you definitely need a PayU account. It may be a production PayU account (register or contact a PayU partner or sales representative) or a sandbox account (register).

After you have logged in to the panel, create a Shop and POS of REST API type.

Note: in case you decided to use a production account to test your integration, your account will not be fully active until we verify you. However you may enable and use the test payment from the very beginning.

1.2 Integration model

Before you start, it is important to choose the right integration model. There are several options available. The service you need to integrate and the configuration of your account may depend on the following:

Will you fullfil each order paid via PayU?

If no, you should disable "automatic collection" on your POS and make separate API-calls to create an order and capture or cancel it aferwards.

Are you selling more expensive goods or services?

If yes, boost your sales with PayU | Installments.

Will you process a lot of refunds?

If yes, you definitely should consider implementing API calls to facilitate refunds programatically, instead of performing them via the Panel.

Would you like to enable the payers to choose a payment method on your website?

If yes, go for "transparent" integration.

Will you create user accounts for your customers?

If yes, implement PayU | Express service and PayU will securely store card data, so your returning customers do not have to provide them each time and will be able to pay with a single click.

Will you charge your customers on a recurring basis (e.g. monthly)?

If yes, use the recurring payment service.

Are you a billing your customers by issuing an invoice connected with a specific bank account?

If yes, use the Mass Collect service.

Will you need to collect funds from customers and later distribute them to your subcontractors?

If yes, use the Payout API to streamline funding of your business partners.

Check our commercial offer for more details.

1.3 Support

Feel free to contact us - by fiiling the form here.

In case you want them to check on a specific API call you made, provide the value of Correlation-Id header returned in the response from PayU.

2 Example

PayU hosted payment page

Click the button – it will redirect you to a PayU hosted payment page.

The working example above shows the most basic integration - a payment form implementing REST API protocol. To make your integration easier to enhance in the future, consider using JSON requests.

Secure Form

Click the button - it will show a Secure Form which you may use to securely capture card data. The Secure Form can be also displayed inline.

To check all card payment processing options refer to the card forms section.

3 Testing your integration

For a basic integration, including only a redirection to PayU hosted payment page, it is perfectly enough to use the test payment method. However, if you would like to test a full set of endpoints, including e.g. refunds, consider registering for a sandbox account.

Below is a list of test cases for your integration - check how your website handles the following:

  1. Is your user correctly redirected to PayU when PayU responds with a HTTP 302 for the POST method calls you make to /api/v2_1/orders endpoint?
  2. Do you receive and parse the notification from PayU and respond with a HTTP 200?
  3. Do you correctly establish order status during its lifecycle? Mind, order status is only provided via notifications, the statuses returned in the response from PayU apply to the request itself and to the order(!).
  4. Do you provide a continueUrl parameter? Is the customer redirected to this URL correctly after the payment process is completed?
  5. Are you prepared to handle the error message passed in the query string added to the continueUrl?
  6. In case of a PayU|Express integration - is your website ready to handle all the payment authorization scenarios?

Options 1 and 2 above can be performed either via the Panel or programatically via API.

3.1 Test payment method

The test method is used for generating test payments in your PayU account. Funds from such transactions are not increasing your merchant account balance, therefore it cannot be used to test refunds. To test full functionalities of a PayU account, you may register for a sandbox account (see below).

Test transactions are disabled by default, they are also automatically blocked 3 days after being used for the last time (it doesn't matter when test transactions were enabled, only when last transaction was made). In order to perform the tests, activate this method of payment in My shops > Shop name > List of POSs > POS name, and change the status of a “Test payment” in the Status column.

Remember to disable this method once you go live!
Value Transaction amount (all currencies) Time of automatic cancellation (in days) Description
t 0,50 - 20000,00 1 test payment – a form is displayed where transaction status can be changed

You may use test payment method on your own POS or use a test production POS we have already created for you:

Production point of sale test data

POS ID (pos_id):                    145227
Second key (MD5):                   13a980d4f851f3d9a1cfc792fb1f5e50
OAuth protocol - client_id:         145227
OAuth protocol - client_secret:     12f071174cb7eb79d4aac5bc2f07563f

3.2 Sandbox

Sandbox is an almost identical copy of PayU production system. It can be used for integration and testing purposes. To use the sandbox you need a register separately in one quick step. After you are registered, you can set up own companies / shops / point of sale. Use the following links:

Sandbox point of sale test data

You may also use a public sandbox test POS without registering:
               
               POS ID (pos_id):                 300746
               Second Key (MD5):                b6ca15b0d1020e8094d9b5f8d163db54
               OAuth protocol - client_id:      300746
               OAuth protocol - client_secret:  2ee86a66e5d97e3fadc400c9f19b065d
            
            

Cards on sandbox.

In order to test card payments on sandbox, please use the following credentials.

Card issuer Number Month Year CVV 3-D Secure Behavior
Visa 4444333322221111 01 21 123 no Positive authorization
MasterCard 5434021016824014 01 21 123 no Positive authorization
Maestro 5099802211165618 01 21 123 no Positive authorization. CVV is not required in single click payments (PayU | Express)
Visa 4012001037141112 01 21 123 yes Positive authorization
MasterCard 5100052384536891 01 21 123 yes Positive authorization
MasterCard 5150030090050083 01 21 123 yes Negative authorization
Visa 4012001007002005 01 21 123 yes Negative authorization
Maestro 5000105018126595 01 21 123 no Negative authorization
Visa 4000398284360 01 21 123 no Negative authorization

OneClick payments with the test cards require a CVV unless specified otherwise in the Behavior column.

Sandbox functionality.

Functionalities available on sandbox:

4 Payment methods

Below is a full list of payment methods available from PayU. To ensure that your customer pays only by currently available payment methods, it is strongly recommended to take advantage of automatic payment methods retrieval:

  • If you are using PayU hosted payment page (payMethod PAYMENT_WALL or none), we take care of everything, including logotypes which are updated automatically.
  • If you have implemented the payment methods on your own in your e-shop, you can follow these instructions.
  • If you are still using Classic API (NewPayment) and you don't plan to upgrade to REST API soon, then please follow these instructions.

Thanks to this service our 24/7 monitoring takes care of the channel deactivation, if it is planned maintenance break or unexpected outage. If something as such would happen, the consumer can, e.g. pay by credit card if his bank does not handle the transfer at that point in time.

4.1 Card-based payment methods

Value Transaction amount Time of automatic cancellation (in days) Description Booking
c 0,01 - 999999,99 5 Payment card (credit, debit, prepaid) - CHF, EUR, GBP, USD. 24h/7
c 0,05 - 999999,99 5 Payment card (credit, debit, prepaid) - PLN, RON. 24h/7
c 0,30 - 999999,99 5 Payment card (credit, debit, prepaid) - CZK. 24h/7
c 0,02 - 999999,99 5 Payment card (credit, debit, prepaid) - BGN. 24h/7
c 1,00 - 999999,99 5 Payment card (credit, debit, prepaid) - RUB. 24h/7
c 5 - 99999999 5 Payment card (credit, debit, prepaid) - HUF. 24h/7
c 0,50 - 99999999,99 5 Payment card (credit, debit, prepaid) - all other supported currencies. 24h/7
jp as above for payment cards 5 Apple Pay is a source of card data - authorization and settlement is done in the same way as for a standard card payment. In the Panel and on statements, Apple Pay transactions are flagged as card payments, i.e. you may use 'jp' value to initiate Apple Pay payment, but the transaction created will be flagged with 'c'. To check if the transaction was done via Apple Pay, you need to check "payment flow" value. The value can be obtained through payment/get or Transaction Data Retrieve. 24h/7
ap as above for payment cards 5 Google Pay (formerly Android Pay) is a source of card data - authorization and settlement is done in the same way as for a standard card payment. In the Panel and on statements, Google Pay transactions are flagged as card payments, i.e. you may use 'ap' value to initiate Google Pay payment, but the transaction created will be flagged with 'c'. To check if the transaction was done via Google Pay, you need to check "payment flow" value. The value can be obtained through payment/get or Transaction Data Retrieve. 24h/7
ma as above for payment cards 5 Masterpass is a source of card data - authorization and settlement is done in the same way as for a standard card payment. In the Panel and on statements, Masterpass transactions are flagged as card payments, i.e. you may use 'ma' value to initiate Masterpass payment, but the transaction created will be flagged with 'c'. To check if the transaction was done via Masterpass, you need to check "payment flow" value. The value can be obtained through payment/get or Transaction Data Retrieve. 24h/7
vc as above for payment cards 5 Visa Checkout is a source of card data - authorization and settlement is done in the same way as for a standard card payment. In the Panel and on statements, Visa Checkout transactions are flagged as card payments, i.e. you may use 'vc' value to initiate Visa Checkout payment, but the transaction created will be flagged with 'c'. To check if the transaction was done via Visa Checkout, you need to check "payment flow" value. The value can be obtained through payment/get or Transaction Data Retrieve. 24h/7

4.2 Installments and Pay later

PayU | Installments is available only on PL market (read more).

PayU | Pay Later is available on PL market (read more).

PayU | Pay Later with Twisto is available on CZ market (read more).

Value Transaction amount (PLN) Time of automatic cancellation (in days) Description Currency
ai 300,00 - 20000,00 5 PayU | Installments PLN
dp 100,00 - 2000,00 5 PayU | Pay later PLN
dpcz 3,00 - 999999,99 5 PayU | Pay Later with Twisto CZK

4.3 Polish pay-by-link online transfers (PLN)

Value Transaction amount (PLN) Time of automatic cancellation (in days) Description Booking
blik 0,01 - 9999,99 10 BLIK 24h/7
m 0,37 - 999999,99 10 mTransfer - mBank 24h/7
w 0,37 - 999999,99 10 Przelew24 - Santander (form. BZ WBK) 24h/7
o 0,37 - 999999,99 10 Pekao24Przelew - Bank Pekao 24h/7
i 0,37 - 999999,99 10 Płacę z Inteligo 24h/7
p 0,37 - 999999,99 10 Płać z iPKO 24h/7
g 0,37 - 999999,99 10 Płać z ING 24h/7
gbx 1,00 - 999999,99 10 Płacę z Getin Bank 24h/7
nlx 1,00 - 999999,99 10 Płacę z Noble Bank 24h/7
ib 0,37 - 999999,99 10 Paylink Idea - IdeaBank 01:00-23:00
l 0,37 - 999999,99 10 Credit Agricole 24h/7(*)
as 0,37 - 999999,99 10 Płacę z T-mobile Usługi Bankowe dostarczane przez Alior Bank 24h/7
ab 0,37 - 999999,99 10 Płacę z Alior Bankiem 24h/7
ps 0,37 - 999999,99 10 Płacę z Bankiem Nowym BFG S.A. (d. PBS) 01:00 – 23:30, 24h on weekends
wm 0,37 - 999999,99 10 Przelew z Millennium 24h/7
wc 0,37 - 999999,99 10 Przelew z Citi Handlowego 24h/7
bo 0,37 - 999999,99 10 Płać z BOŚ 24h/7
bnx 0,37 - 999999,99 10 BNP Paribas 24h/7
bs 0,50 - 999999,99 10 Banki Spółdzielcze 24h/7
nstb 0,50 - 999999,99 10 Nest bank 24h/7
sgb 0,50 - 999999,99 10 SGB-Bank 24h/7
plsb 0,50 - 999999,99 10 Plus Bank 24h/7
b 0,50 - 999999,99 10 Przelew bankowy

(*) Between 23:45 and 3:15 daily cut-off operations are run which can cause breaks in payment processing.

4.4 Czech pay-by-link online transfers (CZK)

Value Transaction amount (CZK) Time of automatic cancellation (in days) Description
cs 3,00 - 999999,99 10 Česká spořitelna
mp 3,00 - 999999,99 10 mBank
kb 3,00 - 999999,99 10 Komerční banka
rf 3,00 - 999999,99 10 Raiffeisenbank
pg 3,00 - 999999,99 10 Moneta Money Bank
pv 3,00 - 999999,99 10 Sberbank
pf 3,00 - 999999,99 10 Fio banka
era 3,00 - 999999,99 10 Poštovní spořitelna / Era
cb 3,00 - 999999,99 10 ČSOB
uc 3,00 - 999999,99 10 UniCredit
bt 3,00 - 999999,99 14 Bank transfer
pt 3,00 - 999999,99 14 Postal transfer

4.5 Slovak pay-by-link online transfers (EUR)

Value Transaction amount (EUR) Time of automatic cancellation (in days) Description Booking
posta 0,5 - 999999,99 10 Poštová banka, a. s. 24h/7
sporo 0,5 - 999999,99 10 Slovenská sporiteľňa, a. s. 24h/7
tatra 0,5 - 999999,99 10 Tatra banka, a. s. 24h/7
uni 0,5 - 999999,99 10 UniCredit Bank 24h/7
viamo 0,5 - 999999,99 10 Viamo 24h/7
vub 0,5 - 999999,99 10 Všeobecná úverová banka, a. s. 24h/7

4.6 International payment methods

These methods are currently offered for payments in EUR. Please contact your account manager to have them enabled.

Value Transaction amount (EUR) Time of automatic cancellation (in days) Description Type Availability
gp 1,00 - 999999,99 10 GiroPay pbl DE
pbc 1,00 - 999999,99 10 Bancontact payment card BE
pid 1,00 - 999999,99 10 iDEAL pbl NL
pmb 1,00 - 999999,99 10 MyBank standard transfer / pbl IT, ES, GR
pscd 1,00 - 1000,00 10 PaySafeCard voucher prepaid AT, BE, CY, DE, ES, FI, FR, IT, LI, LT, LU, MT, NL, PT, SI, SK
sb 1,00 - 999999,99 10 Sofort Banking standard transfer / pbl AT, BE, CH, DE, ES, IT, NL

5 Available currencies

In PayU it is possible to set two types of currency at the level of a single shop: transaction currency and billing currency.

The transaction currency determines in which currency the payer can make their payments. It also affects the availability of payment methods – payments with cards are available in any currency, and other methods (e.g. quick transfer) are only in CZK, EUR and PLN.

Billing currency determines in which currency the funds will be transferred to the merchant’s account. By default, PayU settles with the merchant in the same currency in which the transaction was processed (1:1)

Depending on the selected billing currency there may be additional fees and restrictions in payout frequency.

Below table shows the list of the transaction currencies in which PayU can settle with the merchant. Some currencies – marked with * - are settled only in EUR.

Code Name
BGN* Bulgarian lev
CHF Swiss franc
CZK Czech koruna
DKK Danish krone
EUR Euro
GBP Pound sterling
HRK Croatian kuna
HUF Hungarian forint
NOK Norwegian krone
PLN Polish złoty
RON Romanian leu
RUB* Russian ruble
SEK Swedish krona
UAH* Ukrainian hryvnia
USD US dollar

There is also available an additional ICP functionality. It allows to automatically convert transaction currency into, selected by the merchant, billing currency (currently only USD and EUR). In order to obtain further information, please contact your sales representative or get in touch with us through our contact form.

6 Available language versions

Below language parameters can be provided as language parameter in the <Buyer> object.

The table details language support in terms of paywall (a page hosted by PayU where the payer can choose from all payment methods configured on your POS), card form and email with payment-related information sent to the payer.

Code Language Paywall Paywall card form Email Widget
pl Polish Yes Yes Yes Yes
en English Yes Yes Yes Yes
cs Czech Yes Yes Yes Yes
bg Bulgarian No Yes Yes Yes
da Danish No Yes Yes Yes
de German Yes Yes Yes Yes
el Greek No Yes Yes No
es Spanish No Yes Yes Yes
et Estonian No Yes No Yes
fi Finnish No Yes No No
fr French No Yes Yes Yes
hr Croatian No Yes Yes No
hu Hungarian No Yes Yes Yes
it Italian No Yes Yes Yes
lt Lithuanian No Yes Yes No
lv Latvian No Yes Yes No
nl Dutch No No Yes No
pt Portuguese No Yes No No
ro Romanian No Yes Yes Yes
ru Russian No Yes No No
sk Slovak Yes Yes Yes Yes
sl Slovenian No Yes No No
sr Serbian No Yes No No
sv Swedish No Yes Yes No
tr Turkish No Yes Yes No
uk Ukrainian No Yes Yes No

7 Endpoint reference

Before you take a closer look at full REST API reference, it maybe worth your while to have a quick look at all the endpoints provide, just to plan which of them you want to integrate.

Host addresses

Production:

https://secure.payu.com/

Sandbox:

https://secure.snd.payu.com/

Endpoint paths

Address HTTP Method Comment Full reference
/pl/standard/user/oauth/authorize POST Provides OAuth token. Signing API calls
api/v2_1/paymethods GET Provides available payment methods. Payment methods retrieval
/api/v2_1/orders POST Creates Order and enables to initiate payment transaction. OrderCreateRequest
/api/v2_1/orders/{orderId} GET Provides Order data and status. OrderRetrieveRequest
/api/v2_1/orders/{orderId} DELETE Cancels Order. Canceling Order
/api/v2_1/orders/{orderId}/transactions GET Provides payment transaction details (bank account details or card data). Transaction data retrieval
/api/v2_1/orders/{orderId}/status PUT Captures Order. Order capture
/api/v2_1/orders/{orderId}/refunds POST Allows to perform refunds (total or partial) Refund
/api/v2_1/payouts POST Allows to request payout directly from your application (note: automated or ad hoc payouts are also available in the Panel) Payouts
api/v2_1/mcp-partners/{mcpPartnerId}/fx-table GET Provides available currency pairs. Multi-Currency Pricing
/api/v2_1/reports/{reportId} GET Allows to download transaction statement (note: automated or ad hoc statements are also available in the Panel). Visa Checkout
/api/visa-checkout/proxy/payment/data/{callId} GET Allows to download data (card number, shipping address etc.) from Visa Checkout. Visa Checkout

8 Transmission encryption

Since 30 June 2018 PayU supports only TLS 1.2 protocol.

Lack of support for older protocols is for security reasons. The TLS 1.2 protocol is the best transmission encryption method compliant with the highest security standard PCI DSS 3.2.

The change applies to all transmission via HTTPS, therefore it includes all REST API and Classic API endpoints.

Majority of e-commerce solutions and hosting providers make sure that their software is up-to-date. Therefore, if your site is using such a provider, most probably you have nothing to worry about. You can contact your service providers and ask whether they have updated their software.

If your site is a custom-built solution, make sure that it uses the latest version of the protocol. The following information could be useful:

JAVA

Java 1.5 and below does not support TLS 1.2 In Java 1.6, TLS 1.2 is not supported in Oracle public updates. It is supported in the business edition starting Oracle java version 6u115 b32.

In Java 1.7, TLS1.2 is supported. But it needs to be explicitly enabled by selecting the enabled protocols while creating the SSLSocket & SSLEngine instances.

Please refer to: https://blogs.oracle.com/java-platform-group/jdk-8-will-use-tls-12-as-default for more details.

cURL

Curl supports TLS1.2 starting 7.34.0. Please use the following command to test the connection.

Note: you may use any PayU endpoint - see endpoint reference for REST API and Classic API.

curl --tlsv1.2 https://secure.payu.com/api/v2_1/orders
If it works, you'll see "Unauthorized" message.

cURL+PHP

                    php -r '$ch = curl_init(); 
                    curl_setopt($ch, CURLOPT_URL, "https://secure.payu.com/api/v2_1/orders"); 
                    curl_setopt ($ch, CURLOPT_SSLVERSION, 6); 
                    var_dump(curl_exec($ch)); 
                    var_dump(curl_error($ch));'               
If it works, you'll see "Unauthorized" message. TLS 1.1 and TLS 1.2 are supported since OpenSSL 1.0.1. Forcing TLS 1.1 and 1.2 are only supported since curl 7.34.0.

9 Glossary

PayU PayU S.A. - a licensed payment services provider and an acquirer (member of Visa and MasterCard). For the purpose of this documentation, PayU means also an application run by PayU S.A.
Merchant A merchant (aka "payment acceptor") means an entity which has signed a payment acceptance agreement with PayU and has been registered to PayU application. From the application perspective, "merchant" is a set of entites: Company/Shop/POS (see entries below).
Panel Management Panel or Administration Panel is the user interface of PayU application provided to the merchants. A link to the panel is sent to the merchant's users upon registration in PayU. The guide is available here.
Company / Firm A legal entity that uses PayU application to collect funds from customers. The entity is characterized with a set of features such as legal name, address, tax id etc.
Shop Online shop that collects payments; one company may have several shops. Merchant account balance in specified currency is run at the shop level.
POS Point of sale that accepts payments. Most service parameters are defined at POS level. A single Shop may operate a few POSs.
Customer / Buyer A person making payment at your website (a shopper).