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.

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 Card tokenization 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 public test point of sale. However, if you would like to test a full set of endpoints, including e.g. refunds, consider registering for a sandbox account.

Public 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.1 Test cases

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

The availability of the sandbox environment can be checked on the status page.

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:

Read the instruction if you do not know how to register or set up a new store in your Sandbox account.

3.2.1 Test credentials

Although it is best to create your own account to later be able to configure it as needed, 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

                

3.2.2 Test cards

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

All test cards support authentication by means of 3DS 2 protocol and the result is, unless stated otherwise, a successful frictionless authentication.

In practice this means that all orders with card token or card number in plain text as a payment method will return WARNING_CONTINUE_3DS status, unless the order is out of scope of SCA (like recurring payments or MOTO).

NOTE - due to SCA/PSD2 requirements, test cards with default 3DS result cannot be used to store the card/token.

Number Month Year CVV 3DS result Mastercard installments Behavior
4444333322221111 12 29 123 default no Positive authorization
5434021016824014 12 29 123 default yes * Positive authorization
5598614816563766 12 29 123 default yes ** Positive authorization
5099802211165618 12 29 123 default no Positive authorization. CVV is not required in single click payments (PayU | Express)
4012001037141112 12 29 123 default no Positive authorization
5100052384536891 12 29 123 default no Positive authorization
4012001007002005 12 29 123 default no Negative authorization
5000105018126595 12 29 123 default no Negative authorization
4000398284360 12 29 123 default no Negative authorization
4245757666349685 12 29 123 challenge required no Positive authorization
5150030090350186 12 29 123 3DS Method required and then successful frictionless no Positive authorization
4012001037141120 12 29 123 3DS Method and challenge required no Positive authorization
5100052384536834 12 29 123 challenge params if sdk object sent in OrderCreateRequest no Positive authorization
5100052384536818 02 32 123 challenge required / if no 3DS is used, returns soft decline (SSD) no Positive authorization
5100052384536826 12 29 123 frictionless positive authentication no Positive authorization
5521455186577727 12 29 123 frictionless negative authentication no no authorization (authentication fails)
5405860937270285 12 29 123 default no 50% chance for successful authorization
4532598021104999 12 29 123 default no successful authorization only for amount below 1000 minor units of given currency
4210836393742163 12 29 123 3DS Method no successful authorization only for amount below 1000 minor units of given currency
5436062405627681 12 29 123 challange no iframeAllowed takes a value of false for amounts greater than 300 minor units
  • * - Pay in installments with Mastercard in VARYING_NUMBER_OF_OPTIONS options format
  • ** - Pay in installments with Mastercard in VARYING_NUMBER_OF_INSTALLMENTS options format

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

3.2.3 Available functionalities

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

Automatic cancellation of transactions

All card payment methods are automatically cancelled after:
  • 1 hour - in case of unpaid transaction,
  • 5 days - in case of transaction in "Waiting to be received" status.

Payment methods details

Value Transaction amount Description Booking
c 0,01 - 999999,99 Payment card (credit, debit, prepaid) - CHF, EUR, GBP, USD. 24h/7
c 0,05 - 999999,99 Payment card (credit, debit, prepaid) - PLN, RON. 24h/7
c 0,30 - 999999,99 Payment card (credit, debit, prepaid) - CZK. 24h/7
c 0,02 - 999999,99 Payment card (credit, debit, prepaid) - BGN. 24h/7
c 1,00 - 999999,99 Payment card (credit, debit, prepaid) - RUB. 24h/7
c 5 - 9999999 Payment card (credit, debit, prepaid) - HUF. 24h/7
c 0,50 - 9999999,99 Payment card (credit, debit, prepaid) - all other supported currencies. 24h/7
jp as above for payment cards 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 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 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 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).

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

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

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

Automatic cancellation of transactions

In the case of credit payment methods, the automatic cancellation time for unpaid transactions and transactions in the status "Waiting to be received" is the same but depends on the payment method:
  • 5 days - for PayU | Installments,
  • 10 days - for other methods.

Payment methods details

Value Transaction amount (PLN) Description Currency
ai 100,00 - 50000,00 * PayU | Installments PLN
dpt 1,00 - 1500,00 Twisto | PayU Pay Later (Poland) PLN
dpp 10,00 - 2000,00 PayPo | PayU Pay Later (Poland) PLN
dpcz 3,00 - 999999,99 Pay Later with Twisto (Czech) CZK
dpts 1500,00 - 100000,00 Twisto Pay in 3 (Czech) CZK
  • * - depending on the variant.

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

Automatic cancellation of transactions

For Polish transfers, the automatic cancellation time for unpaid transactions is 5 days, and for transactions in the status "Waiting to be received": 10 days. The exception is the "Przelew bankowy" method, for which the automatic cancellation time is 10 days in both cases.

Payment methods details

