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 our IT Support team - by sending an email to tech@payu.pl.

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.

PayU hosted widget

Click the button - it will invoke a PayU widget which you may use to securely capture card data. The widget 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. How do you handle an order with REJECTED status?*
  7. In case of a PayU|Express integration - is your website ready to handle all the payment authorization scenarios?

*REJECTED status occurs from time to time for some online transfers. It means that the bank initially responded with a CANCELED status, but later charged your customer. In this case, PayU sends a notification about status change. The options you have are: 1/ capture and fulfill the order, 2/ cancel the order to return the money as quickly as possible, 3/ do nothing (order will be canceled automatically after number of days specified for a given payment method. To simulate this case, do the following: create an order and perform redirection to the bank or test payment method (you will get a notification with PENDING status, cancel it in the panel (CANCELED status), return to the payment and authorize it (REJECTED status).

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. 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 (PLN) Time of automatic cancellation (in days) Description
t 0,50 - 1000,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
Maestro 5000105018126595 01 21 123 no Negative authorization
Visa 4000398284360 01 21 123 no Negative authorization

Sandbox functionality.

Functionalities available on sandbox:

4 Payment methods

Below is a full list of payment methods available from PayU.

4.1 Card-based payment methods

Value Transaction amount Time of automatic cancellation (in days) Description
c 0,50 - 999999,99 5 Payment card (credit, debit, prepaid) - all supported currencies except CZK and HUF
c 3,00 - 999999,99 5 Payment card (credit, debit, prepaid) - CZK
c 10,00 - 99999999,99 5 Payment card (credit, debit, prepaid) - HUF
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.
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.

4.2 Installments and Pay later

These payment methods are currently offered in PLN currency only.

Value Transaction amount (PLN) Time of automatic cancellation (in days) Description
ai 300,00 - 20000,00 5 PayU | Installments
dp 100,00 - 2000,00 5 PayU | Pay later

4.3 Polish pay-by-link online transfers

Value Transaction amount (PLN) Time of automatic cancellation (in days) Description Booking
blik 1,00 - 999999,99 10 BLIK 24h/7
m 0,37 - 999999,99 10 mTransfer - mBank 24h/7
mtex 0,50 - 999999,99 10 mTransfer mobilny - mBank(*) 24h/7
w 0,37 - 7000,00 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
pkex 1,00 - 999999,99 10 PayU Express Bank Pekao(*) 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
gbex 1,00 - 999999,99 10 GetIn Bank PayU Express(*) 24h/7
nlx 1,00 - 999999,99 10 Płacę z Noble Bank 24h/7
nlex 1,00 - 999999,99 10 Noble Bank PayU Express(*) 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
exas 0,37 - 500 (if the max. value is exceeded or PayU’s transaction risk assessment is negative, the payment will be processed via the “Płacę z T-mobile Usługi Bankowe dostarczane przez Alior Bank” method [as]) 10 PayU Express T-mobile Usługi Bankowe(*) 24h/7
u 0,37 - 999999,99 10 Eurobank 04:00-23:30
ab 0,37 - 999999,99 10 Płacę z Alior Bankiem 24h/7
exab 0,37-500 (if the max. value is exceeded or PayU’s transaction risk assessment is negative, the payment will be processed via the “Płacę z Alior Bankiem” method [ab]) 10 PayU Express z Alior Bankiem(*) 24h/7
ps 0,37 - 999999,99 10 Płacę z PBS 01:00 – 23:30, 24h on weekends
wm 0,37 - 999999,99 10 Przelew z Millennium 24h/7
rfki 1,00 - 999999,99 10 Raiffeisen POLBANK 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,50 - 999999,99 10 Płacę z BNP Paribas 24h/7
bnex 0,37 - 999999,99 10 BNP Paribas PayU Express(*) 24h/7
orx 1,00 - 999999,99 10 Płacę z Orange 24h/7
orex 1,00 - 999999,99 10 PayU Express Orange(*) 24h/7
bs 0,50 - 999999,99 10 Banki Spółdzielcze 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
t 0,50 - 1000,00 1 test payment – a form is displayed where transaction status can be changed

(*) This payment type is available for: PayU Account and PayU | Express.

(**) 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 transfer payment methods

Value Transaction amount (CZK) Time of automatic cancellation (in days) Description
cs 3,00 - 999999,99 10 PLATBA 24 - Česká spořitelna
mp 3,00 - 999999,99 10 mTransfer - mBank
kb 3,00 - 999999,99 10 MojePlatba – Komerční banka
rf 3,00 - 999999,99 10 ePlatby pro eKonto - 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 Era - Poštovní spořitelna
cb 3,00 - 999999,99 10 ČSOB
uc 3,00 - 999999,99 10 UniCredit
bt 3,00 - 999999,99 14 Bankovní převod
pt 3,00 - 999999,99 14 Převod přes poštu (poštovní poukázkou)

4.5 International payment methods

These methods are currently offered for payments in EUR only. Please contact your account manager to have them enabled.
Value Transaction amount (EUR) Time of automatic cancellation (in days) Description
gp 1,00 - 999999,99 10 GiroPay
it 1,00 - 999999,99 10 InstantTransfer
pscd 1,00 - 1000,00 10 PaySafeCard
sp 1,00 - 999999,99 10 SafetyPay
sb 1,00 - 999999,99 10 Sofort Banking
trp 1,00 - 999999,99 10 TrustPay

5 Available currencies

Payment transactions in currencies listed below are settled "like for like" (that is: payer is charged and the funds are paid out to you in the same currency) except for marked with * which are settled in EUR.

Additional fees or settlement cycle restrictions (e.g. no daily pay-outs) may apply in case of some currencies.

Payment method support varies depending on currency - cards are available for all, whereas alternative payment methods such as online transfers etc. are supported only for CZK, EUR and PLN.

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

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 Card form Email
pl Polish Yes Yes Yes
en English Yes Yes Yes
cs Czech Yes Yes Yes
bg Bulgarian No Yes No
de German Yes Yes No
el Greek No Yes Yes
es Spanish No Yes Yes
et Estonian No Yes No
fi Finnish No Yes No
fr French No Yes No
hr Croatian No Yes No
hu Hungarian No Yes Yes
it Italian No Yes Yes
lt Lithuanian No Yes Yes
lv Latvian No Yes Yes
pt Portuguese No Yes No
ro Romanian No Yes Yes
ru Russian No Yes No
sk Slovak No Yes No
sl Slovenian No Yes No
sv Swedish No Yes Yes
uk Ukrainian No Yes Yes

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