Last update: Sept 30th, 2016
For each customer that clicks the "Checkout" button in the merchant's website (or mobile application), an HTTP POST must be initiated to https://secure.payu.ro/order/lu.php using the LiveUpdate (LU) API, in order for the order to get started. The customer is then redirected to the PayU payment pages, where he has to enter the data required to authorize the transaction.
The LiveUpdate API is product-based, meaning that any order must contain at least one product, uniquely identified in the merchant's account through it's product code (recommended). The PayU server expects data in the following structure and order:
| Field Name | Description |
| MERCHANT | The merchant's ID, available in Control Panel (Account Management / Account Settings) |
| ORDER_REF | Order reference number in merchant's system (for easier order identification) |
| ORDER_DATE | The date when the order is initiated in the system, in YYYY-MM-DD HH:MM:SS format (e.g.: "2012-05-01 21:15:45") |
| Field Name | Description | Optional Field? |
| ORDER_PNAME[] | Array with the product names (maximum length: 155 characters per product name) | No |
| ORDER_PGROUP[] | Array with the ID's of the product groups (optional, the group ID's managed in Control Panel - Products / Product Groups ) | Yes |
| ORDER_PCODE[] | Array with the product codes (maximum length: 50 characters per product code). If multiple products are sent (in the same or subsequent transactions) with the same product code, PayU will update the product with the corresponding ORDER_PCODE (overwriting all the other product information - name, price, taxes). | No |
| ORDER_PINFO[] | Array with additional product info (displayed in the payment pages under the product name) | Yes |
| ORDER_PRICE[] | Array with the product prices, positive number, with "." as a decimal separator. | No |
| ORDER_QTY[] | Array with the quantities for each product. | No |
| ORDER_VAT[] | Array with VAT values for each product in the order. | No |
| ORDER_PRICE_TYPE[] | Array that specifies if the ORDER_PRICE[] includes the VAT. Possible values: "GROSS" (VAT included) and "NET" (VAT will be added by PayU). The parameter is optional, but if not specified, the default value is "NET" . Please note that using "NET" and ORDER_VAT[] different from 0 is deprecated and will be removed in the future. | Yes |
| ORDER_SHIPPING | Shipping costs for the order. | No |
| PRICES_CURRENCY | The currency in which the prices, taxes, shipping costs and discounts are expressed.
Accepted values: RON, EUR, USD. If the parameter is not specified, the default value is RON*. To transact a different currency than the one in which the prices are specified, use the CURRENCY parameter. |
Yes |
| DISCOUNT | The discount value for the order, positive number, with "." as a decimal separator (optional) | Yes |
| DESTINATION_CITY | The city where the order delivery is to be made (optional). If the parameter is specified, the customer will not be able to change its value in the PayU payment pages | Yes |
| DESTINATION_STATE | The state (county) where the order delivery is to be made (optional). If the parameter is specified, the customer will not be able to change its value in the PayU payment pages. Possible values for validation are in the "State/County List", available in Control Panel . | Yes |
| PAY_METHOD | The payment method for the transaction (optional). If the parameter is specified, the customer
will not be able to change its value in the PayU payment pages. If the parameter is not specified,
a drop-down with the payment methods active on the account will be displayed. Possible values:
|
Yes |
| ORDER_HASH | HMAC MD5 signature for the sent data (HMAC is defined in RFC 2104 ). | No |
| Field Name | Description | Optional Field? |
| TESTORDER | Text parameter ("TRUE" or "FALSE"), used to initiate transactions in TEST MODE (optional). If the parameter is active, the PayU payment form will be pre-filled with test payment details (you don't need any credit card test numbers). | Yes |
| DEBUG | Boolean parameter ("0" or "1"), used to require the PayU support team's assistance during the implementation (optional). If the parameter is active, you can request logs of the communication between your server and PayU. | Yes |
| LANGUAGE | Allows setting a specific language for the payment interface (and overriding the language detected
by the geolocation) (optional). Possible values:
|
Yes |
| ORDER_TIMEOUT | Sets the interval in which the order can be placed (optional, takes a number of seconds as a value). | Yes |
| TIMEOUT_URL | SETS the URL for the redirect of the customer, in case the ORDER_TIMEOUT expired (optional). | Yes |
| AIRLINE_INFO | Parameter to be used by airline services operators; see below for structure of this parameter. | Yes |
The airline information parameter, AIRLINE_INFO, should be provided by any airline services operator
merchant. This parameter contains basic information about the passenger and his/her flight ticket.
| Parameter | Description | Required | ||||||||||||||||||||||||||||||
PASSENGER_NAME |
First name and last name of the passenger (max. 20 characters) | Yes | ||||||||||||||||||||||||||||||
TICKET_NUMBER |
Ticket number (max. 14 characters) | No | ||||||||||||||||||||||||||||||
RESTRICTED_REFUND |
Possibility of refund (0 - no restrictions, 1 - non refundable) | No | ||||||||||||||||||||||||||||||
RESERVATION_SYSTEM |
Name of reservation system (e.g. ATS = Delta, SABR = Sabre) (max. 4 characters) | No | ||||||||||||||||||||||||||||||
TRAVEL_AGENCY_CODE |
The code of travel agency (max. 8 characters) | No | ||||||||||||||||||||||||||||||
TRAVEL_AGENCY_NAME |
The name of travel agency (max. 25 characters) | No | ||||||||||||||||||||||||||||||
FLIGHT_SEGMENTS |
An array containing information about this flight transits. First element
should have
For instance, the |
Yes |
| Parameter | Description | Length | Format | Mandatory/Optional |
| ADDRESS_MATCH | Indicates whether the cardholder's shipping address and billing address are the same. | 2-3 characters | String Values accepted:
|
Optional |
| BILL_ADDRESS3 | Third line of the street address or equivalent local portion of the cardholder's billing address associated with the card used for this purchase. | Variable, maximum 50 characters | String |
Optional |
| BILL_STATE_CODE | The state or province of the cardholder's billing address associated with the card used for this purchase. | Variable, maximum 7 characters | String Format: The ISO-3166-2 code of the country subdivision: country - subdivision Examples: RO-VN (Romania - Vrancea) GB-LND (United Kingdom - London) |
Optional |
| HOME_PHONE_COUNTRY_PREFIX | The country code of the home phone number. | Variable, maximum 3 characters | String Refer to ITU-E.164 for additional information on format. |
Optional |
| HOME_PHONE_SUBSCRIBER | The cardholder's home phone number (without the country code). | Variable, maximum 15 characters | String Refer to ITU-E.164 for additional information on format. |
Optional |
| MOBILE_PHONE_COUNTRY_PREFIX | The country code of the mobile phone number. | Variable, maximum 3 characters | String Refer to ITU-E.164 for additional information on format. |
Optional |
| MOBILE_PHONE_SUBSCRIBER | The cardholder's mobile phone number (without the country code). | Variable, maximum 15 characters | String Refer to ITU-E.164 for additional information on format. |
Optional |
| WORK_PHONE_COUNTRY_PREFIX | The country code of the work phone number. | Variable, maximum 3 characters | String Refer to ITU-E.164 for additional information on format. |
Optional |
| WORK_PHONE_SUBSCRIBER | The cardholder's work phone number (without the country code). | Variable, maximum 15 characters | String Refer to ITU-E.164 for additional information on format. |
Optional |
| DELIVERY_ADDRESS3 | Third line of the street address or equivalent local portion of the shipping address requested by the cardholder. | Variable, maximum 50 characters | String |
Optional |
| DELIVERY_STATE_CODE | The state or province of the shipping address. | Variable, maximum 7 characters | String Format: The ISO-3166-2 code of the country subdivision: country - subdivision Examples: RO-VN (Romania - Vrancea) GB-LND (United Kingdom - London) |
Optional |
| CARDHOLDER_FRAUD_ACTIVITY | Indicates whether the merchant experienced suspicious activity on the account. | 2-3 characters | String Values accepted:
|
Optional |
| DEVICE_CHANNEL | Indicates the type of channel interface being used to initiate the transaction. | 2 characters | String Values accepted:
|
Optional |
| CHALLENGE_INDICATOR | Indicates whether a challenge is requested for this transaction. For example, for Payment Authentication, a 3DS Requestor may have concerns about the transaction, and request a challenge. | 2 characters | String Values accepted:
|
Optional |
| CHALLENGE_WINDOW_SIZE | An override field that you can pass in to set the challenge window size to display to the end cardholder. The Access Control Server (ACS) will reply with content that is formatted appropriately to this window size to allow for the best user experience. The sizes are width x height in pixels of the window displayed in the cardholder browser window. | 2 characters | String Values accepted:
|
Optional |
| ACCOUNT_ADDITIONAL_INFORMATION | Additional information about the cardholder’s account provided by the 3DS Requestor. | Variable | String | Optional |
| TRANSACTION_TYPE | Identifies the type of transaction being authenticated. | 2 characters | String Values accepted:
|
Optional |
| SHIPPING_INDICATOR | The shipping method selected by the customer. | 2 characters | String Values accepted:
|
Optional |
| PREORDER_INDICATOR | Indicates whether cardholder is placing an order for merchandise with a future availability or release date. | 2 characters | String Values accepted:
|
Optional |
| PREORDER_DATE | Expected date that a pre-ordered purchase will be available. | 10 characters | String Format: YYYY-MM-DD |
Optional |
| DELIVERY_TIME_FRAME | Indicates the merchandise delivery time frame. | 2 characters | String
|
Optional |
| REORDER_INDICATOR | Indicates whether the cardholder is reordering previously purchased merchandise. | 2 characters | String
|
Optional |
| MERCHANT_FUNDS_AMOUNT | For prepaid or gift card purchase, the purchase amount total of prepaid or gift card(s) in major units. | Maximum 15 digits | Numeric | Optional |
| MERCHANT_FUNDS_CURRENCY | For prepaid or gift card purchase, currency code of the gift card. | 3 characters | String Format: ISO 4217 |
Optional |
| RECURRING_FREQUENCY_DAYS | Indicates the minimum number of days between authorizations. | Maximum 4 digits | Numeric | Optional |
| RECURRING_EXPIRY_DATE | It is the date after which no further authorizations shall be performed. | 10 characters | String Format: YYYY-MM-DD |
Optional |
| ACCOUNT_CREATE_DATE | It is the date when the cardholder opened the account with the 3DS Requstor. | 10 characters | String Format: YYYY-MM-DD |
Optional |
| ACCOUNT_DELIVERY_ADDRESS_FIRST_USED_DATE | It is the date when the shipping address used for this transaction was first used with the 3DS Requestor. | 10 characters | String Format: YYYY-MM-DD |
Optional |
| ACCOUNT_DELIVERY_ADDRESS_USAGE_INDICATOR | Indicates when the shipping address used for this transaction was first used with the 3DS Requestor. | 2 characters | String Values accepted:
|
Optional |
| ACCOUNT_NUMBER_OF_TRANSACTIONS_LAST_YEAR | Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous year. | Maximum 3 digits | Numeric | Optional |
| ACCOUNT_NUMBER_OF_TRANSACTIONS_LAST_DAY | Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous 24hours. | Maximum 3 digits | Numeric | Optional |
| ACCOUNT_NUMBER_OF_PURCHASES_LAST_SIX_MONTHS | Number of purchases with this cardholder account during the previous six months. | Maximum 4 digits | Numeric | Optional |
| ACCOUNT_CHANGE_DATE | It is the date when the cardholder’s account with the 3DS Requestor was last changed, including Billing or Shipping address, new payment account, or new user(s) added. | 10 characters | String Format: YYYY-MM-DD |
Optional |
| ACCOUNT_CHANGE_INDICATOR | Length of time since the cardholder’s account information with the 3DS Requestor was last changed, including billing or shipping address, new payment account, or new user(s) added. | 2 characters | String Values accepted:
|
Optional |
| ACCOUNT_AGE_INDICATOR | Length of time that the cardholder has had the account with the 3DS Requestor. | 2 characters | String Values accepted:
|
Optional |
| ACCOUNT_PASSWORD_CHANGED_DATE | It is the date when cardholder’s account with the 3DS Requestor had a password change or account reset. | 10 characters | String Format: YYYY-MM-DD |
Optional |
| ACCOUNT_PASSWORD_CHANGED_INDICATOR | Indicates the length of time since the cardholder’s account with the 3DS Requestor had a password change or account reset. | 2 characters | String Values accepted:
|
Optional |
| ACCOUNT_NAME_TO_RECIPIENT_MATCH | Indicates if the cardholder name on the account is identical to the shipping name used for this transaction. | 2-3 characters | String Values accepted:
|
Optional |
| ACCOUNT_ADD_CARD_ATTEMPTS_DAY | Indicates the number of attempts to add a card to cardholder's account in merchant's system within last 24 hours. | Maximum 3 digits | Numeric | Optional |
| ACCOUNT_AUTH_METHOD | Mechanism used by the cardholder to authenticate to the 3DS Requestor. | 2 characters | String Values accepted:
|
Optional |
| ACCOUNT_AUTH_DATETIME | Date and time of the cardholder authentication (in UTC). | 19 characters | String Format: YYYY-MM-DD HH:MM:SS |
Optional |
| REQUESTOR_AUTHENTICATION_DATA | Information about how the 3DS Requestor authenticated the cardholder before or during the transaction. | Variable | String | Optional |
| ACCOUNT_CARD_ADDED_INDICATOR | Indicates if and when the card was stored in the merchant account. | 2 characters | String Values accepted:
|
Optional |
| ACCOUNT_CARD_ADDED_DATE | Date when card has been stored in the merchant account. | 10 characters | String Format: YYYY-MM-DD |
Optional |
Merchant stores have the opportunity of including the billing and delivery information in the LiveUpdate requests made. This presents the advantage of pre-filling the sent information in the PayU payment pages, so that the customer doesn't have to.
The billing and delivery parameters are optional, not included in the HMAC MD5 calculation, and only the sent values in request will be pre-filled in the payment interface.
| Billing | ||
| Field Name | Description | Optional? |
| BILL_FNAME | Customer's first name | Yes |
| BILL_LNAME | Customer's last name | Yes |
| BILL_CITYPE | Shopper's ID type - mandatory for UPT. Accepted values: PERSONALID (identity card), PASSPORT (passport), DRVLICENSE (driving license) | Yes |
| BILL_CISERIAL | ID Card Series (for RO residents) | Yes |
| BILL_CINUMBER | ID Card Number (for RO or TR residents) | Yes |
| BILL_CIISSUER | ID Card Issuer (for RO residents) | Yes |
| BILL_CNP | Numeric Personal Code (for RO residents) | Yes |
| BILL_COMPANY | Legal company name for billing | Yes |
| BILL_FISCALCODE | Company's Fiscal Code (CUI/VAT ID) | Yes |
| BILL_REGNUMBER | Company's Registration Number at the Commerce Registry. | Yes |
| BILL_BANK | Company's bank | Yes |
| BILL_BANKACCOUNT | Company's bank account | Yes |
| BILL_EMAIL | Customer's email address | Yes |
| BILL_PHONE | Phone number | Yes |
| BILL_FAX | Fax number | Yes |
| BILL_ADDRESS | Customer's/Company's address | Yes |
| BILL_ADDRESS2 | Customer's/Company's address (additional) | Yes |
| BILL_ZIPCODE | Customer's/Company's ZIP/Postal Code | Yes |
| BILL_CITY | City | Yes |
| BILL_STATE | State/County | Yes |
| BILL_COUNTRYCODE | Country Code (RO for Romania) | Yes |
| Delivery | ||
| Field Name | Description | Optional? |
| DELIVERY_FNAME | Customer's first name | Yes |
| DELIVERY_LNAME | Customer's last name | Yes |
| DELIVERY_COMPANY | Legal company name for delivery | Yes |
| DELIVERY_PHONE | Phone number | Yes |
| DELIVERY_ADDRESS | Customer's/Company's Address | Yes |
| DELIVERY_ADDRESS2 | Customer's/Company's Address (additional) | Yes |
| DELIVERY_ZIPCODE | Customer's/Company's ZIP/Postal Code | Yes |
| DELIVERY_CITY | City | Yes |
| DELIVERY_STATE | State/County | Yes |
| DELIVERY_COUNTRYCODE | Country Code (RO for Romania) | Yes |
NOTE: If the parameters DESTINATION_CITY, DESTINATION_STATE or DESTINATION_COUNTRY are sent, these will override the values for the parameters DELIVERY_CITY, DELIVERY_STATE, DELIVERY_COUNTRYCODE.
Let's construct a LiveUpdate request, for the following transaction information:
| Information | Parameter | Value | Length |
| General Data | MERCHANT | PAYUDEMO | [8] |
| ORDER_REF | 112457 | [6] | |
| ORDER_DATE | 2012-05-01 15:51:35 | [19] | |
| Cart contents | ORDER_PNAME[] | "MacBook Air 13 inch", "iPhone 4S" | [19, 9] |
| ORDER_PCODE[] | "MBA13", "IP4S" | [5, 4] | |
| ORDER_PINFO[] | "Extended Warranty - 5 Years", "" | [27, 0] | |
| ORDER_PRICE[] | "2000", "400.50" | [4, 6] | |
| ORDER_PRICE_TYPE[] | "GROSS", "NET" | [5, 3] | |
| ORDER_QTY[] | "1", "2" | [1, 1] | |
| ORDER_VAT[] | "24", "24" | [2, 2] | |
| ORDER_SHIPPING | "50" | [2] | |
| PRICES_CURRENCY | "EUR" | [3] | |
| DISCOUNT | "10" | [2] | |
| DESTINATION_CITY | "București" | [10] | |
| DESTINATION_STATE | "București" | [10] | |
| DESTINATION_COUNTRY | "RO" | [2] | |
| PAY_METHOD | "CCVISAMC" | [8] | |
| Additional Info | TESTORDER | "TRUE" | Mandatory in HMAC signature when set to "TRUE" |
| LANGUAGE | "EN" | Not included in HMAC signature |
To validate this information when the order is placed, a HMAC MD5 signature is required, as a value for the ORDER_HASH parameter. The calculation is made using the secret key of the merchant (or demo) account, available in Control Panel, in the Account Management / Account Settings section.
The signature is calculated on a string, composed of each of the values above, with their corresponding lengths prepended (in UTF-8 bytes). The order of the parameters is important and must be the same as defined in the list above.
For the information used as a sample order in the table above, the resulting string of the concatenated lengths and values of the request parameters is the following:
8PAYUDEMO6112457192012-05-01 15:51:3519MacBook Air 13 inch9iPhone 4S5MBA134IP4S27Extended Warranty - 5 Years0420006500.5011122242242503EUR21010București10București2RO8CCVISAMC5GROSS3NET4TRUE
NOTE that for the second product, there was no value for the ORDER_PINFO[] parameter, but because the parameter was specified, we have to take into account it's length (0) in the string composition.
The TESTORDER parameter is taken into account for string composition and HMAC MD5 calculation only when the value is set to "TRUE", otherwise it is optional for HMAC MD5 calculation.
The LANGUAGE parameter is not taken into account for string composition and HMAC MD5 calculation.
The data has to be transported in UTF-8 format, in order to correctly calculate the lengths on both ends (your server and the PayU platform).
If the secret key for the merchant account is SECRET_KEY, the resulting HMAC MD5 (and value for the ORDER_HASH parameter) is efb6260ea1764d2ccb555bb048cd441c.
The sample LiveUpdate HTTP POST request can be created with the following HTML form:
Merchants can configure the amount of personal data that is transited through the PayU system from the Control Panel, in the Account Management / Payment Form Settings section. The information set as mandatory there should be also sent through LiveUpdate, if we want to redirect the customer straight to the last step of the payment process.
As a minimum, if all the fields are set to optional/hidden, PayU requires for antifraud purposes the following fields: BILL_FNAME, BILL_LNAME, BILL_EMAIL, BILL_PHONE and BILL_COUNTRYCODE. The validation for the BILL_PHONE field is although relaxed (so if you, as a merchant, do not collect / use the phone number of the customer, you can use a dash "-" as a value).
If this information is sent through LiveUpdate, for the redirect to the final step of the order (e.g. card data entry, for CCVISAMC) the request must also contain the AUTOMODE parameter, with the value "1".
NOTE: This parameter will function properly only if all the required fields are sent. Otherwise, the process will begin with the page in which the billing/delivery data are collected.
<input name="AUTOMODE" value="1" type="hidden" />
In order to redirect the customer back to the website (her account or a customized thank you message), you can use the BACK_REF parameter with a URL. The BACK_REF redirect is, by default, made only if the used payment method is one with instant authorization (e.g. will be made for CCVISAMC, but not for regular WIRE transfer).
A merchant could use GET parameters in order to specify an order or customer identifier, as below:
<input name="BACK_REF" value="{*}http://domain.com/process.php?order=123456*" type="hidden" />
To make sure that the redirect comes from PayU, a control variable is attached to the URL to which the redirect is made. The control variable (a GET parameter, ctrl) is also HMAC MD5, calculated on a string composed from the URL (with all parameters) to which PayU redirects, with the length of that URL (parameters included) prepended.
Sample:
For url: http://www.yourdomain.com/process.php?order=123456&ctrl=741fcf35a297e256f4090c4dfc0ed65
The source string for the ctrl HMAC MD5 calculation is: http://www.yourdomain.com/process.php?order=123456
The PayU Platform can also handle installment payments. This can be done using two different technical ways, based on the user's selection of the payment method. If the merchant is simply redirecting the user to the PayU pages then installment options will be available by default. This way, implementing additional payments is a seamless process for the merchant. The user will see all the payment options available in the first page of the payment process, below the personal details form.
If the user will select the payment method on the merchant's site, then the merchant will have to send to PayU the specific PAY_METHOD value. When the PAY_METHOD variable has a predefined value, then PayU will use the value received from the merchant and the user will be unable to change the payment method from the PayU pages.
PAY_METHOD
<input name="PAY_METHOD" value="STARBT" type="radio" /> StarBT
Additionally, the number of installments can be selected on the merchant's site and sent to PayU with the "SELECTED_INSTALLMENTS_NO" value, as shown below:
PAY_METHOD
<select name="SELECTED_INSTALLMENTS_NO">
<option value="1">Direct Payment</option>
<option value="3">3 Payments</option>
<option value="6">6 Payments</option>
<option value="12">12 Payments</option>
</select>
NOTE: If AUTOMODE is used then the use of the PAY_METHOD is MANDATORY since the user will no longer see the first page of the payment process.
PayU can provide you with the Google Pay button on our payment page. This allows your customers to use a saved card from their Google account to finish the payment, instead of entering their card details.
This doesn't require any technical change on your side, but our operational team must perform changes on your account to use this feature. For more details, please reach out to our team.
Charging in another currency than the one in which prices are specified.
If you have more than one currency activated for your account, the customers can choose in the payment form the currency in which they will make the payment.
If you want to force the order's collecting using another currency than the one in which the prices are set (PRICES_CURRENCY), you can send the optional parameter:
<input name="CURRENCY" value="USD" type="hidden" />
If you get errors when trying to transmit your data, see the list below for problem descriptions for each type of error:
| Error | Description |
| ACCES DENIED | Your access to the PayU interface is not allowed. Please contact the PayU support team. |
| Invalid account | The MERCHANT parameter is incorrect or not specified |
| Access not permitted | You access to the LiveUpdate feature is restricted. You should contact your PayU Account Manager |
| Invalid Data | The data you have transmitted is not correctly formed. Please check the arrays |
| Invalid product code | The ORDER_PCODE[] array is incorrectly formed |
| Invalid product name | The ORDER_PNAME[] array is incorrectly formed |
| Invalid product group | The ORDER_PGROUP[] array is incorrectly formed |
| Invalid price | The ORDER_PRICE[] array is incorrectly formed |
| Invalid VAT | The ORDER_VAT[] array is incorrectly formed |
| Invalid Price | The calculated total is incorrect. Check the DISCOUNT and ORDER_SHIPPING parameters |
| Invalid Signature | The HMAC_MD5 signature is incorrectly calculated for the sent data |
| VAT calculation not supported for this integration type | The ORDER_PRICE_TYPE[] is "NET" and ORDER_VAT[] different from 0. |
| Invalid price type | ORDER_PRICE_TYPE[] must have one of the following values: NET or GROSS |
| Invalid Billing Country Code | Invalid BILL_COUNTRYCODE value |
| Invalid number of installments | The installments number sent in SELECTED_INSTALLMENTS_NO is not supported |
A request containing all the data above, placing a TEST transaction in the PayU demo account, and using both the AUTOMODE and BACK_REF features, is available in example: example.php