84
PayU Implementation Manual for e-shops using a template www.payu.cz 2.2

Payu Implementation Manual Template En

  • Upload
    puneet

  • View
    267

  • Download
    3

Embed Size (px)

DESCRIPTION

This document is for implementation of payu payment gateway

Citation preview

Page 1: Payu Implementation Manual Template En

PayU ImplementationManual for e-shopsusing a template

www.payu.cz

2.2

Page 2: Payu Implementation Manual Template En

www.payu.cz

Table of Contents

1. Introduction

2. From registration to PayU launch 2.1 General information 2.2 Description of individual steps

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

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

5. The mandatory parameters of implementation

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

4

567

13141415151515161621212225252527282930

313232333334343535

37

3940404147545659656767

Page 3: Payu Implementation Manual Template En

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

707172737576808183

Page 4: Payu Implementation Manual Template En

www.payu.cz

IntroductionPayU 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

1

Page 5: Payu Implementation Manual Template En

From registration to PayU launch

2

Page 6: Payu Implementation Manual Template En

www.payu.cz

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 gatewayin an e-shop:

6

2.1

registration at www.payu.cz

contract

technical implementation

according to technical

documentation

testing payment

activation of payment

methods according

to the contract

productionlaunch

IMPLEMENTATION OF THE PAYU PAYMENT GATEWAY

2

Page 7: Payu Implementation Manual Template En

1.

2.

3.

4.

5.

www.payu.cz

Description of individual steps

7

2.2

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

Tentative registration at https://www.payu.cz/manager/register?execution=e1s1This 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.

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.

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.

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

Customer(e-shop)

1. Information about PayUat www.payu.cz

2. registration, creatinga PayU account (login

and password)

5. logging in to the PayUaccount, adding a Shop anda POS and implementation

6. signing a contractand sending the AMLidentification to PayU

8. testing payment

9. request salesdepartment to activate

payment methods

PayUsales department

3. sending the contractand contractual terms

PayUcustomer service

4. activation of the account and a test payment

7. setting the contractualpayment methods

for the POS and activation

10. verification of thetesting payment,

activation and checks

2

Page 8: Payu Implementation Manual Template En

www.payu.cz

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

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

5.1

2

Page 9: Payu Implementation Manual Template En

www.payu.cz

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

5.2

2

Page 10: Payu Implementation Manual Template En

www.payu.cz

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

5.3

2

Page 11: Payu Implementation Manual Template En

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.

Check the contract received from PayU, sign it and send it to the following address:

PayU Czech Republic, s. r. o.Karolinská 650/1186 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.

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

11

6.

7.

2

Page 12: Payu Implementation Manual Template En

www.payu.cz

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 completionof the implementation to PayU customer service using the contact form in your PayU account:

To activate the payment methods specified in the contract, contact your PayU sales representative or send a request to [email protected].

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

8.

9.

10.

2

Page 13: Payu Implementation Manual Template En

PayUimplementation

3

Page 14: Payu Implementation Manual Template En

www.payu.cz

14

General information

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

Terms used in the application

PayUThe payment processing application.

CompanyThe company that uses the PayU application to receive payments from Customers.

ShopAn e-shop receiving payments; one company may run several Shops.

POSThe Point of Sale processing the received payments; for a given POS, all service parameters are defined; one Shop can run multiple POS.

CustomerA person performing a payment.

UrlPayUURL address where the PayU application is installed: https://secure.payu.com/paygw

UrlPositiveURL address of the Shop application where the Customer is redirected after a successful start of transaction.

UrNegativeURL address of the Shop application where the Customer is redirected after a failed start of transaction.

UrlOnlineURL address of the Shop application where notifications of changes in payment status will be sent using the POST method.

3.1

3.2

3

Page 15: Payu Implementation Manual Template En

www.payu.cz

15

Integration with PayU

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“

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

Encoding

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

3.3

3.3.1

3.3.2

3.3.3

3

name in PayU encoding used

ISO ISO-8859-2

UTF UTF-8

WIN Windows-1250

Page 16: Payu Implementation Manual Template En

www.payu.cz

16

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

