Classic API (NewPayment)

To create a new payment, you need to place an appropriate form on your website which will redirect the customer to PayU, to NewPayment procedure (read more in "PayU URLs"). It is advised to use the POST method; if it is impossible, you may apply the GET method. The list of parameters and their description is available at "new payment parameters".

After the payment is finished, the customer will be redirected to UrlPositive or UrlNegative address using the GET method. It may happen that the customer does not go back to the Shop application, and that is why the information transferred using these addresses is not binding, decisions regarding payments cannot be made on its basis.

The method of transferring information about transactions has been described in "exchange of information".

Example form with a minimal number of parameters:

<form action="https://secure.payu.com/paygw/UTF/NewPayment" method="POST" name="payform">
    Name: <input type="text" name="first_name" value=""><br/>
    Surname: <input type="text" name="last_name" value=""><br/>
    E-mail: <input type="text" name="email" value=""><br/>
    <input type="hidden" name="pos_id" value="178893">
    <input type="hidden" name="pos_auth_key" value="gQJQrgD">
    <input type="hidden" name="session_id" value="Zz0cyTCtkbiR7LOpNzrkddZXkgbFbo6A.">
    <input type="hidden" name="amount" value="1000">
    <input type="hidden" name="desc" value="Payment desc">
    <input type="hidden" name="client_ip" value="123.123.123.123">
    <input type="hidden" name="js" value="0">
    <input type="hidden" name="ts" value="124321879">
    <input type="hidden" name="sig" value="80764dcb147ed9c71b5e2dcde26e7b3bd3879c236ccca96e9e21f2ea9c4e91b6">
    <input type="submit" value="Pay via PayU">
</form>
<script language="JavaScript" type="text/javascript">
    <!--
    document.forms['payform'].js.value=1;
    -->
</script>

Depending on a payment method, it may be necessary to enter values defined in the table as not required. Additional information can be found next to descriptions of particular payment methods "payment types".

¹ If the pay_type parameter is missing, a window with a selection of all payment types available for a given pos_id will be displayed (list of payment types is available in "payment types")

² Read more in "signing parameters"

Additional information about transaction statuses

If Automatic receipt of payments is disabled:

If Automatic receipt of payments is enabled:

After a finished payment process, the customer may be redirected to a URL specified by the Shop. The use of a UrlPositive or UrlNegative depends on a transaction status. The return to Shop addresses are of information character only; no decisions can be taken on their basis.

They may contain the following constants to be exchanged for appropriate values, according to the table below:

Examples:

http://www.sklep.pl/status_ok.html?pos_id=%posId%&session_id=%sessionId%

http://www.sklep.pl/status_error.html?pos_id=%posId%&session_id=%sessionId%&error=%error%

A PayU application URL is created according to the following scheme:

URL = UrlofPlatnosci.pl/Encoding/ProcedureName

where:

Depending on encoding used by a Shop application, an appropriate charset should be selected for communication with PayU:

Selected encoding should match encoding set in a given POS (point of sale).

For the Payment/get, Payment/confirm and Payment/cancel procedures it is also possible to specify a format used for sending data; the formula is the following:

URL = UrlPlatnosci.pl/Encoding/ProcedureName/Format

where the Format may be either “xml” or “txt”; “xml” is selected by default.

Shop application must add a checksum of all parameters transferred to the new payment form (NewPayment).

In order to use this option, add additional parameter to the form:

Algorithm for signing parameters in the form

1. Sort all the fields available in the form in the alphabetic, ascending order according to the names of parameters name attribute of the input element. If a given value is not transferred in the form creating a new payment, use an empty string of characters.
2. Concatenate the keys and values of all the fields according to pre-set order (key=value), separated by the ampersand sign &. The parameters values must be URL encoded (application/x-www-form-urlencoded - a space character is encoded with '+') using appropriate page encoding. Note: capital letters must be used for encoding (e.g. Polish special character "ł" should be "%C5%82", not "%c5%82").
3. Assign your private key to this sequence of characters (available in the Panel Manager as Second key (MD5)).
4. Use SHA-256 hash function.

In case the sig value has been calculated incorrectly or the values of other transferred parameters have been changed, the new payment will not be created. The Customer will be redirected to UrlNegative with error code 103.

Pseudo-code of an algorithm for signing parameters in the form

generate_signature(form, secondKey, posId) {
    sortedValues = sortValuesByItsName(form)

    foreach value in sortedValues {
        content = content + parameterName + "=" + urlencode(value) + "&"
    }

    content = content + secondKey
        
    return sha256(content)
}

Signing of example form

