2.

PayU Implementation
Manual for e-shops
using a template

www.payu.cz

www.payu.cz

Table of Contents
1. Introduction

2. From registration to PayU launch

2.1 General information
2.2 Description of individual steps

5
6
7

3. PayU implementation
3.1 General information
3.2 Terms used in the application
3.3 Integration with PayU
3.3.1 Configuration data
3.3.2 URL addresses and available procedures of the PayU application
3.3.3 Encoding
3.3.4 Data Format
3.3.5 Creating a new payment
3.4 Exchange of information on transactions
3.4.1 Notifying the Shop of transaction status change
3.4.2 Recognizing the transaction status
3.4.3 Receipt of payment
3.4.4 Rejection of payment
3.4.5 The operation complete status
3.5 The structure of the UrlPositive and UrlNegative return addresses
3.6 MD5 checksums
3.6.1 Checksum parameters passed on to a new payment
3.7 Testing

13
14
14
15
15
15
15
16
16
21
21
22
25
25
25
27
28
29
30

4. Appearance of the PayU payment gateway in the e-shop

4.1 Visualization and description of payment methods
4.2 Implementation
4.3 The purchasing process and user-friendly implementation
4.4 Optimizing the purchasing process
4.5 Navigation and visualization
4.6 Speed and conversion rate
4.7 A functional template
4.8 Education of customers and marketing

31
32
32
33
33
34
34
35
35

5. The mandatory parameters of implementation

37

6. PayU account administration

6.1 General information
6.2 PayU user interface
6.3 Creating a Shop and a POS
6.4 Transactions
6.5 Billing, Collection and Refund payments
6.6 Payouts
6.7 PDF/CSV/ABO Statements
6.8 Statistics
6.9 Notification settings
6.10 User accounts

39
40
40
41
47
54
56
59
65
67
67

www.payu.cz

7. Appendices
Appendix 1 Types of payments
Appendix 2 Transaction status
Appendix 3 Transitions among transaction states
Appendix 4 Error codes
Appendix 5 A sample php script for checking transaction status
Appendix 6 PayU templates
Appendix 7 PayU implementation examples
Appendix 8 Changes according to the manual version

70
71
72
73
75
76
80
81
83

www.payu.cz

Introduction

PayU is the fastest growing provider of online payments in the Czech Republic. It is the Czech
version of the successful service that has been operating in Europe since 2005. It uses a unique
know-how and many years of experience in the e-commerce market in Central and Eastern Europe.
PayU Czech Republic, Ltd. was founded in 2011 by the Naspers technology company, which
operates in the online market in the USA, China, Brazil, Africa, Russia, Poland and many other
countries, including the Czech Republic.
With this strong international presence, PayU offers complete payment services connected with
transaction processing, delivers innovative technology, safety and continuous development of their
services. The goal of PayU is to constantly bringing fast and secure payment solutions that will
simplify the payment process for shoppers and thus contribute to increased conversion on sales
platforms.
This guide is intended to make it easy for e-shops and partners to implement the PayU payment
gateway. In a few simple steps, it explains how to register for PayU, how the technical integration
works, what are the possibilities of visualization of the offered payment options, describes and
explains the functions and administration of the PayU account. The goal of this manual is to help you
implement the PayU payment gateway in the best possible way. It is essential in showing how to take
advantage of all the features and functions that PayU offers you and for your trading platform.
The manual is composed of seven color-coded sections. Each section provides a comprehensive
set of information on specific areas of implementation or operation of the PayU system.

From registration
to PayU launch

www.payu.cz

2.1 General information

This section describes in simple steps the process of establishing the payment gateway from
registration until a successful launch.
The following diagram clearly shows the steps required to implement the PayU payment gateway
in an e-shop:

registration at
www.payu.cz

contract

technical
implementation
according
to technical
documentation

IMPLEMENTATION OF THE PAYU PAYMENT GATEWAY

production
launch

activation
ofpayment
methods
according
to the contract

testing payment

www.payu.cz

2.2 Description of individual steps

Customer
(e-shop)

PayU
sales department

PayU
customer service

1. Information about PayU

at www.payu.cz

2. registration, creating
a PayU account (login
and password)
3. sending the contract
and contractual terms
5. logging in to the PayU
account, adding a Shop and
a POS and implementation

4. activation of the account

and a test payment

6. signing a contract
and sending the AML
identification to PayU

7. setting the contractual

payment methods
for the POS and activation

8. testing payment

9. request sales
department to activate
payment methods

10. verification of the

testing payment,
activation and checks

1.

The www.payu.cz website contains all important information regarding the PayU company and its
payment solutions.

2.

Tentative registration at https://www.payu.cz/manager/register?execution=e1s1

This registration is used to obtain information for later to create an user account and for the first
contact. It is important to mention information about your company according to the commercial
register and the correct contact information.

3.

Based on an interview with you, our sales representative will prepare an offer of commission levels for
different types of payments. Once you approve them, a draft agreement is sent to you for signing.

4.

A copy of the contract is sent to PayU customer service that checks whether the data in the contract
corresponds with your registration. If the data is correct your PayU account can be activated. The
data for your first login will be sent to you by email. Consequently, it is possible to set the parameters
required for implementation of the account. At the same time you can also use the system to make
test payments. A properly made test payment is an integral part of the implementation and without it
its not possible to successfully complete the implementation.

5.

You can now log in to your PayU account and begin with the implementation.

www.payu.cz

Basic setup of a PayU account to for beginning the implementation:

5.1

Setting up the Shop

Select Online Payments > My shops > Add shop

The first step is to enter the web address of your shop, shop name (optionally also its description) and
select the desired currency in which payments will be processed. If you want to process payments in
euros, that fact must be stated in the contract with PayU.
If you wish to use the PayU payment system on another web address than the one specified during
registration, you can add this address in your accounts setup. In this case it is necessary to create an
amendment to your contract with PayU where the preferred or the new web address will be defined.

www.payu.cz

5.2

Setting the POS (Point of Sale)

To set the values of a new POS, the following information mused be filled in:
a) POS name
b) Error return address (URL address where the payer will be redirected if the
transaction fails to authorize)
c) Successful return address (URL address where the payer will be redirected if the
initial authorization of the transaction appears to be successful)
d) Address for reports (URL address where you will be sent information about changes
of payment status using the POST method)
e) Data coding (character set)

www.payu.cz

5.3

Configuring the Point of Sale

Once you have added a POS, click it in the POS list. This will open Point of Sale configuration.
There is some very important information in this configuration that you need to implement the
payment gateway. These are the following:

10

www.payu.cz

After completing this step, you can begin the implementation, as described in chapter 3 under the
conditions set out in chapter 5, and perform test transactions, as described in chapter 3.7.
6.

Check the contract received from PayU, sign it and send it to the following address:
PayU Czech Republic, s. r. o.
Karolinsk 650/1
186 00, Praha Karln
Also send the information requested for identifying the company or individuals pursuant to Act No.
253/2008 Coll. on some measures against money laundering and terrorist financing.

7.

When PayU receives the signed contract, customer service will added the agreed payment methods
to your Point of Sale. This is what the POS list will look like:

11

www.payu.cz

8.

Complete the implementation. Make the test payment. It must be processed without any error
messages. The list of error messages can be found in Appendix 4. Report the successful completion
of the implementation to PayU customer service using the contact form in your PayU account:

9.

To activate the payment methods specified in the contract, contact your PayU sales representative
orsend a request to obchod@payu.cz.

10.

Upon your request to the sales department and after the verification of your implementation
according to chapter 5, the chosen payment methods will be activated for your POS. You will be able
to start accepting payments through the PayU payment gateway.

12

PayU
implementation

www.payu.cz

3.1 General information

This practical guide to implementing PayU payment gateway contains information needed
fortechnical integration with your trading platform.

3.2 Terms used in the application