Creating a new payment

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

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.

3.3.4

3.3.5

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

4. The customeris redirected to the

bank to pay

E-shop

PayU

7. PayU informs the e-shop of the transaction status change

5. Aft er payment, the customeris redirected back to the e-shop

Bank

6. The Bank informs PayU of

the payment

3

Page 17: Payu Implementation Manual Template En

www.payu.cz

17

Parameters of the new payments are as follows: 3parameter

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 customeron 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-3166https://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-639http://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

Page 18: Payu Implementation Manual Template En

www.payu.cz

18

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.

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 oft en realizes the error only aft er he’s redirected to the website of the bank or the card transactions provider. At this point, the Customer oft en 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:

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

Creating a simple form with the corresponding parameters

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

3

1.

2.

3.

Page 19: Payu Implementation Manual Template En

www.payu.cz

19

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.

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:ywhether the sig parameter value calculation should or should not includethe pay_type parameter: 1 = yes, 0 = no

3where the parameters have the following meaning:

Page 20: Payu Implementation Manual Template En

www.payu.cz

20

3In 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=“[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>

Page 21: Payu Implementation Manual Template En

www.payu.cz

21

Exchange of information on transactions

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

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:

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.

3.4

3.4.1

3

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

Page 22: Payu Implementation Manual Template En

www.payu.cz

22

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:

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:

The sig value is calculated using the following formula:

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

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

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)

3

Page 23: Payu Implementation Manual Template En

www.payu.cz

23

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

„txt“ format:

status: OKtrans_id: 7trans_pos_id: 1trans_session_id: 417419trans_order_id: trans_amount: 200trans_status: 5trans_pay_type: ttrans_pay_gw_name: pttrans_desc: Platba pro shop.cztrans_desc2: trans_create: 2012-12-21 10:39:52trans_init: 2012-12-21 10:41:03trans_sent: 2012-12-21 10:41:44trans_recv: trans_cancel: trans_auth_fraud: 0trans_ts: 1094205761232trans_sig: b6d68525f724a6d69fb 1260874924759

„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>

3

Page 24: Payu Implementation Manual Template En

www.payu.cz

24

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_idvalue assigned by the Shop application when the transaction is created

trans_order_id response/transorder_idvalue 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_nameresponse/trans/pay_gw_name

name of the gateway performing the transaction – internal information of the PayU application

trans_desc response/trans/descvalue assigned by the Shop application when the transaction is created

trans_desc2 response/trans/desc2value 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

3

Page 25: Payu Implementation Manual Template En

www.payu.cz

25

Other fields – for selected methods of payment:

– Test payment

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.

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.

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: OKtrans_id: 7trans_pos_id: 1trans_session_id: 417419trans_ts: 1094206530505trans_sig: 9da7c868407fedae6f1b6aca9054632b

3.4.3

3.4.4

3.4.5

3

Page 26: Payu Implementation Manual Template En

www.payu.cz

26

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: ERRORerror_nr: 503error_message:

Error - „xml“ format:

<?xml version=“1.0“ encoding=“UTF-8“?><response> <status>ERROR</status> <error> <nr>503</nr> <message></message> </error></response>

3

Page 27: Payu Implementation Manual Template En

www.payu.cz

27

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:

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%

3.5

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

3

Page 28: Payu Implementation Manual Template En

www.payu.cz

28

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

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:

3.6

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

Page 29: Payu Implementation Manual Template En

www.payu.cz

29

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

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.

3.6.1

3

Page 30: Payu Implementation Manual Template En

www.payu.cz

30

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.

3.7 3

Page 31: Payu Implementation Manual Template En

Appearance of the PayU payment gatewayin the e-shop

4

Page 32: Payu Implementation Manual Template En

Implementation

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.

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

32

4

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

4.2

Page 33: Payu Implementation Manual Template En

www.payu.cz

4.4

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.

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 customeris to leave it prematurely.

Simplifying the shopping process requires optimization of three basic key elements: navigation, visualization and speed.

33

4 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 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 methodin the same way as they are displayed in the PayU template (see Appendix 6).

Page 34: Payu Implementation Manual Template En

