PayU Implementation Manual for e

2.2
PayU Implementation
Manual for e-shops
using a template
www.payu.cz
www.payu.cz
Table of Contents
1. Introduction
4
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
1
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.
4
From registration
to PayU launch
2
www.payu.cz
2
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
of payment
methods
according
to the contract
testing payment
6
www.payu.cz
2
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
it’s not possible to successfully complete the implementation.
5.
You can now log in to your PayU account and begin with the implementation.
7
www.payu.cz
Basic setup of a PayU account to for beginning the implementation:
5.1
2
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 account’s 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.
8
www.payu.cz
2
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)
9
www.payu.cz
2
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.
2
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 – Karlín
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
or send a request to [email protected].
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.
2
12
PayU
implementation
3
www.payu.cz
3.1 General information
3
This practical guide to implementing PayU payment gateway contains information needed
for technical 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
of transaction.
UrNegative
URL address of the Shop application where the Customer is redirected after a failed start
of transaction.
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
3
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 následujících 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
3
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}
customer‘s 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}
client’s 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 client’s 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
3
17
www.payu.cz
It is not mandatory to include the payer address parameters in the New payment form, however,
if possible, 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.
3
After creating a payment the customer will be redirected to the UrlPositive or UrlNegative address
using the GET method. Since it’s 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 doesn’t 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 he’s 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 Merchant’s 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
3
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:
3
<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=“[email protected]“>
<input type=“hidden“ name=“first_name“ value=“Petr“>
<input type=“hidden“ name=“last_name“ value=“Novák“>
<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
3
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 hasn’t 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
3
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:
3
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)
3
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
3
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>
3
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
3
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.
3
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:
3
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
3
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
4
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
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. They’re 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.
4
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 you’re 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, he’s 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
4
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 Customer’s 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
4
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 Customer’s 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
5
www.payu.cz
Before launching the PayU payment system into production, the e-shop must meet the following
requirements:
5
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
6
www.payu.cz
6.1 General information
6
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
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
6
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 a new payment.
6
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 Shop’s website (pos_id, key and
second key (MD5) and the pos_auth_key authorization key).
43
www.payu.cz
6
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
6
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
6
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
6
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
6
Details of each transaction can be viewed by clicking on the transaction description.
48
www.payu.cz
The transaction details page looks like this
6
After clicking on „Show reports“ it is possible to manually send the transaction status change
notification to Shop’s 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
6
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
6
Based on the chosen refund method it is then required to fill in the fields in the „Refund receiver´s
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, there’s 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.
6
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
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
6
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.6 Payouts
You can ask to transfer the Shop’s 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
6
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 Shop’s 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 a selected
day in a month“. The first one allows you to make payouts on the specified day of the week,
6
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.
6
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 flexible 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.
6
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:
6
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.
6
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.
6
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.
6
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
6
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.
6
The table shows the same data as the chart.
66
www.payu.cz
6.9 Notification settings
6
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
6
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.
6
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“ user’s
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
7
www.payu.cz
7
Appendix 1 – Types of payments
name
transaction limit (CZK)
automatic
cancellation
time (days)
description
cs
3,00 – 999999,99
10
PLATBA 24 – Česká spořitelna
mp
3,00 – 999999,99
10
mTransfer – mBank
kb
3,00 – 999999,99
10
MojePlatba – Komerční banka
rf
3,00 – 999999,99
10
ePlatby pro eKonto - Raiffeisenbank
pg
3,00 – 999999,99
10
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 - Poštovní spořitelna
cb
3,00 – 999999,99
10
ČSOB
psc
3,00 – 999999,99
10
PaySec
c
3,00 – 999999,99
10
Platební karty přes 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)
t
0,50 – 1000,00
1
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 Shop’s site should be the same as in this document.
71
www.payu.cz
Appendix 2 – Transaction status
status
description
1
new
2
cancelled
3
rejected
4
started
5
awaiting receipt
7
reject done
99
ended
888
wrong status – please contact us
7
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“
is canceled 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 a transaction 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
to 99 – „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
7
Appendix 3 – Transitions among transaction states
If automatic payment receipt is disabled:
Awaiting
receipt
(status 5)
New
(status 1)
Started
(status 4)
If it’s possible to cancel
the transaction
Cancelled
(status 2)
Rejected
(status 3)
Reject done
(status 7)
Ended
(status 99)
73
www.payu.cz
7
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
7
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 doesn’t 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,
a transaction 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
7
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)
function get_status($parts) {
// invalid POS ID in response
if($parts[1] != PAYU_POS_ID) return array(“code” => false, “message” => “incorrect POS number”); // 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) return array(“code” => false, “message” => “incorrect signature”);
// various messages according to transaction status. Descriptions of individual states are listed in
the technical documentation
switch($parts[5]) { case 1: return array(“code” => $parts[5], “message” => “new”); case 2: return array(“code” => $parts[5], “message” => “cancelled”); case 3: return array(“code” => $parts[5], “message” => “rejected”); case 4: return array(“code” => $parts[5], “message” => “started”); case 5: return array(“code” => $parts[5], “message” => “awaiting receipt”); case 6: return array(“code” => $parts[5], “message” => “no authorization”); case 7: return array(“code” => $parts[5], “message” => “payment rejected”); case 99: return array(“code” => $parts[5], “message” => “payment received - ended”); case 888: return array(“code” => $parts[5], “message” => “incorrect status”); default: return array(“code” => false, “message” => “no status”); } } // some parameters are missing
if(!isset($_POST[“pos_id”]) || !isset($_POST[“session_id”]) || !isset($_POST[“ts”]) || !isset($_POST[“sig”])) die(“ERROR: EMPTY PARAMETERS”); 76
www.payu.cz
// the received POS ID is different than expected
if($_POST[“pos_id”] != PAYU_POS_ID) die(“ERROR: INCORRECT POS ID”); 7
// 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: INCORRECT SIGNATURE”); // 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: No connect method ...\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 Shop‘s system
7
/* examples”
if ($result[“code”] == “99”) { if(money_are_on_the_account) { // payment is successful, sending back OK
echo “OK”; exit; } } else if ($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) // { echo “OK”; exit; // } else { // // } } 78
www.payu.cz
else { // TODO: // managing payments with the error status
echo “ERROR: Data error ....\n”; echo “code=”.$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)....
} 7
?>
79
www.payu.cz
7
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
7
81
www.payu.cz
Custom implementation
7
82
www.payu.cz
Appendix 8 – Changes according to the manual version
7
VERZE 2.1
Kapitola 3, str. 17 – nahrazení chybného názvu „house number“ za „parameter“
Kapitola 3, str. 19 – odstranění čísel 4, 6 v tabulce
Kapitola 3, str. 19 – přesunutí textu ze str. 20, odstranění odstavce, odstranění scriptu
Kapitola 3, str. 20 – přesunutí textu na str. 19, odstranění věty „anglická verze“
Kapitola 3, str. 20 – přidání textu <input type=“hidden“ name=“ts“ value=“251013105655“> a <input
type=“hidden“ name=“sig“ value=“9075ed67df1c3a4e5686ee7bbb78ad64“>
Kapitola 7, str. 71 – přidání nových položek „era, cb, psc“
Kapitola 7, str. 71 – změna hodnoty sloupce u metody „t“ z „1,00 – 1000,00“ na „0,50 – 1000,00“
Kapitola 7, str. 72 – (status 3) přidání textu „Transaction should be…“
Kapitola 7, str. 71 – změna textu „mPenize“ na „mTransfer“
Celý dokument – zrušení ligatury „fi“ na „fi“
Kapitola 3, str. 17 – změna parametru „no“ na „yes“ (řádek language)
VERZE 2.2
Kapitola 3, str. 15 – odstranění odstavce „Alternatively, in case of…“
Kapitola 3, str. 17 – změna „http:www.chemie.fu-berlin.de/…“ na „https://www.iso.org/obp/…“
Kapitola 3, str. 17 – změna „http:www.ics.uci.edu/…“ na „http://www-01.sil.org/…“
Kapitola 3, str. 20 – vložení řádku „<input type=“hidden“ name=“language“ value=“cs“>“
Kapitola 3, str. 21 – vložení řádků „sig_ext“ a „sig_ext_order“
Obálka, str. 84 – změna 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: [email protected] / web: www.payu.cz / © PayU