PayU
The payment processing application.
Company
The company that uses the PayU application to receive payments from Customers.
Shop
An e-shop receiving payments; one company may run several Shops.
POS
The Point of Sale processing the received payments; for a given POS, all service parameters are
defined; one Shop can run multiple POS.
Customer
A person performing a payment.
UrlPayU
URL address where the PayU application is installed: https://secure.payu.com/paygw
UrlPositive
URL address of the Shop application where the Customer is redirected after a successful start
oftransaction.
UrNegative
URL address of the Shop application where the Customer is redirected after a failed start
oftransaction.
UrlOnline
URL address of the Shop application where notifications of changes in payment status will be sent
using the POST method.

14

www.payu.cz

3.3 Integration with PayU

3.3.1

Configuration data
In PayU, each Shop can have any number of POS.
For each POS, the following URL addresses can be defined: UrlPositive (return address on success),
UrlNegative (return address on failure) and UrlOnline (address for notification).
PayU allocates a set of configuration keys to each POS, consisting of a POS identifier (pos_id), code
strings key1 and key2 (see chapter 3.6) and an authorization key (pos_auth_key). All these data are
available in the PayU user interface after adding a POS.
The configuration keys can be found by clicking on:
My shops > Shop Name > POS list > POS name

3.3.2

URL addresses and available procedures of the PayU application

The PayU URL address is formed this way:
URL = UrlPayU/Encoding/ProcedureName
where
UrlPayU base address of the PayU application, i.e. https://secure.payu.com/paygw
Encoding one of the following values: ISO, UTF, WIN
ProcedureName jedna z nsledujcch hodnot: NewPayment, Payment/get, Payment/confirm,
Payment/cancel

3.3.3

Encoding
Depending on the character set used by your Shop application, the Shop can choose the character
encoding also when referring to PayU procedures:
name in PayU

encoding used

ISO

ISO-8859-2

UTF

UTF-8

WIN

Windows-1250

15

www.payu.cz

3.3.4

Data Format
For procedures Payment/get, Payment/confirm and Payment/cancel you can also specify the format
of data sent as shown below.
URL = UrlPayU/Encoding/ProcedureName/Format
Format can be either xml or txt. The default value is xml.

3.3.5

Creating a new payment

In a simplified way, the payment via the PayU works as shown on the diagram below:

7. PayU informs the e-shop of

the transaction status change

PayU

E-shop

3. E-shop sends the new

payment form to PayU

2. Choosing a payment
gateway in the PayU
template

1. Selection of goods /
services in the e-shop

Bank

6. The Bank
informs PayU of
the payment

4. The customer
is redirected to the
bank to pay

5. After payment, the customer

is redirected back to the e-shop
In order to create a new payment, a form that redirects the Customer to PayU the NewPayment
procedure (for list of PayU procedures see chapter 3.3.2) must be placed to the Shop website. It is
recommended to use the POST method, if not possible. The GET method can also be used.

16

www.payu.cz

Parameters of the new payments are as follows:

parameter

required
field

data type

description

pos_id

yes

INT

value assigned by PayU

pos_auth_key

yes

STR {7,7}

value assigned by PayU

session_id

yes

STR {1,1024}

Payment ID - must be unique for each transaction

amount

yes

NUM {1,10}

amount in hellers (1 CZK = 100 hellers)

desc

yes

STR {1,50}

Short description shown to the customer

on bank statements and elsewhere

order_id

no

STR {1,1024}

order number

desc2

no

STR {0,1024}

arbitrary information

first_name

yes

STR {0,100}

name

last_name

yes

STR {0,100}

surname

street

no

STR {0,100}

street

street_hn

no

STR {0,10}

land registry number

street_an

no

STR {0,10}

house number

city

no

STR {0,100}

city

post_code

no

STR {0,20}

ZIP code

country

no

STR {0,100}

customers country code (2 letters) according to ISO-3166

https://www.iso.org/obp/ui/#iso:code:3166:CZ

email

yes

STR {0,100}

e-mail address

phone

no

STR {0,100}

phone number (or several numbers separated by commas)

language

yes

ENUM

language code according to ISO-639

http://www-01.sil.org/iso639-3/
codes.asp?order=639_1&letter=c
(currently can be either cs or en)

client_ip

yes

STR {7,15}

clients IP address in the following format:

D{1,3}.D{1,3}.D{1,3}.D{1,3}

js

no

ENUM ( 0, 1 )

whether the clients browser has JavaScript enabled

sig

yes

STR {32}

checksum of parameters sent in the form

ts

yes

STR

timestamp used to calculate the value of the sig parameter

17

www.payu.cz

It is not mandatory to include the payer address parameters in the New payment form, however,
ifpossible, we recommend to use these parameters. Entering this information allows easier
identification of the payer in the event that it is necessary to match the payment manually.
Identification of the payer affects conversion in case of unpaired payments.

After creating a payment the customer will be redirected to the UrlPositive or UrlNegative address
using the GET method. Since its possible that the Customer does not return back to the Shop website
(e.g. the Customer closes their browser window before they can be redirected), the information
obtained through these URLs is not binding and cannot provide a basis to draw any conclusions
regarding the final status of payments.

Caution! Sometimes it can happen that the Customer accidentally choses the wrong
payment method (e.g. selects a bank where he doesnt have an account open or chooses
payment by a card which does not have with him at that moment, etc). Customer often realizes
the error only after hes redirected to the website of the bank or the card transactions provider.
At this point, the Customer often tries to go back a step using the browser buttons and then
select another payment method. In these cases, it is necessary to ensure that before a new
NewPayment request is sent to PayU, a new value of the session_id parameter is generated
(despite the fact that from the Merchants perspective this is still the same order). It is necessary
to create a new session_id because the PayU system creates a transaction record before
redirecting the customer to the bank, which also includes this parameter. Repeated use of
the same session_id value will cause an error that leads to the transaction being rejected.
Before sending the https://secure.payu.com/paygw/Encoding/NewPayment request it is
thus necessary to ensure that the used session_id was unique even in those cases where the
Customer has changed the method of payment chosen for the implementation of the same
order.
A simple mechanism to ensure the uniqueness of the session_id parameter may be e.g. linking
the internal order number from the Shop with a time stamp generated with a millisecond
precision (order_id = session_id + - + timestamp).

The standard way to create a payment form uses so-called PayU templates. The PayU system allows
you to select from two types of predefined templates. Creating a new payment form using these
templates is very easy and can be done in three steps:
1.

Inserting JavaScript libraries to <head> section of the HTML document

2.

Creating a simple form with the corresponding parameters

3.

Inserting a JavaScript snippet to the payment form

The JavaScript library can be loaded from this location in the PayU system:
UrlPayU/Encoding/js/pos_id/KK/template:x/ext_calc:y/paytype.js

18

www.payu.cz

where the parameters have the following meaning:

UrlPayU

base address of the PayU application

Encoding

one of the following values: ISO, UTF, WIN

pos_id

a value assigned by PayU; POS number (ID)

KK

the first two characters of Key1

template:x

template identifier, where x is a numerical value from the {3, 5} set

ext_calc:y

whether the sig parameter value calculation should or should not include
the pay_type parameter: 1 = yes, 0 = no

The template parameter refers to which type of predefined template should be used. If necessary,
the Shop is allowed to customize the template to suit their specific requirements. Any template editing
must be approved by the PayU payment system operator. Names and logos of payment channels and
the PayU logo cannot be removed or changed in any way.
The ext_calc parameter indicates whether the calculation of the sig parameter value should include
the pay_type parameter. If the ext_calc is 0 then the pay_type parameter is not included in the sig
parameter calculation and its value is not sent. If the ext_calc is 1 then the pay_type parameter is
included in the calculation of the sig parameter and its value is sent as the pay_type parameter.
JavaScript libraries should be placed in the <head> section of the HTML document (step 1 above) as
follows:
<head>
<script language=JavaScript type=text/JavaScript src=https://secure.payu.com/jsgenerator/js/
jquery-latest.js></script>
<script language=javascript type=text/javascript src=https://secure.payu.com/paygw/UTF/js/
pos_id/KK/template:3/ext_calc:1/paytype.js>
</script>
</head>
In this case, template number 3 is used (see Appendix 6) as the parameter defining the type of
template was assigned a value of 3. The English version of template number 3 is template number 5.