www.payu.cz

4.6

34

4Navigace 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 Customer’s perspective, an e-shop always has greater credibility if it cooperates with well-known 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.

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.

4.5

Page 35: Payu Implementation Manual Template En

www.payu.cz

35

4A 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.7

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/

Page 36: Payu Implementation Manual Template En

www.payu.cz

36

4Inserting 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 .

Page 37: Payu Implementation Manual Template En

The mandatory parameters of implementation

5

Page 38: Payu Implementation Manual Template En

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 pageof 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 stepwhere shoppers choose „PayU“ in the list of payment methods – PayU is a payment gateway off ering payment methods – not a payment method.

38

5

Page 39: Payu Implementation Manual Template En

PayU account administration

6

Page 40: Payu Implementation Manual Template En

www.payu.cz

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.

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

Aft er 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.

6.1

6.2

40

6

Page 41: Payu Implementation Manual Template En

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.

www.payu.cz

6.3

41

6

Page 42: Payu Implementation Manual Template En

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.

www.payu.cz

42

6

Page 43: Payu Implementation Manual Template En

www.payu.cz

43

6In 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.

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

Page 44: Payu Implementation Manual Template En

www.payu.cz

Aft er 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

6

Page 45: Payu Implementation Manual Template En

www.payu.cz

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

45

6

Page 46: Payu Implementation Manual Template En

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

6

Page 47: Payu Implementation Manual Template En

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.

Transactions

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

6.4

47

6

Page 48: Payu Implementation Manual Template En

www.payu.cz

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

48

6

Page 49: Payu Implementation Manual Template En

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

6

Page 50: Payu Implementation Manual Template En

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

6

Page 51: Payu Implementation Manual Template En

www.payu.cz

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

On the „List of transactions“ page, payment refunds can also be performed. Only payments with status „ended“ can be refunded. Aft er clicking the „Refund“ link

6

Page 52: Payu Implementation Manual Template En

www.payu.cz

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

6

Page 53: Payu Implementation Manual Template En

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 – aft er 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

6

Page 54: Payu Implementation Manual Template En

www.payu.cz

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

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 diff er by also including information regarding billed commissions in addition to information about transactions. Also listed here is the current Shop balance aft er each operation (i.e. aft er receiving the transaction, billing the commission etc).

54

6.5

6

Page 55: Payu Implementation Manual Template En

www.payu.cz

55

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.

6

Page 56: Payu Implementation Manual Template En

www.payu.cz

56

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

6.6

6

Page 57: Payu Implementation Manual Template En

www.payu.cz

57

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.

6

Page 58: Payu Implementation Manual Template En

www.payu.cz

58

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,

the second one on a specified day of month.

6

Page 59: Payu Implementation Manual Template En

www.payu.cz

59

PDF/CSV/ABO Statements

Using the user interface, it is possible to download a statement of transactions in 3 diff erent 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 soft ware (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).

6.7 6

Page 60: Payu Implementation Manual Template En

www.payu.cz

60

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

You also need to select the desired „File format“. Depending on the selected format, it is possible to specify further settings. The most fl 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.

6

Page 61: Payu Implementation Manual Template En

www.payu.cz

61

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

6

Page 62: Payu Implementation Manual Template En

www.payu.cz

62

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 PDF format allows you to choose between two statement templates.

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

6

Page 63: Payu Implementation Manual Template En

www.payu.cz

63

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.

6

Page 64: Payu Implementation Manual Template En

www.payu.cz

64

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. Aft er 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.

6

Page 65: Payu Implementation Manual Template En

www.payu.cz

65

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.

6.8 6

Page 66: Payu Implementation Manual Template En

www.payu.cz

66

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. Aft er 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.

6

Page 67: Payu Implementation Manual Template En

www.payu.cz

67

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.

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.

6.9

6.10

6

Page 68: Payu Implementation Manual Template En

www.payu.cz

68

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.

6

Page 69: Payu Implementation Manual Template En

www.payu.cz

69

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

6

Page 70: Payu Implementation Manual Template En

Appendices 7

Page 71: Payu Implementation Manual Template En

