Instant Order Status (IOS)

Last update: July 07th, 2016

Summary

How does it work?
What is the data that must be sent to PayU?
Request authentication
What response do I receive from PayU?

1. How does it work?

Instant Order Status (IOS) makes it possible to query the PayU platform for the status of an order.

IOS can be triggered through HTTP POST or HTTP GET by accessing: https://secure.payu.ro/order/ios.php.

The query of the PayU database will be made individually, for one order at a time.

2. What is the data that must be sent to PayU?

In order to query the PayU system for an order status, the following parameters are required:

Parameter	Description
MERCHANT	Merchant's ID. Available in the PaVU administration interface, in the "Account administrator" / "Account settings" sections
REFNOEXT	The external reference number, sent by the merchant with the order.
HASH	Request signature - HMAC MD5 over a string composed through the fields above (HMAC defined at: RFC 2104)

3. Authentication

The request is authenticated with a HMAC_MD5 signature calculated on the sent data and a shared key (PayU/merchant). The string on which the signature will be created is composed like this: parameter length + parameter value.

We assume to have the following data:

Field name	Length (in bytes)	Field value
MERCHANT	8	PAYUDEMO
REFNOEXT	9	EPAY10425

In order to validate the sent data, a HMAC_MD5 signature has to be calculated, that will be encoded with the secret key attached to your account. The Secret Key is available in Control Panel, at the "Account Administration" / "Account settings" section [click here].

The source string for the HMAC_MD5 signature is created by prepending each field value (converted to string), with its length, without "new line" characters (for UTF-8 characters, the string length in bytes may be larger than the number of characters). The order of the fields that compose the source string who's signature must be calculated, must be the same as in the tables above.
For the data above, the source string is: 8PAYUDEMO9EPAY10425
The secret key for data validation is: 1231234567890123
The HMAC_MD5 signature calculated for the data above is: 6cb19f366fd9709b078b593b1736a4ea

4. What response do I receive from PayU?

The PayU system will respond inline, in XML format, with the following values:

ORDER_DATE	Order date in the format: Y-m-d G:i:s (Y-year-4 digits, m-month-2 digits, d-day-2 digits, Ghour-2 digits, i-minute-2 digits, s-second-2 digits)
REFNO	Global PayU reference number for the order(max. 9 characters)
REFNOEXT	Merchant reference number for the order (max. 10 characters) given through LiveUpdate
ORDERSTATUS	Current order status. Possible values: • NOT_FOUND - not existing/unfinished order • WAITING_PAYMENT - the order has been placed and payment is waiting • CARD_NOTAUTHORIZED - the card used for payment has not been authorized • IN_PROGRESS - payment has been authorized, the order is in approval process • PAYMENT_AUTHORIZED - payment authorized, order approved • COMPLETE - finished order (charged/delivered) • FRAUD - fraud suspect order • INVALID - invalid data entered by the customer • TEST - test order • CASH - order with cash on delivery • REVERSED - order reversed, money unlocked in the customer account • REFUND - order refund, money wire transferred to the customer account
PAYMETHOD	Used payment method (maxim 40 characters). In some special cases, like orders initialized through MasterPass method, at the end we will have concatenated the method through which the order was initialized.
ORDER_HASH	HMAC_MD5 signature for data validation

In case some API limit is defined in PayU system, we also return some specific headers with information about it (see API Limit documentation).

Sample response received from the platform:

<?xml version="1.0"?>
<Order>
	<ORDER_DATE>2016-07-08 11:39:06</ORDER_DATE>
	<REFNO>12368082</REFNO>
	<REFNOEXT>ORDER_REF3894835806767224</REFNOEXT>
	<ORDER_STATUS>IN_PROGRESS</ORDER_STATUS>
	<PAYMETHOD>Visa/MasterCard/Eurocard</PAYMETHOD>
	<HASH>928240d8a818f8c4643c05ff2529df9f</HASH>
</Order>

Sample response received from the platform when order is with MasterPass:

<?xml version="1.0"?>
<Order>
	<ORDER_DATE>2016-07-08 11:39:06</ORDER_DATE>
	<REFNO>12368082</REFNO>
	<REFNOEXT>ORDER_REF3894835806767224</REFNOEXT>
	<ORDER_STATUS>IN_PROGRESS</ORDER_STATUS>
	<PAYMETHOD>Visa/MasterCard/Eurocard | MasterPass</PAYMETHOD>
	<HASH>d5b95ef273bc4a055a0e995f9fb8aa05</HASH>
</Order>

Sample response received when limit is reached:

			<?xml version="1.0"?>
			<Error>
				Limit calls for IOS exceeded!
			</Error>

			<?xml version="1.0"?>
			<Error>
				Limit calls for IOS exceeded for this merchant!
			</Error>

Note: In case the merchant has sent more than one order with the same external reference, the query will return information for the most recent transaction found in the database for that reference.