19

www.payu.cz

In accordance with step 3 above, this JavaScript snippet should be added to the payment form:

<script language=JavaScript type=text/JavaScript>

PlnPrintTemplate();
</script>
Example payment form with the snippet added:
<form action=https://secure.payu.com/paygw/UTF/NewPayment
method=POST name=payform>
<input type=hidden name=pos_id value=12345>
<input type=hidden name=pos_auth_key value=wq2iO3q>
<input type=hidden name=session_id value=1234565>
<input type=hidden name=amount value=1000>
<script language=JavaScript type=text/JavaScript>
PlnPrintTemplate();
</script>
<input type=hidden name=desc value=Payment description>
<input type=hidden name=client_ip value=123.123.123.123>
<input type=hidden name=js value=0>
<input type=hidden name=email value=example@example.cz>
<input type=hidden name=first_name value=Petr>
<input type=hidden name=last_name value=Novk>
<input type=hidden name=language value=cs>
<input type=hidden name=ts value=251013105655>
<input type=hidden name=sig value=9075ed67df1c3a4e5686ee7bbb78ad64>
<input type=submit value=Paywith PayU.cz>
</form>
<script language=JavaScript type=text/javascript>
<!-document.forms[payform].js.value=1;
-->
</script>

20

www.payu.cz

3.4 Exchange of information on transactions

The Shop application is obliged to verify the checksums of the transmitted information.
3.4.1

Notifying the Shop of transaction status change

Any change of transaction status is announced to the Shop application. PayU sends the POST request
to the UrlOnline address, including the following parameters:

pos_id

value assigned by PayU; POS identifier (ID)

session_id

value entered by the Shop when creating the payment

ts

timestamp, value needed to verify the checksum

sig

checksum of the transmitted information (see chapter 3.6)

sig_ext

internal datum of PayU system

sig_ext_order

internal datum of PayU system

The sig value is calculated using the following formula:

sig = md5(pos_id + session_id + ts + key2)
The transaction status change notification does not include any other information. Details of
the transaction and its current status must be read and analyzed by the Shop application using
mechanisms described in chapter 3.4.2.
Upon receipt of that request, the Shop application MUST send back a response with the OK string.
If the PayU application receives a different response than this, the response will be saved to the
database and the transaction status change notification shall be deemed not received.
The Shop application should allow for situations where the notification regarding a single transaction
is posted several times despite the fact that the transaction status hasnt changed. OK should
normally be sent in response to each such repeatedly received notification.
A single POST request at a time is normally sent to a specific POS, but it is also possible for several
requests to the same POS to be sent at the same time.

21

www.payu.cz

Notification is sent immediately after the transaction status change. If the Shop application does not
confirm receipt of the notification as required, notification will be re-sent to the Shop application
again with the following delay:

3.4.2

attempt

delay

0 10

1 minute

11 15

3 minutes

16 20

5 minutes

21 25

10 minutes

26 50

15 minutes

51 75

30 minutes

75 99

60 minutes

> = 100

re-sending stops

Recognizing the transaction status

In order to read the current transaction status, it is necessary to call the Payment/get procedure (for
the list of PayU procedures see chapter 3.3.2) using the POST method with the following parameters:

pos_id

value assigned by PayU; POS identifier (ID)

session_id

value entered by the Shop when creating the payment

ts

timestamp, value needed to verify the checksum

sig

checksum of the transmitted information (see chapter 3.6)

The sig value is calculated using the following formula:

sig = md5(pos_id + session_id + ts + key1)

22

www.payu.cz

In response, the Shop application will receive the following information:

txt format:

status: OK
trans_id: 7
trans_pos_id: 1
trans_session_id: 417419
trans_order_id:
trans_amount: 200
trans_status: 5
trans_pay_type: t
trans_pay_gw_name: pt
trans_desc: Platba pro shop.cz
trans_desc2:
trans_create: 2012-12-21 10:39:52
trans_init: 2012-12-21 10:41:03
trans_sent: 2012-12-21 10:41:44
trans_recv:
trans_cancel:
trans_auth_fraud: 0
trans_ts: 1094205761232
trans_sig: b6d68525f724a6d69fb1260874924759
xml format:
<?xml version=1.0 encoding=UTF-8 ?>
<response>
<status>OK</status>
<trans>
<id>7</id>
<pos_id>1</pos_id>
<session_id>417419</session_id>
<order_id></order_id>
<amount>200</amount>
<status>5</status>
<pay_type>t</pay_type>
<pay_gw_name>pt</pay_gw_name>
<desc>Platba pro shopcz</desc>
<desc2></desc2>
<create>2012-12-21 10:39:52</create>
<init>2012-12-21 10:41:03</init>
<sent>2012-12-21 10:41:44</sent>
<recv></recv>
<cancel></cancel>
<auth_fraud>0</auth_fraud>
<ts>1094205828574</ts>
<sig>a95dc2145079b16a3668175279c35736</sig>
</trans>
</response>

23

www.payu.cz

For the data sent back by PayU, the value of sig is calculated using the following formula:
sig = md5(pos_id + session_id + order_id + status + amount + desc + ts + key2)

The notification fields are described is as follows:

Basic fields:

txt field

xml field

description

Status

responsetatus

indicates the processing state: success OK

trans_id

response/trans/id

unique transaction ID; assigned by PayU

trans_pos_id

response/trans/pos_id

ID of the POS for which the transaction was created

trans_session_id

response/transession_id

value assigned by the Shop application when the

transaction is created

trans_order_id

response/transorder_id

value assigned by the Shop application when the

transaction is created

trans_amount

response/transmount

current value of the transaction in haler (heller)

trans_status

response/transtatus

current transaction status according to Appendix 2

trans_pay_type

response/trans/pay_type

payment type according to Appendix 1

trans_pay_gw_name

response/trans/pay_gw_
name

name of the gateway performing the transaction

internal information of the PayU application

trans_desc

response/trans/desc

value assigned by the Shop application when the

transaction is created

trans_desc2

response/trans/desc2

value assigned by the Shop application when the

transaction is created

trans_create

response/trans/create

transaction creation date

trans_init

response/trans/init

transaction start date

trans_sent

response/trans/sent

date the transaction was sent for collection

trans_recv

response/trans/recv

date the transaction was received

trans_cancel

response/trans/cancel

date the transaction was cancelled

trans_auth_fraud

response/trans/auth_fraud

internal information of the PayU application

trans_ts

response/trans/ts

value needed to calculate the checksum

trans_sig

response/trans/sig

checksum of the transmitted information

24

www.payu.cz

Other fields for selected methods of payment:

Test payment

3.4.3

txt field

xml field

description

add_test

response/trans/add_test

always 1

add_testid

response/trans/add_testid

transaction ID

Receipt of payment
To receive the payment, i.e. to confirm the transaction, it is necessary to invoke the Payment/
confirm procedure using the POST method and specify the same parameters as for transaction status
recognition (see chapter 3.4.2). It is necessary to receive payments if automatic receiving of payments
is turned off (otherwise payments are received automatically). Payments with status 5 - awaiting
receipt can also be received this way. Alternatively, you can also receive payments through the user
PayU interface on the List of transactions page.

3.4.4 Rejection of payment

To refuse the payment, it is necessary to invoke the Payment/cancel procedure and enter the same
parameters as for transaction status recognition (see chapter 3.4.2). Rejection of payment is used
if automatic receiving of payments is turned off. If payment is rejected in time shorter than time of
automatic cancellation of payment (see Appendix 1), it will be canceled automatically. Payments with
status 5 - awaiting receipt can also be rejected this way. Alternatively, you can also reject payments
through the user PayU interface on the List of transactions page.
3.4.5