www.payu.cz

71

Appendix 1 – Types of payments 7name 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 - Raiff eisenbank

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

Page 72: Payu Implementation Manual Template En

www.payu.cz

72

Appendix 2 – Transaction status 7status description

1 new

2 cancelled

3 rejected

4 started

5 awaiting receipt

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

Page 73: Payu Implementation Manual Template En

www.payu.cz

73

Appendix 3 – Transitions among transaction states

If automatic payment receipt is disabled:

New(status 1)

Cancelled (status 2)

If it’s possible to cancel the transaction

Rejected(status 3)

Reject done(status 7)

Ended(status 99)

Started(status 4)

Awaiting receipt

(status 5)

7

Page 74: Payu Implementation Manual Template En

www.payu.cz

74

If automatic payment receipt is enabled:

New(status 1)

Cancelled (status 2)

Rejected (status 3)

Reject done(status 7)

Ended (status 99)

Started (status 4)

7

Page 75: Payu Implementation Manual Template En

www.payu.cz

75

Appendix 4 – Error codes 7code description

100 pos_id parameter missing

101 session_id parameter missing

102 ts parameter missing

103sig parameter missingor invalid sig value

104 desc parameter missing

105 client_ip parameter missing

106 first_name parameter missing

107 last_name parameter missing

108 street parameter missing

109 city parameter missing

110 post_code parameter missing

111 amount parameter missing

112 wrong bank account number

113 email parameter missing

114 phone parameter missing

200 other transient error

201 other transient database error

202 POS of this ID is blocked

203invalid pay_type valuefor the given pos_id

204

The chosen payment type (pay_type)is temporarily blocked for the given pos_id, e.g. due to maintenancedowntime of the payment gateway

205the transaction amount is smallerthan the minimum value

206the transaction amount is greaterthan the maximum value

207exceeded the value of all transactions for a single customer for the last period

209 invalid pos_id or pos_auth_key

210transaction amount containsunallowed halíř (heller) entries

212transaction request more frequent than one per minute(for not activated company)

500 transaction doesn’t exist

501 transaction authorization missing

502 transaction has already started earlier

503transaction authorizationhas already been done

504 transactions were previously revoked

505 transactions were previously accepted

506 transaction was selected

507error during transfer of fundsback to the customer

508customer resigned frommaking a transaction

599incorrect transaction status, a transaction cannot be accepted multiple times – please contact us

999 other critical error – please contact us

Page 76: Payu Implementation Manual Template En

www.payu.cz

Appendix 5 – A sample php script for checking transaction status

76

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 requestdefine(“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 missingif(!isset($_POST[“pos_id”]) || !isset($_POST[“session_id”]) || !isset($_POST[“ts”]) || !isset($_POST[“sig”]))     die(“ERROR: EMPTY PARAMETERS”);       

7

Page 77: Payu Implementation Manual Template En

www.payu.cz

77

// the received POS ID is different than expectedif($_POST[“pos_id”] != PAYU_POS_ID)      die(“ERROR: INCORRECT POS ID”);    

// verification of the received signature$sig = md5($_POST[“pos_id”].$_POST[“session_id”].$_POST[“ts”].PAYU_KEY2);   

// incorrect signatureif($_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 socketif ($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 CURLelseif ($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); } 

7

Page 78: Payu Implementation Manual Template En

www.payu.cz

78

// no usable connection method is availableelse     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 statusif ($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

    /*  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 {     //     // } } 

7

Page 79: Payu Implementation Manual Template En

www.payu.cz

79

 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

Page 80: Payu Implementation Manual Template En

www.payu.cz

80

Appendix 6 – PayU templates

template no. 3 (CZ version) template no. 5 (EN version)

7

Page 81: Payu Implementation Manual Template En

www.payu.cz

Appendix 7 – PayU implementation examples

Implementation using a template

81

7

Page 82: Payu Implementation Manual Template En

www.payu.cz

82

7Custom implementation

Page 83: Payu Implementation Manual Template En

83

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“

7

www.payu.cz

Appendix 8 – Changes according to the manual version

Page 84: Payu Implementation Manual Template En

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