<form action="https://secure.payu.com/paygw/UTF/NewPayment" method="POST" name="payform">
    Name: <input type="text" name="first_name" value="First Name"><br/>
    Surname: <input type="text" name="last_name" value="Last Name"><br/>
    E-mail: <input type="text" name="email" value="email@email.com"><br/>
    <input type="hidden" name="pos_id" value="999999">
    <input type="hidden" name="pos_auth_key" value="abcDEF">
    <input type="hidden" name="session_id" value="Zz0cyTCtkbiR7LOpNzrkddZXkgbFbo6A.">
    <input type="hidden" name="amount" value="1000">
    <input type="hidden" name="desc" value="Payment desc">
    <input type="hidden" name="client_ip" value="123.123.123.123">
    <input type="hidden" name="js" value="1">
    <input type="hidden" name="ts" value="124321879">
    <input type="submit" value="Pay via PayU">
</form>

amount=1000&client_ip=123.123.123.123&desc=Payment+desc&email=email%40email.com&first_name=First+Name&js=1&last_name=Last+Name&pos_auth_key=abcDEF&pos_id=999999&session_id=Zz0cyTCtkbiR7LOpNzrkddZXkgbFbo6A.&ts=124321879&098f6bcd4621d373cade4e832627b4f6

703ca5f6ac791dc244290a30d054039b32ed445c98655568c00ff532e719c6cb                

<input type="hidden" name="sig" value="703ca5f6ac791dc244290a30d054039b32ed445c98655568c00ff532e719c6cb">

In case of questions please contact us.

The Shop application is obliged to verify signatures of transmitted information.

Every command (except for creating new payment) and response generated by PayU is provided with an MD5 signature that makes it possible to verify data integrity.

The signatures are created in accordance with the following formula (where “+” means operation of joining the strings of characters):

sig = md5( pos_id + session_id + value1 + value2 + ... + valuen + ts + key )

where:

In PayU application, there are two key values assigned to a given pos_id,

key1 – key used while checking the signature sent by the Shop (visible as Key(MD5) in the Management Panel)

key2 – key used to generate a signature that is sent to the Shop (visible as Secondary Key(MD5) in the Management Panel)

Each change of transaction status is reported to the Shop application. A POST request is sent to the given UrlOnline address with the following parameters:

Where the sig value is calculated in accordance with the following formula:

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

A message about a change of transaction status does not contain any detailed information. The Shop application MUST individually read transaction data and its current status using mechanisms described in "exchange of information" (section "reading transaction status").

After receiving the request, the Shop application MUST send the “OK” string of characters in response. If another answer is received, it will be saved in the database and the notification will be considered as not received.

The Shop application should take account of situations where a notification is sent several times for the same transaction and the same status. For each repeated notification, the “OK” response should be sent as well.

For one POS, one POST request is sent at a time, but it should be possible to send a few requests for same POS at a time.

Notifications are sent immediately after a payment status changes. If the notification is not received by the Shop application, it will be sent again in accordance with the table below:

In order to read the current state of the SMS transaction, you need to call the Payment/get procedure ("PayU URLs!!!") using the POST method, specifying the following parameters:

Where the sig value is calculated in accordance with the following formula:

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

In the response you will receive the following pages containing information:

“txt” format:

status:OK
trans_id:7
trans_pos_id:1
trans_session_id:417419
trans_order_id:
trans_amount:200
trans_status:5
trans_pay_type:t
trans_pay_gw_name:pt
trans_desc:Wpłatadlatest@test.pl
trans_desc2:
trans_create:2004-08-2310:39:52
trans_init:2004-08-3113:42:43
trans_sent:2004-08-3113:48:13
trans_recv:
trans_cancel:
trans_auth_fraud:0
trans_ts:1094205761232
trans_sig:b6d68525f724a6d69fb1260874924759
trans_add_client_name: JAN KOWALSKI
trans_add_client_street: UL.NOWOWIEJSKIEGO 8
trans_add_client_city: WARSZAWA
trans_add_client_post_code: 02-638
trans_add_client_account: 80607787095718703296721164
trans_add_client_address: 
            

“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>Wpłatadlatest@test.pl</desc>
        <desc2></desc2>
        <create>2004-08-2310:39:52</create>
        <init>2004-08-3113:42:43</init>
        <sent>2004-08-3113:48:13</sent>
        <recv></recv>
        <cancel></cancel>
        <auth_fraud>0</auth_fraud>
        <ts>1094205828574</ts>
        <sig>a95dc2145079b16a3668175279c35736</sig>
        <add_client_name>JAN KOWALSKI</add_client_name>
        <add_client_street>UL.NOWOWIEJSKIEGO 8</add_client_street>
        <add_client_city>WARSZAWA</add_client_city>
        <add_client_post_code>02-638</add_client_post_code>
        <add_client_account>80607787095718703296721164</add_client_account>
        <add_client_address></add_client_address>
    </trans>
</response>
            