The operation complete status

Responses received after the Shop application invokes the Payment/confirm and Payment/cancel
procedures are as follows:
Successful execution txt format:
status: OK
trans_id: 7
trans_pos_id: 1
trans_session_id: 417419
trans_ts: 1094206530505
trans_sig: 9da7c868407fedae6f1b6aca9054632b

25

www.payu.cz

Successful execution xml format:

<?xml version=1.0 encoding=UTF-8?>
<response>
<status>OK</status>
<trans>
<id>7</id>
<pos_id>1</pos_id>
<session_id>417419</session_id>
<ts>1094205828574</ts>
<sig>a95dc2145079b16a3668175279c35736</sig>
</trans>
</response>

Receiving the OK status in these cases does not mean that the transaction was successfully
confirmed/canceled. These responses only confirm receipt of the request for processing. Confirmation
of the transaction status change is sent separately using the standard way the UrlOnline addresses.
For the data sent back by PayU, the value of sig is calculated using the following formula:
sig = md5(pos_id + session_id + ts + key2)
Error txt format:
status: ERROR
error_nr: 503
error_message:
Error - xml format:
<?xml version=1.0 encoding=UTF-8?>
<response>
<status>ERROR</status>
<error>
<nr>503</nr>
<message></message>
</error>
</response>

26

www.payu.cz

3.5 The structure of the UrlPositive and UrlNegative return addresses

After completing the payment you can redirect the Customer to the URL specified in the POS settings.
Depending on the current transaction status, either UrlPositive or UrlNegative is used as the redirect
address. Customer is redirected to UrlPositive after successfully entering a payment in his internet
banking (in case of quick online transfers) or on the website of a card transaction processor (when
paying by card). If it is a payment by transfer or postal order, the Customer is redirected to UrlPositive
after he receives the information needed to make a payment. Redirect to UrlNegative occurs in the
event that payment is not started correctly.
The return UrlPositive and UrlNegative addresses are used for informational purposes only. Therefore,
is not possible to draw any conclusions regarding the final status of payments based on the redirection
to these addresses. Even if you are redirected to UrlPositive, the payment may remain incomplete (e.g.
the Customer may not have sufficient funds for payment on his account; in case of a bank transfer or
postal order, the Customer may not use the generated payment information at all, etc). Therefore, in
order to find out the transaction status, it is always necessary to invoke the Payment/get procedure
(see chapter 3.4.2). Information about the current transaction status can also be found in the PayU
user interface.
The return address can contain the following constants which are replaced upon redirecting by the
corresponding values in the following table:

constant

description

%transId%

new transaction identifier created in the PayU application

%posId%

pos_id values

%payType%

pay_type values

%sessionId%

session_id values

%amountPS%

amount values, separated by dot

%amountCS%

amount values, separated by comma

%orderId%

order_id values

%error%

error number according to table (see Appendix 4), used only in case of UrlNegative

Examples:
http://www.shop.cz/status_ok.html?pos_id=%posId%&session_id=%sessionId%
http://www.shop.cz/status_error.html?pos_id=%posId%&session_id=%sessionId%&error=%error%

27

www.payu.cz

Information about the values of the above constants can be used by the Shop application in many
different ways. According to the payment type information (pay_type), it is for example possible to
specify different notices displayed to the Customer at URLPositive for different payment channels.
Based on the value of the session_id parameter, the Shop application can offer the Customer a link
to a new payment for the same order (but with a new session_id value, because it must always be
unique) in cases where the initial payment remains uncompleted. The error number (see Appendix
4) allows the Shop application to determine the reason why the payment has not been created (we
recommend to use this example in the testing phase because it allows to quickly identify and remove
causes of the most common problems when creating new payments), etc.

UrlOnline is the third address which can be defined for each POS. PayU sends transaction status
change notifications (see chapter 3.4.1) to this address.

3.6 MD5 checksums

Each time you send a request to by the Shop application and for each response created on the PayU
side, an MD5 checksum is created which allows you to verify data integrity.
Checksums are created using the following formula (+ stands for character strings concatenation):
sig = md5(pos_id + session_id + value1 + value2 + + valuen + ts + key)
where:

pos_id

value assigned by PayU

session_id

Payment ID - unique for each transaction

value1...valuen

list of other values listed in the descriptions of particular methods

ts

any string of characters such as the current time in seconds (recommended)

key

a string of characters known by both PayU and the Shop

28

www.payu.cz

In the PayU application, two key values are assigned to each pos_id:

key1 used to create a checksum that is sent by the Shop

key2 used to create a checksum that is sent by PayU
3.6.1

Checksum parameters passed on to a new payment

The Shop application is required to indicate the checksum of the transmitted parameters in the
new payment form (NewPayment). Adding a checksum to the new payments is a mechanism that
increases the security of the system against attacks from the outside and ensures a smooth and
trouble-free transaction.
The following two parameters must be specified is the new payment form to create a checksum:
ts timestamp, the value needed to verify the checksum; any string of characters such as the current
time in seconds (recommended)
sig checksum of the transmitted information
The sig value is calculated using the following formula:
sig = md5(pos_id + pay_type + session_id + pos_auth_key + amount + desc + desc2 + order_id
+ first_name + last_name + street + street_hn + street_an + city + post_code + country
+ email + phone + language + client_ip + ts + key1)
If one of the values is not transmitted in the form used to create a new payment, use an empty string.
If the value of the pay_type parameter is not known at the time of sig parameter calculation, the ext_
calc parameter in the PayU template URL (see section 3.3.5) should be set to 0.
If no the value of the sig parameter is not calculated properly or if the values of other parameters
transmitted change, the new payment will not be created (Customer will be redirected to the
UrlNegative address with error code 103). Using the checksum thus works as a safety check, ensuring
that no unauthorized change of parameter values payments remains unnoticed.

29

www.payu.cz

3.7 Testing

So called test payments (payment type t, see Appendix 1) are used for testing the implementation of
the PayU payment system. These payments are treated as real transactions, the only difference being
that the funds transferred are not real.
Test payments allow you to check the integrity of the data transmitted by the Shop to the PayU
application. Using test payments it is possible to verify redirects to the UrlNegative and UrlPositive
return addresses, as well as UrlOnline communication. In addition to the NewPayment procedure, test
payments can also perform the Payment/get, Payment/confirm and Payment/cancel procedures.
Using test payments, various payment transaction statuses (see Appendix 2) and transitions between
them (see Annex 3) can be created. Using test payments does not change the Shop account balance;
any number of them can therefore be created.
If creating a test payment causes redirects to UrlNegative, it is possible to determine the error number
by placing the %error% constant in the address (see Section 3.5). Based on tables located in Appendix
4 is possible to determine the cause of the problem and then solve it.
Since the test payments work on the same principle as the actual payments, in case they operate
smoothly, it is possible to proceed with launching the PayU payment system in production.

30

Appearance
of the PayU
payment
gateway
in the e-shop

www.payu.cz

This part of the implementation manual shows how to properly set up completing a purchase with
PayU and how to display different payment methods.

4.1 Visualization and description of payment methods

PayU has spent a long time analyzing the clarity of payment method description. The following
instructions are the result of the analysis. Theyre designed to help the customer to rapidly get their
bearings when choosing a payment method.
There are 2 ways to display the payment methods:
1. Static JavaScript template
2. Dynamic JavaScript template (the drop-down variant)
The PayU JavaScript payment template allows you to leverage the PayU experience in the purchasing
process and provide your customers with a clear and visually pleasing rendering of payment methods
and their clear identification with logos of banks and payment institutions that are familiar with.
Both templates are available in Czech and English version (see Appendix 6). Examples of template
implementations in particular e-shops are shown in Appendix 7.