Value Transaction amount (PLN) Description Booking
blik 0,01 - 49999,99 BLIK 24h/7
m 0,37 - 999999,99 mTransfer - mBank 24h/7
w 0,37 - 999999,99 Przelew24 - Santander (form. BZ WBK) 24h/7
o 0,37 - 999999,99 Pekao24Przelew - Bank Pekao 24h/7
i 0,37 - 999999,99 Płacę z Inteligo 24h/7
p 0,37 - 999999,99 Płać z iPKO 24h/7
g 0,37 - 999999,99 Płać z ING 24h/7
gbx 1,00 - 999999,99 Płacę z VeloBank 24h/7
l 0,37 - 999999,99 Credit Agricole 24h/7(*)
ab 0,37 - 999999,99 Płacę z Alior Bankiem 24h/7
wm 0,37 - 999999,99 Przelew z Millennium 24h/7
wc 0,37 - 999999,99 Przelew z Citi Handlowego 24h/7
bo 0,37 - 999999,99 Płać z BOŚ 24h/7
bnx 0,37 - 999999,99 BNP Paribas 24h/7
bs 0,50 - 999999,99 Banki Spółdzielcze 24h/7
nstb 0,50 - 999999,99 Nest bank 24h/7
plsb 0,50 - 999999,99 Plus Bank 24h/7
b 0,50 - 999999,99 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)

Automatic cancellation of transactions

For Czech transfers, the time for automatic cancellation of unpaid transactions and transactions in the status "Waiting to be received" is the same, but depends on the payment method:
  • 14 days - for bank transfer (bt) and postal transfer (pt),
  • 10 days - for other methods.

Payment methods details

Value Transaction amount (CZK) Description
cs 3,00 - 999999,99 Česká spořitelna
mp 3,00 - 999999,99 mBank
kb 3,00 - 999999,99 Komerční banka
rf 3,00 - 999999,99 Raiffeisenbank
pg 3,00 - 999999,99 Moneta Money Bank
pf 3,00 - 999999,99 Fio banka
cb 3,00 - 999999,99 ČSOB
uc 3,00 - 999999,99 UniCredit
bt 3,00 - 999999,99 Bank transfer
pt 3,00 - 999999,99 Postal transfer

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

Automatic cancellation of transactions

For Slovak transfers, the time for automatic cancellation of unpaid transactions and transactions in the status "Waiting to be received" is the same and is 10 days.

Payment methods details

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

4.6 International payment methods

Please contact your account manager to have them enabled.

Automatic cancellation of transactions

For international transfers, the automatic cancellation time for unpaid transactions and transactions in the status "Waiting to be received" is the same and is 10 days. The exception is the GiroPay (gp) method, for which the automatic cancellation time for unpaid transactions is 5 days and the automatic cancellation time for transactions in the status "Waiting to be received" is 10 days.

Payment methods details

Value Transaction amount (equivalent in EUR) Description Type Availability Currency
gp 1,00 - 999999,99 GiroPay pbl DE EUR
pbc 1,00 - 999999,99 Bancontact payment card BE EUR
pid 1,00 - 999999,99 iDEAL pbl NL EUR
pmb 1,00 - 999999,99 MyBank standard transfer / pbl IT EUR
pscd 1,00 - 1000,00 PaySafeCard voucher prepaid AT, BE, CY, DE, ES, FI, FR, IT, LI, LT, LU, MT, NL, PT, SI, SK EUR
sb 1,00 - 999999,99 Sofort Banking standard transfer / pbl AT, BE, CH, DE, ES, GB, IT, NL EUR, GBP*, CHF*
sdd 1,00 - 1000,00 SEPA Direct Debit direct debit AT, BE, CH, CY, CZ, DE, DK, EE, ES, FI, FR, GB, GR, HR, HU, IE, IS, IT, LI, LT, LU, LV, MC, MT, NL, NO, PT, RO, SE, SI, SK, SM EUR
pmbc 1,00 - 99999,99 Multibanco pbl PT EUR
ptrl 1,00 - 1000,00 Trustly pbl DE, DK, EE, ES, FI, GB, LT, LV, NL, NO, PT, SE, SK EUR, DKK*, GBP*, NOK*, SEK*
  • CHF* - only in combination with country code CH
  • DKK* - only in combination with country code DK
  • GBP* - only in combination with country code GB
  • NOK* - only in combination with country code NO
  • SEK* - only in combination with country code SE

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 (1:1).

Code Name
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
SEK Swedish krona
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 Yes 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 Yes Yes Yes Yes
lt Lithuanian No Yes Yes No
lv Latvian No Yes Yes No
nl Dutch Yes Yes 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
/api/v2_1/card-installment-proposals/{proposalId} GET Provides installment proposal for Mastercard payment. Pay in installments with Mastercard
/api/v2_1/card-installment-proposals/{proposalId}/decisions POST Allows to submit payer’s decision with selected installment option. Pay in installments with Mastercard

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