In respect of data sent back by PayU, we calculate the sig value according to the following formula:

sig = md5( pos_id + session_id + order_id + status + amount + desc + ts + key2 )

The meaning of the particular message fields has been described in the following tables:

Basic fields:

Additional fields – for chosen payment types:

- mBank, BZWBK

- payment card (incl. Masterpass)

* - used in the service Pay in installments with Mastercard

- ING

- przelew bankowy

- płatność testowa

In order to receive a payment, i.e. confirm the transaction, we call the Payment/confirm procedure using the POST method, and enter the same parameters as in the case of reading transaction information (read: "exchange of information").

Calling this method is necessary only in case of disabling the “Automatic collection” option for a given payment type.

In order to cancel or reject a payment, call the Payment/cancel procedure using POST and specify the same parameters as those for retrieving transaction data (see: "exchange of information").

For the Payment/confirm and Payment/cancel procedures the following pages are retrieved:

Correct execution – “txt” format:

status:OK
trans_id:7
trans_pos_id:1
trans_session_id:417419
trans_ts:1094206530505
trans_sig:9da7c868407fedae6f1b6aca9054632b
                

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

In data returned by PayU, the sig value is calculated according to 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>
                

The described procedures may be used via their WEBAPI/SOAP interface available at:

https://secure.payu.com/api/classic/services/payments

The appropriate WSDL link can be downloaded from:

https://secure.payu.com/api/classic/services/payments?wsdl

PayU offers a set of tools which can be used by the Seller to enhance user experience (UX) during the payment process. These tools can be divided into two categories.

The first category is a set of tools which allows for retrieving payment methods in order to display them on the Seller’s system page. A JavaScript tool “injects” available payment methods. The second option allows for retrieving the same data in xml format that can be further processed by the server of Seller’s system.

However, the second category allows for defining the cart with a link. It is a very convenient solution enabling easy integration. You can read more about it in the sections below.

A current payment list for a given POS can be placed on a site by referring to JavaScript code retrieved from PayU.

The code can be found at:

URL = UrlPlatnosci.pl/Encoding/js/PosId/K/paytype.js

where:

Paytype.js contains the following methods:

Example of use:

<script language='JavaScript' type='text/JavaScript'
src='https://secure.payu.com/paygw/ISO/js/1234/xx/paytype.js'>
</script>
<form action="https://secure.payu.com/paygw/ISO/NewPayment"
method="POST" name="payform">
    <input type="hidden" name="pos_id" value="12345">
    <input type="hidden" name="session_id" value="1234565">
    <input type="hidden" name="amount" value="1000">
    <input type="hidden" name="desc" value="Payment description">
    <script language='JavaScript'type='text/JavaScript'>
    PlnDrawSelect();
    </script>
    <input type="hidden" name="client_ip" value="123.123.123.123">
    <input type="hidden" name="js" value="0">
    <input type="submit" value="Pay via PayU">
</form>
<script language="JavaScript" type="text/javascript">
<!--
document.forms['payform'].js.value=1;
-->
</script>
                

A list of the current payment methods for a given POS may be downloaded as xml file.

The appropriate xml file can be found at:

URL = UrlPlatnosci.pl/Encoding/xml/PosId/K/paytype.xml

where:

Example content of the downloaded file:

<?xml version="1.0"encoding="UTF-8" ?>
<paytypes>
    <paytype>
        <type>c</type>
        <name>Payment card</name>
        <enable>true</enable>
        <img>https://secure.payu.com/paygw/images/paytype/on-c.gif</img>
        <min>1.01</min>
        <max>4000.0</max>
    </paytype>
    <paytype>
        <type>m</type>
        <name>mTransfer</name>
        <enable>true</enable>
        <img>https://secure.payu.com/paygw/images/paytype/on-m.gif</img>
        <min>0.5</min>
        <max>999999.99</max>
    </paytype>
...
</paytypes>
                

Automatic collection enabled

Automatic collection can be configured as other standard payment methods.

If Automatic collection has been enabled, transactions are processed automatically, without manual confirmation.

Automatic collection disabled

Automatic collection can be configured as other standard payment methods.

If Automatic collection has been disabled, transactions are processed only after they have been manually confirmed.

Manual transaction confirmation

To manually confirm a transaction in the Management Panel when Automatic collection is disabled:

1. Go to the Management Panel.
2. Go to Transactions > List of transactions.
3. In the Status field, select Waiting for collection. Optionally, set other search parameters.
4. Click on Show.
5. To confirm the transaction, in the Action column, click on Collect.
6. Check if data is correct and click on OK.

Note: Information about transaction support via API is available in the Information exchange section.

Configuring Automatic collection

Automatic collection can be configured as other standard payment methods.

Related information

Transaction statuses transitions