4.2 Implementation
Implementation of PayU payment templates involves placing JavaScript source code into your
website. You can choose between the static and the pop-up template, whichever is more suitable for
your shopping process. The payment template allows the e-shop customer to select the payment
method, to store the selected data and send the customer directly to the bank. The e-shop can place
the template into the shopping process. Then the customer can proceed to the next steps of the
purchasing process, e.g. the confirmation of the order, etc.
For detailed instructions on how to implement the JavaScript PayU template, see section 3.3.5.
Customization
The payment template can be adjusted using CSS styles. Is it possible to change the template width,
background color, text color and style. You cannot change the description of payment methods,
pictures, the order of payment methods the PayU footers or the number of payment methods per line.
If possible, we recommend you to keep the template background white or use very light colors. The
darker the color you choose, the greater the possibility that the image and the template elements
will appear jagged and the template will not look professional. That could affect the credibility of the
payment system and subsequently the conversion rate of your e-shop.
In case you want to use a custom payment method selector (without using the templates), follow
these rules:
1. Present the payment methods in separate units as follows:
a. payment buttons and the standard bank transfer
b. debit card and Mobito
c. postal order

32

www.payu.cz

2. In case you are displaying other payment methods apart from the methods facilitated by
the PayU payment gateway, display those separately, too. This means to display the PayU
payment methods separately from other payment methods.

3. You can use a line or space between groups of payment methods as a separator.
4. The PayU payment methods must always be presented with the following symbols:
a. PayU - Secure and fast payments - download banners here:
http://www.en.payu.cz/downloads
b. In case youre using payment cards - download security logos here:
http://www.en.payu.cz/downloads
5. Always call the bank buttons quick bank transfers
6. For each payment method you must display the logo and name of the payment method
in the same way as they are displayed in the PayU template (see Appendix 6).

4.3 The purchasing process and user-friendly implementation

According to some studies of online shopping behavior up to 75% of buyers leave the e-shop without
paying for the goods. Before the customer buys the goods and pays, hes forced to click through or go
through a variety of operations which are often unnecessary.
Wrong configuration of the final shopping process stage (checkout) is to blame here. E-shop often
unknowingly complicates the path to complete the purchase, order confirmation and payment. The
process is lengthy, confusing, the e-shop asks the customer to provide a number of things - forces
him to register, requires filling in personal data. A properly adjusted checkout in combination with an
immediate payment for goods significantly contributes to higher purchase conversion rates and thus
increases sales. By purchase conversion we mean order confirmation and payment for goods.

4.4 Optimizing the purchasing process

The whole shopping process should ideally be set up to lead to a single goal: the successful
completion of the transaction, i.e. the payment for goods.
As a general principle, the more intuitive and the faster the process is, the less likely the customer
is to leave it prematurely.
Simplifying the shopping process requires optimization of three basic key elements: navigation,
visualization and speed.

33

www.payu.cz

4.5 Navigace a vizualizace

Nowadays, the Customer has plenty of opportunities to choose the best offer. He uses the opportunity
to compare goods, for example using Heureka.cz. He therefore often leaves the e-shop during
shopping to compare parameters, price, references and quality of different shops. Therefore it is very
important to provide the buyer as much information directly in your e-shop and go through checkout
as quickly as possible.
An ideal checkout process should have four steps at most. A single-page customer checkout definitely
has higher conversion rate, but only if the customer is able to understand the entire process well.
Necessary elements are a navigation bar, prominent buttons for continuing to the next step, and the
ability to leave the shopping cart and go back to the previous step. The ability to go directly to the
product page or the opportunity to compare similar products in the cart are big advantages for the
customer.
From the Customers perspective, an e-shop always has greater credibility if it cooperates with wellknown and trusted institutions. Any logos of banks, security systems, certificates and payment methods
providers represent this credibility and are always beneficial for the e-shop, so it is ideal to display
them during the checkout process. They increase the sense of security and confidence in the e-shop.
Photographs are an equally important element of visualization. High quality and sufficiently detailed
photographs of the product can reduce exit rate by 20%. Excessive postage is the most common
reason for leaving the e-shop without completing the purchase. If there is no way to reduce the cost of
postage, try to present the expected amount at the beginning of the shopping process.

4.6 Speed and conversion rate

To speed up the shopping process, it is good to focus on eliminating any unnecessary steps and barriers
that can impede the customer. Examples include the need for registration and disclosure of personal
information. Allowing a purchase without registration is an interesting way to increase the number
of completed and paid orders. The faster the customer is led through checkout, the higher purchase
conversions will be achieved.
Simple and fast payments are perhaps the most underestimated and yet the most affordable way to
optimize the purchasing process. They are relatively new in the Czech environment, yet they are the
key to higher purchase conversion rates. Unlike cash-on-delivery or a standard bank transfer, the
Customer does not leave the e-shop before paying.
The order and payment are part of a single process: Customer goes through the e-shop from the
decision to buy to the payment in a short period of time and the actual payment in the case of quick
on-line payments takes no more than a few seconds. On the other hand, in case of cash-on-delivery
or a standard bank transfer, it is possible for the customer to change his mind or to buy at your
competitor. The simpler the checkout and payment, the higher conversions and sales for the e-shop.

34

www.payu.cz

4.7 A functional template

We have many years of experience optimizing the checkout process. Based on analyses of shopping
behavior, we have developed a functional template for payment in advance. The template is used by
e-shops that want to increase purchase conversion using quick online payments. In agreement with
the banks, we modified the visualization and description of payment methods to be as understandable
as possible for the shoppers. The payment methods are arranged to direct shoppers first to the quick
transfer from their bank and only then to the card payment, which has higher cost per transaction.
The template is clear and easy to read and can be placed directly into the e-shop.

4.8 Education of customers and marketing

Each customer will appreciate being sufficiently informed about payment progress and the actual
payment for goods or services. For Standard Bank Transfer and Payment by postal order via
Czech Post PayU offers the possibility of activating a service for sending e-mails showing payment
information directly to the Customers e-mail. Thanks to that the Customer is assured that the data
entered is correct while also reducing any errors. If you are interested in trying out the PayU template,
you can visit our testing e-shop at http://payu.fcostry.cz/

35

www.payu.cz

4
Inserting the PayU logo or banner is also a part of a successful implementation. These are available for
download at http://www.en.payu.cz/downloads
PayU also provides an educational mailing for clients. You will be informed how you can reduce the
error rate when of online payments and increase you conversion rates.
For more information please contact our sales team or our customer support staff.

36

The mandatory
parameters of
implementation

www.payu.cz

Before launching the PayU payment system into production, the e-shop must meet the following
requirements:

1. Deployment of all payment methods in accordance with the contract.

2. Correct description and visualization of payment methods (see chapter 4).
3. Correctly implemented return addresses (see section 3.5)
4. Correctly implemented checksums (see section 3.6).
5. A positive result of test payments.
6. Placing the PayU logo (optionally also banners and other graphics) on the main page
of the e-shop and on the page with payment method selection page.
7. Each payment method must display its logo to improve its recognition by shoppers
(logos are displayed automatically if templates are used implementation).
8. All payment methods must be on the same page, therefore there must not be a step
where shoppers choose PayU in the list of payment methods PayU is a payment
gateway offering payment methods not a payment method.

38

PayU account
administration

www.payu.cz

6.1 General information

This chapter is devoted to setting up and using your PayU account. It will help you set up everything
you need from the first login to your account and navigate the PayU user interface.

6.2 PayU user interface

You can login to the PayU user interface by clicking the Log in new PayU account 2.0 link,
which is located on the PayU homepage (http://www.payu.cz).

After clicking the link, the user is redirected to https://secure.payu.com/user/start?lang=en, which

requires a user name and password and then clicking the Log in button.

40

www.payu.cz

6.3 Creating a Shop and a POS

After logging into the user interface for the first time, the user is prompted to create a Shop (creating
a Shop and a POS is also briefly described in chapter 2.2).

After clicking on the Add shop the first step is to choose a website address of the Shop, Shop name
noted (optionally also its description) and select the desired currency. If the user is interested in
processing euro payments in his Shop, this fact must be stated in the contract with PayU.

41

www.payu.cz

If the user is interested in using the PayU payment system on another web address than the
one specified during registration, he can add this address. In that case it is necessary to make an
amendment to the contract with PayU.

42

www.payu.cz

In the second step, the POS name must be specified and the desired data coding selected. Also,
it is possible to define the error return address (UrlNegative), the successful return address
(UrlPositive) and the address for reports (UrlOnline) for this POS. The Secure my transaction/
Check sig correctness must be left checked for the correct checksum value to be verified when
creating anew payment.

After clicking the Add shop button, a page will be displayed with configuration data of the created
POS, which is necessary for implementing the payment system to the Shops website (pos_id, key and
second key (MD5) and the pos_auth_key authorization key).

43

www.payu.cz

After clicking the End button, the Shop is added to the list of shops that are located in the Online
Payments tab under My shops.

Another Shop can be added by clicking the Add shop button.

44

www.payu.cz

Another POS can be added to an already existing Shop by clicking POS list in the Shop

45

www.payu.cz

followed by clicking on Add POS

Shop details can be viewed by clicking on the Shop name,

POS details can be viewed by clicking on the POS name.

46

www.payu.cz

The POS information also shows payment types available for a given POS including commissions
(before production launch only a test payment is available). In POS configuration, the user can disable
or enable the function of automatic receipt of payments, either for each payment type individually or
collectively for all types of payments.

6.4 Transactions
The list of transactions is in the Online Payments tab under Transactions. Transactions in the list
can be searched according to various criteria.

47

www.payu.cz

Details of each transaction can be viewed by clicking on the transaction description.

48

www.payu.cz

The transaction details page looks like this

After clicking on Show reports it is possible to manually send the transaction status change
notification to Shops UrlOnline address. The function is useful especially during the implementation
phase and while testing the payment system. In other cases, sending notification is completely
automatic and it is not required to initiate it this or any other way.

49

www.payu.cz

On the List of transactions page, transactions with status awaiting receipt can be
received or cancelled

transactions with status rejected can be received or cancelled

and transactions with status new can be cancelled.

50

www.payu.cz

6
On the List of transactions page, payment refunds can also be performed. Only payments with status
ended can be refunded. After clicking the Refund link

and clicking the Next button on the following page

you can specify the amount to be refunded (you can refund the entire amount of the transaction or
any part thereof), post a message for the recipient in the Refund for field and choose one of three
types of manual refund methods - bank transfer, foreign bank transfer or payment by postal order.

51

www.payu.cz

Based on the chosen refund method it is then required to fill in the fields in the Refund receivers
data and click the Make refund button.

52

www.payu.cz

For certain types of payments, the automatic (the same as payment method) option can be
selected in the Refund method section. When using this option, theres no need to enter any
further information after clicking the Make refund button, the payment is refunded to the
account from which it was sent.

Alternatively, it is possible to initiate a refund from the Online payments > Transactions > Refunds
by clicking the New refund button

53

www.payu.cz

and entering the number of the transaction to be refunded on the next page.

6.5 Billing, Collection and Refund payments

The History of billing and transactions list can be found in the Online Payments tab under the
Transactions > Billing link.

This page can be searched by various criteria, like the List of transactions page. However, search
results differ by also including information regarding billed commissions in addition to information
about transactions. Also listed here is the current Shop balance after each operation (i.e. after
receiving the transaction, billing the commission etc).

54

www.payu.cz

The Payouts page (Online Payments > Transactions > Payouts) allows you to search in the
history of payouts (transfers of balances of Shops to bank accounts associated with these Shops).

The Refunds page (Online Payments > Transactions > Refunds) allows you to search in the
history of refunded payments. You can initiate a payment refund using the New refund button, as
already mentioned above.

55

www.payu.cz

6.6 Payouts
You can ask to transfer the Shops current balance to the bank account associated with this Shop at
any time by clicking the Pay out funds button located on the Online payments > My shops page.

However, it is not always necessary to request withdrawals manually as described above. Rules for
automatic withdrawals can be also defined in the user interface. After clicking on the Automatic
payouts link in the Shop on the Online payments > My shops page

56

www.payu.cz

and selecting Edit automatic payouts

automatic payouts are activated by checking Yes next to the Automatic payouts are active option.
Then you must specify the Minimum amount of payout (if Shops balance is less than this amount,
the payout is not performed) and choose one of the three Frequency of payouts options (such as
periodically, i.e. every time after the specified number of days). Then press the Save changes
button to confirm the payouts.

57

www.payu.cz

Further optional Frequency of payouts options are On selected weekdays and On aselected
day in amonth. The first one allows you to make payouts on the specified day of the week,

the second one on a specified day of month.

58

www.payu.cz

6.7 PDF/CSV/ABO Statements

Using the user interface, it is possible to download a statement of transactions in 3 different formats
- PDF, CSV and ABO. The PDF format is suitable for printing. The CSV format can be open in MS
Excel (or any other spreadsheet application). The ABO format (.gpc) is compatible with accounting
software (bookkeeping programs). Reports in this format can be imported into these programs and
thus incorporate this data about transactions from the PayU system into corporate accounting.
Reports in all three formats can be generated once or periodically. To create a statement report, go to
Online payments > Statements> Periodical statements and click on the Create a new periodical
statement button.

On the following page, select the Shop for which the statements are to be generated, specify
the e-mail address to which the statement is to be sent, select requested language and select the
Frequency, i.e. define how often the desired statement is to be created. In the example below you
can see the after each payout option chosen. In addition to this option, the statements can be set to
be created at a specific day of month, a specific day of week or repeatedly after a certain number of
days (i.e. the available options are similar to those for automatic payouts).

59

www.payu.cz

You also need to select the desired File format. Depending on the selected format, it is possible
to specify further settings. The most exible format is CSV. This type of statement may contain the
following information: type of operation, date, transaction ID, amount, account balance, change
account balance, order ID, description, description 2 / account number, payment type, city, postal
code, phone, e-mail address, street, name and surname, commission fees and currency. To add the
requested data to the report select it using your mouse and click on the > button. You can add all
the data to the statement by clicking the >> button.

A CSV statement with a semicolon (;) as the field delimiter and a quote () as the text delimiter
looks as follows:

60

www.payu.cz

A CSV statement with a semicolon (;) as the field delimiter and a quote () as the text delimiter
looks as follows:

The ABO format allows you to select which data is to be placed in the variable symbol column
and whether the statement should also include commission records.

61

www.payu.cz

The PDF format allows you to choose between two statement templates.

The Statement template contains the following data: date, operation type, transaction ID, currency,
amount, commission fees, account balance, description/account number and a summary of the given
period.

The Summary template contains only a summary of the given period.

62

www.payu.cz

To activate the statement after filling in all the required fields, you must confirm it by clicking the
Add button.
After clicking this button, a newly created request for generation of Periodical statements is shown
in the table on the Online Payments > Statements > Periodical statements page. An overview of the
already generated Periodical statements can be viewed by clicking the List of periodical statements
link on the same page.

A one-time statement can be created on the Online payments > Statements > Statements on
demand page by clicking on the New statement button.

63

www.payu.cz

Same as with periodic statements, on the next page you need to choose for which Shop the report
is to be created, requested language and to which E-mail it is to be sent. In this case the frequency
field is replaced by the period for which the statement is to be created. Just like with periodic
statements, the other settings then depend on what File Format is selected. After filling in all the
required fields the statement will be created after clicking the Generate button located at the bottom
of the page.

Once the request to create a single statement is created, it is displayed on the Online payments >
Statements> Statement on demand page. Information about the current request status is indicated
in the Status column. After the statement is sent to the requested email address, the status is
changed to Generated. Statements that have already been generated by the system one can be
obtained again by clicking the Download button. In this case the statement is no longer sent via
email, but can be directly opened or saved on a computer instead.

All periodic as well as on demand statements are always compressed using the ZIP method.

64

www.payu.cz

6.8 Statistics

Statistics located on the Online payments > Statistics page are used to display statistical data for
the required period. You can choose between daily, monthly and yearly data. Data can be displayed
only for the specific Shop or for selected types of payments. You can choose between number of
transactions, transaction amount and number of transactions and their amount using the Scope
field. Presentation of statistics is activated by clicking the Show button.

65

www.payu.cz

The requested data is displayed as a chart and a table. If the chart shows the amount of transactions
(cash amount paid using the various types of payments), you can press the Number of transactions
button to display the number of payments and vice versa. After you move your cursor over any of the
chart columns, its numerical value will be shown.

The table shows the same data as the chart.

66

www.payu.cz

6.9 Notification settings

Using the Account Configuration > Notification settings page, you can activate sending general or
transaction notifications by email. To send notifications by email, click on the Enable button.

6.10 User accounts

The list of user accounts is located on the Account Configuration> User accounts page. A new user
account can be created using the Add user button.

On the next page you need to fill in the details about the new user (the Login, Name, Surname,
E-mail and Phone fields) and choose whether this should be an account of an Administrator or
a User for your company. An Administrator has access to all the data and functions in the user
interface, while User access rights can be limited. For a User account you can select whether the
account owner should have Privileges to view invoices. After completing all required fields, you can
continue by clicking the Next button.

67

www.payu.cz

On the following page you can select in case of a User account which functions and Shops the
account owner should have access to. To complete creating the account, click the Add user button.

68

www.payu.cz

The newly created user account is then added to the list of users on the Account Configuration
> User Accounts page. The password of the new user account is delivered to the email address
listed in the account settings.

Any operations that can be performed with user accounts are displayed after moving your cursor over
the Options link located in the Action column. For user accounts, you can activate the function of
sending transactions notifications by email (the Notifications link). It is also possible to Edit users
contact information and Remove or Block a user account (a blocked account may be unblocked, as
opposed to a deleted account). It is also possible to generate a new password for a user account.

69

Appendices

www.payu.cz

Appendix 1 Types of payments

name

transaction limit (CZK)

automatic
cancellation
time (days)

description

cs

3,00 999999,99

10

PLATBA 24 esk spoitelna

mp

3,00 999999,99

10

mTransfer mBank

kb

3,00 999999,99

10

MojePlatba Komern banka

rf

3,00 999999,99

10

ePlatby pro eKonto - Raiffeisenbank

pg

3,00 999999,99

10

GE Money Bank

pv

3,00 999999,99

10

Sberbank

pf

3,00 999999,99

10

Fio banka

era

3,00 999999,99

10

Era - Potovn spoitelna

cb

3,00 999999,99

10

SOB

psc

3,00 999999,99

10

PaySec

3,00 999999,99

10

Platebn karty pes GPE

mo

5,00 10000,00

10

Mobito

bt*

3,00 999999,99

14

Bank transfer

pt*

3,00 999999,99

14

Post transfer (postal money order)

0,50 1000,00

Test payment a page is displayed that allows

you to select between redirecting to UrlPositive
or UrlNegative

* For these payment methods is essential for the Customer to make the payment according to
instructions displayed on the screen, including the bank account number, variable symbol, specific
symbol and the exact amount. This information is available to the Customer even after leaving the
website. You can activate a feature that will send the information required to make the payment to
the Customer via email. To activate this function at your Shop, please contact the PayU staff. If you are
interested, these reports can also include an email address you specified as the sending email.
The order of payment channels available on the Shops site should be the same as in this document.

71

www.payu.cz

Appendix 2 Transaction status

status

description

new

cancelled

rejected

started

awaiting receipt

reject done

99

ended

888

wrong status please contact us

Status 1 new appears when the Shop application successfully invokes the NewPayment procedure.
Status 2 canceled appears automatically after a certain number of days (see Appendix 1) since the
creation or start of the transaction (status 1 or 4), unless the payment is paid within this term (funds
are transferred to the PayU account).
Status 2 canceled also appears when transaction with status 1 new or 5 awaiting receipt
iscanceled by the Shop application or by the user.
Status 3 rejected appears when a transaction had been canceled (status 2) that was then paid
(funds are transferred to the PayU account). Transaction should be received or cancelled by Shop
within as many days (more exactly, until as many 24 hour periods), as it takes for the automatic
cancellation of the transaction (see Appendix 1). If the payment is not received within this time, it is
cancelled automatically and funds are returned to payer
Status 3 rejected will also appear in the case when a transaction with status 5 - awaiting receipt
is canceled and the selected payment method does not allow automatic refund to the Customer.
If atransaction with status 3 is accepted and the automatic payment reception is disabled, the
transaction receives status 5 awaiting receipt. To complete the transaction and change its status
to99 ended, it is necessary to accept the transaction again.
Status 4 started is a temporary condition and may not appear. Transactions can change their
status to awaiting receipt or ended (in case that automatic payment reception is enabled) directly
following status 1 new.
Status 5 awaiting receipt is displayed only when automatic payment reception is disabled. A Shop
should receive a payment within as many days (more exactly, until as many 24 hour periods), as it
takes for the automatic cancellation of the transaction (see Appendix 1). If the payment is not received
within this time, it is automatically canceled.
Status 7 reject done appears if a transaction with status 3 is canceled.
Status 99 ended means the transaction finished successfully. This is the ultimate, unchanging
transaction status. At the moment a transaction is assigned status 99, the Shop can inform the
customer about the fact that the payment was paid (recommended).
Payments can be received and cancelled using the Payment/confirm and Payment/cancel procedures
(see chapters 3.4.3 and 3.4.4). Receiving and cancelling payments can also be performed in the PayU
user interface using tools on the List of transactions page.

72

www.payu.cz

Appendix 3 Transitions among transaction states

If automatic payment receipt is disabled:
Awaiting
receipt
(status 5)

New
(status 1)
Started
(status 4)

If its possible to cancel

the transaction
Cancelled
(status 2)

Rejected
(status 3)

Reject done
(status 7)
Ended
(status 99)

73

www.payu.cz

If automatic payment receipt is enabled:

New
(status 1)
Started
(status 4)

Cancelled
(status 2)

Rejected
(status 3)

Reject done
(status 7)
Ended
(status 99)

74

www.payu.cz

Appendix 4 Error codes

code

description

100

pos_id parameter missing

101

session_id parameter missing

102

205

the transaction amount is smaller

than the minimum value

206

the transaction amount is greater

than the maximum value

ts parameter missing

207

exceeded the value of all transactions

for a single customer for the last period

103

sig parameter missing

or invalid sig value

209

invalid pos_id or pos_auth_key

104

desc parameter missing

210

transaction amount contains

unallowed hal (heller) entries

105

client_ip parameter missing

106

first_name parameter missing

212

transaction request more frequent

than one per minute
(for not activated company)

107

last_name parameter missing

500

transaction doesnt exist

108

street parameter missing

501

transaction authorization missing

109

city parameter missing

502

transaction has already started earlier

110

post_code parameter missing

111

amount parameter missing

503

transaction authorization
has already been done

112

wrong bank account number

504

transactions were previously revoked

113

email parameter missing

505

transactions were previously accepted

114

phone parameter missing

506

transaction was selected

200

other transient error

507

error during transfer of funds

back to the customer

201

other transient database error

202

POS of this ID is blocked

508

customer resigned from

making a transaction

203

invalid pay_type value

for the given pos_id

599

incorrect transaction status,

atransaction cannot be accepted
multiple times please contact us

204

The chosen payment type (pay_type)

is temporarily blocked for the given
pos_id, e.g. due to maintenance
downtime of the payment gateway

999

other critical error please contact us

75

www.payu.cz

Appendix 5 A sample php script for checking transaction status

This script can also be found on our website at http://www.en.payu.cz/downloads

<?php
//PayU server and the Payment/get method addresses
$server=secure.payu.com;
$server_script=/paygw/ISO/Payment/get;
//parameters required to send the request
define(PAYU_POS_ID,123);
define(PAYU_KEY1,1234567890123456);
define(PAYU_KEY2,9123456789012345);
//returns a field with following indexes: code(transaction status code or false in case of failure),
message (transaction status description or error description)
functionget_status($parts)
{
//invalid POS ID in response
if($parts[1]!=PAYU_POS_ID)
returnarray(code=>false,message=>incorrectPOSnumber);

//calculation of signature to verify sig sent by PayU

$sig=md5($parts[1].$parts[2].$parts[3].$parts[5].$parts[4].$parts[6].$parts[7].PAYU_KEY2);

//wrong response signature compared to the locally computed signature

if($parts[8]!=$sig)
returnarray(code=>false,message=>incorrectsignature);

//various messages according to transaction status. Descriptions of individual states are listed in
the technical documentation
switch($parts[5])
{
case1:returnarray(code=>$parts[5],message=>new);
case2:returnarray(code=>$parts[5],message=>cancelled);
case3:returnarray(code=>$parts[5],message=>rejected);
case4:returnarray(code=>$parts[5],message=>started);
case5:returnarray(code=>$parts[5],message=>awaitingreceipt);
case6:returnarray(code=>$parts[5],message=>noauthorization);
case7:returnarray(code=>$parts[5],message=>paymentrejected);
case99:returnarray(code=>$parts[5],message=>paymentreceived-ended);
case888:returnarray(code=>$parts[5],message=>incorrectstatus);
default:returnarray(code=>false,message=>nostatus);
}
}
//some parameters are missing
if(!isset($_POST[pos_id])||!isset($_POST[session_id])||!isset($_POST[ts])||!isset($_POST[sig]))
die(ERROR:EMPTYPARAMETERS);

76

www.payu.cz

//the received POS ID is different than expected

if($_POST[pos_id]!=PAYU_POS_ID)
die(ERROR:INCORRECTPOSID);

//verification of the received signature

$sig=md5($_POST[pos_id].$_POST[session_id].$_POST[ts].PAYU_KEY2);
//incorrect signature
if($_POST[sig]!=$sig)
die(ERROR:INCORRECTSIGNATURE);
//the signature which will be sent to PayU together with the request
$ts=time();
$sig=md5(PAYU_POS_ID.$_POST[session_id].$ts.PAYU_KEY1);
//preparing string parameters to be sent to PayU
$parameters=pos_id=.PAYU_POS_ID.&session_id=.$_POST[session_id].&ts=.$ts.&sig=.$sig;
//identify connection methods (socket or CURL)
$fsocket=false;
$curl=false;
if((PHP_VERSION>=4.3)&&($fp=@fsockopen(ssl://.$server,443,$errno,$errstr,30)))
$fsocket=true;
elseif(function_exists(curl_exec))
$curl=true;
//sending the request using a socket
if($fsocket==true)
{
$header=POST.$server_script.HTTP/1.0.\r\n.Host:.$server.\r\n.
Content-Type:application/x-www-form-urlencoded.\r\n.Content-Length:.
strlen($parameters).\r\n.Connection:close.\r\n\r\n;
@fputs($fp,$header.$parameters);
$payu_response=;
while(!@feof($fp))
{
$res=@fgets($fp,1024);
$payu_response.=$res;
}
@fclose($fp);
}
//sending the request using CURL
elseif($curl==true)
{
$ch=curl_init();
curl_setopt($ch,CURLOPT_URL,https://.$server.$server_script);
curl_setopt($ch,CURLOPT_SSL_VERIFYPEER,FALSE);
curl_setopt($ch,CURLOPT_HEADER,0);
curl_setopt($ch,CURLOPT_TIMEOUT,20);
curl_setopt($ch,CURLOPT_POST,1);
curl_setopt($ch,CURLOPT_POSTFIELDS,$parameters);
curl_setopt($ch,CURLOPT_RETURNTRANSFER,1);
$payu_response=curl_exec($ch);
curl_close($ch);
}

77

www.payu.cz

//no usable connection method is available

else
die(ERROR:Noconnectmethod...\n);

//obtaining response from PayU

$result=false;
if(preg_match(/<trans>.*<pos_id>([0-9]*)<\/pos_id>.*<session_id>(.*)<\/session_id>.*<order_
id>(.*).
<\/order_id>.*<amount>([0-9]*)<\/amount>.*<status>([0-9]*)<\/status>.*<desc>(.*)<\/
desc>.*<ts>.
([0-9]*)<\/ts>.*<sig>([a-z0-9]*)<\/sig>.*<\/trans>/is,$payu_response,$parts))
$result=get_status($parts);

//recognized transaction status

if($result[code])
{
$pos_id=$parts[1];
$session_id=$parts[2];
$order_id=$parts[3];
$amount=$parts[4];// in hal (heller)
$status=$parts[5];
$desc=$parts[6];
$ts=$parts[7];
$sig=$parts[8];

//TODO:
//change transaction status in the Shops system

/*examples
if($result[code]==99)
{
if(money_are_on_the_account)
{
//payment is successful, sending back OK
echoOK;
exit;
}
}
elseif($result[code]==2)
{
//transaction canceled, we can cancel the transaction as well
}
else
{
//other actions
}
*/
//if all operations are completed, send back OK, otherwise generate error
//if(everything_ok)
// {
echoOK;
exit;
//}else{
//
//}
}

78

www.payu.cz

else
{
//TODO:
//managing payments with the error status
echoERROR:Dataerror....\n;
echocode=.$result[code].message=.$result[message].\n;
echo$payu_response;
//information about the change of status to secure.payu.com will be re-sent, we can write
information to the log (logs)....
}

?>

79

www.payu.cz

Appendix 6 PayU templates

template no. 3 (CZ version)

template no. 5 (EN version)

80

www.payu.cz

Appendix 7 PayU implementation examples

Implementation using a template

81

www.payu.cz

Custom implementation

82

www.payu.cz

Appendix 8 Changes according to the manual version

VERZE 2.1
Kapitola 3, str. 17 nahrazen chybnho nzvu house number za parameter
Kapitola 3, str. 19 odstrann sel 4, 6 v tabulce
Kapitola 3, str. 19 pesunut textu ze str. 20, odstrann odstavce, odstrann scriptu
Kapitola 3, str. 20 pesunut textu na str. 19, odstrann vty anglick verze
Kapitola 3, str. 20 pidn textu <input type=hidden name=ts value=251013105655> a <input
type=hidden name=sig value=9075ed67df1c3a4e5686ee7bbb78ad64>
Kapitola 7, str. 71 pidn novch poloek era, cb, psc
Kapitola 7, str. 71 zmna hodnoty sloupce u metody t z 1,00 1000,00 na 0,50 1000,00
Kapitola 7, str. 72 (status 3) pidn textu Transaction should be
Kapitola 7, str. 71 zmna textu mPenize na mTransfer
Cel dokument zruen ligatury na fi
Kapitola 3, str. 17 zmna parametru no na yes (dek language)
VERZE 2.2
Kapitola 3, str. 15 odstrann odstavce Alternatively, in case of
Kapitola 3, str. 17 zmna http:www.chemie.fu-berlin.de/ na https://www.iso.org/obp/
Kapitola 3, str. 17 zmna http:www.ics.uci.edu/ na http://www-01.sil.org/
Kapitola 3, str. 20 vloen dku <input type=hidden name=language value=cs>
Kapitola 3, str. 21 vloen dk sig_ext a sig_ext_order
Oblka, str. 84 zmna tel. . na 226 221 951

83

Adress: PayU Czech Republic, s. r. o. / Karolinsk 650/ 1 / Praha 8, 18600

Telephone: 226 221 951 / e-mail: obchod@payu.cz / web: www.payu.cz / PayU