Instant Payment Notification (IPN)

Last update: Mar 12th, 2021

Summary

About
How does it work?
Merchant response
Hashing example

About

IPN provides automatic notification for every status of a transaction from online payment system, being a link between PayU servers and merchant's servers. This notification method will enable transaction data receiving for future processing in merchant's transaction management systems.

How does it work?

In order to be able to receive IPNs the merchant should have set a valid URL in the designated area from cPanel.
For an authorized and authenticated order, the PayU server will send a HTTP POST notification which encapsulates a structure with all data referencing that transaction.

A signature for authentication is used in the request. The signature is built using HMAC_MD5 algorithm and a common secret key established between PayU and the seller. The HMAC algorithm is applied to all data set.

If the notification fails and the merchant server does not respond properly, it will be retried for a maximum of 50 attempts in a maximum period of 10 days. The time between each attempt will be increased as the number attempts raises. This will PayU try to prevents any problem with merchant servers, in order for it to be able to receive transaction notifications.

Parameter Description

SALEDATE Sale date in the following format: Y-m-d G:i:s (Y-year-4 digits, m-month-2 digits, d-day-2 digits, G-hour-2 digits, i-m-2 digits, s-second-2 digits)

REFNO PayU global order reference.

REFNOEXT Order reference code (max. 10 chars) provided by seller

ORDERNO Seller order number (max. 6 chars)

ORDERSTATUS

PAYMENT_AUTHORIZED	payment authorized, order approved
PAYMENT_RECEIVED	wired transfer payment is finished
TEST	test order
CASH	order with cash on delivery
COMPLETE	payment finished, delivery confirmed by merchant
REVERSED	order reversed, money unlocked in the customer account
REFUND	order refund, returned to the customer account
SUSPECT	fraud suspect order
PENDING	pending order waiting for approval
PROCESSING	payment has been authorized, the order is in approval process
INVALID	invalid data entered by the customer
-	unfinished order

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. For eg.: "Visa/MasterCard/Eurocard" or "Visa/MasterCard/Eurocard | MasterPass"

PAYMETHOD_CODE The code of the payment method used. For eg.: "CCVISAMC" or "CCVISAMC|MASTERPASS" for orders initialized through MasterPass method

HAS_FAST_REFUND Specifies if a refund order was made using fast refund. Parameter is present only for orders made with fast refund. Possible values: "YES"

CHARGEBACK Chargeback reason of refund order.

REFUND_REQUEST_ID

If the ORDERSTATUS is either REFUND or REVERSED, this contains the unique ID that was sent in the IRN response. Please refer to the IRN documentation for more information regarding this value.

This field will not be sent unless your account is configured on our side to receive it. Please contact us for more information. If your account is already configured, you may enable (or disable) receiving this field anytime via CPanel, in the IPN settings page.

BILLING INFORMATION

FIRSTNAME First Name (max. 40 chars)

LASTNAME Last Name (max. 40 chars)

IDENTITY_NO

IDENTITY_ISSUER

IDENTITY_CNP

COMPANY Company Name (max 40 chars)

REGISTRATIONNUMBER Company VAT number

FISCALCODE Company unique registration code

CBANKNAME Company bank name (max. 40 chars)

CBANKACCOUNT Company bank account (max 50 chars)

ADDRESS1 Address (max. 100 chars)

ADDRESS2 More address information (max. 100 chars)

CITY City (max. 30 chars)

STATE State/County (max. 30 chars)

ZIPCODE Zip code (max 30 chars)

COUNTRY Country (max 50 chars)

PHONE Phone number (max. 40 chars)

FAX Fax number (max. 40 chars)

CUSTOMEREMAIL Customer email address (max 40 chars)

DELIVERY INFORMATION

FIRSTNAME_D First Name (max 40 chars)

LASTNAME_D Last Name (max. 40 chars)

COMPANY_D Company Name (max 50 chars)

ADDRESS1_D Address (max. 100 chars)

ADDRESS2_D Extra address information (max. 100 chars)

CITY_D City (max 30 chars)

STATE_D State/County (max 30 chars)

ZIPCODE_D Zip code (max 20 chars)

COUNTRY_D Country (max 50 chars)

PHONE_D Telephone number (max 40 chars)

IPADDRESS Customer IP address (max 250 chars)

CURRENCY Currency used in order.

IPN_PID[] Array of products codes, within current order, from PayU system (PayU reference codes)

IPN_PNAME[] Array with products names from current order

IPN_PCODE[] Array with seller reference code for order products. (seller reference)

IPN_INFO[] Array with extra information for each product within current order.

IPN_QTY[] Quantities array

IPN_PRICE[] Array with prices for each product (no VAT), with dot as float separator

IPN_VAT[] VAT values array for each product.

IPN_VER[] Array with version of each product.

IPN_DISCOUNT[] Array with discount values within a promotion. It includes VAT values.

IPN_PROMONAME[] Promotions names for the above discounts.

IPN_DELIVEREDCODES[] Array with codes delivered to client, if the contract specifies this feature. Each row is only one string, using comma as separator

IPN_TOTAL[] Partially total on order line (including VAT), using dot (.) as float separator

IPN_TOTALGENERAL[] Total transaction sum, including shipping and VAT, using dot (.) as float separator.

IPN_SHIPPING Shipping costs, expressed in the same currency as CURRENCY field, using dot (.) as float separator.

IPN_GLOBALDISCOUNT Global order discount. It is an optional field that is sent only for values greater than 0.

IPN_COMMISSION PayU commission, using dot (.) as float separator.

HASH HASH signature which is build from all the above fields.

* For IPNs sent in case of refund orders information about products (like IPN_PID, IPN_PNAME, IPN_PCODE, IPN_INFO, IPN_QTY) may be missing or different than the ones sent in Authorization request.
In case of IPN for Refund orders, the product information will be sent only if it is a "Full refund" or a "Partial refund that only has one product". Because of this you should not use these fields to match products or do specific logic based on it.

Additional parameters for loyalty points:

Merchants can also receive in IPN the money amount worth of loyalty points used for payment. This feature has to be activated by PayU Operational staff.
Merchants can receive in IPN the following keys:

USED_LOYALTY_POINTS	loyalty points used for payment
USED_LOYALTY_POINTS_DETAILS_PROGRAM (where PROGRAM will be replaced with the specific program of loyalty points)	loyalty points of the type specified used for payment

Merchant response

PayU expects to get an answer anywhere in the document (in the output of your script), in the following format:

            <EPAYMENT>DATE|HASH</EPAYMENT>

DATE	HASH
DATE	Echo response date in the following format: [YmdGis] (Y-year-4 digits, m-month-2 digits, d-day-2 digits, G-hour-2 digits, i-minutes-2 digits, s-seconds-2 digits)
HASH	HASH response (md5 HASH made from IPN_PID[0], IPN_PNAME[0], IPN_DATE and DATE (the above field) fields.

HASH used fields are the following:

DATE	HASH
IPN_PID[0]	Echo replay from original IPN – First product ID from order.
IPN_PNAME[0]	Echo replay from original IPN – first product name from order.
IPN_DATE	Echo replay from original IPN – IPN date in the following format: [YmdGis] (Y-year-4 digits, m-month-2 digits, d-day-2 digits, G-hour-2 digits, i-minutes-2 digits, s-seconds-2 digits)
DATE	Response date (server time) in the following format: [YmdGis] (Y-year-4 digits, m-month-2 digits, d-day-2 digits, G-hour-2 digits, i-minutes-2 digits, s-seconds-2 digits)

Hashing signature building example

Field name	Field length	Field value
SALEDATE	19	2004-06-01 12:22:09
REFNO	7	1000037
REFNOEXT	0
ORDERNO	2	13
ORDERSTATUS	8	COMPLETE
PAYMETHOD	13	Wire transfer
FIRSTNAME	4	John
LASTNAME	5	Smith
IDENTITY_NO	9	BV-667788
IDENTITY_ISSUER	0
COMPANY	0
REGISTRATIONNUMBER	0
FISCALCODE	0
CBANKNAME	0
CBANKACCOUNT	0
ADDRESS1	15	101 Main Street
ADDRESS2	0
CITY	8	New York
STATE	8	New York
ZIPCODE	6	500365
COUNTRY	24	United States of America
PHONE	12	951-121-2121
FAX	0
CUSTOMEREMAIL	19	johnsmith@email.com
FIRSTNAME_D	4	John
LASTNAME_D	5	Smith
COMPANY_D	0
ADDRESS1_D	15	101 Main Street
ADDRESS2_D	0
CITY_D	8	New York
STATE_D	8	New York
ZIPCODE_D	6	500365
COUNTRY_D	24	United States of America
PHONE_D	12	951-121-2121
IPADDRESS	14	213.233.121.50
CURRENCY	3	USD
IPN_PID[0]	1	1
IPN_PNAME[0]	16	Software program
IPN_PCODE[0]	5	PM_11
IPN_INFO[0]	0
IPN_QTY[0]	1	1
IPN_PRICE[0]	5	29.00
IPN_VAT[0]	4	0.00
IPN_VER[0]	0
IPN_DISCOUNT[0]	4	0.00
IPN_PROMONAME[0]	0
IPN_DELIVEREDCODES[0]	0
IPN_TOTAL[0]	5	29.00
IPN_TOTALGENERAL	5	34.00
IPN_SHIPPING	4	5.00
IPN_COMMISSION	4	3.38
IPN_DATE	14	20050303123434

HMAC source string is built by merging to each field value the value length. So, for the above data we will have the following HMAC source string:

            192004-06-01 12:22:097100003702138COMPLETE13Wire transfer4John5Smith9BV-66778800000015101 Main Street, nr.208New York 8New York65003658 United States ofAmerica12951-121-2121019johnsmith@email.com4John5Smith015101 Main Street, nr.208NewYork8New York65003658 United States of America12951-121-212114213.233.121.503USD1116Softwareprogram5PM_11011529.0040.00040.0000529.00534.0045.0043.381420050303123434

The secret key in this example is: AABBCCDDEEFF

For this source string, the MD5 HASH value is: f87d96c8b5daa65b63cae5171280b7eb

For this example, the response is built in the same way, only using shorter data formats for date values. HMAC source string is built from the following:

Field name	Field length	Field value
IPN_PID[0]	1	1
IPN_PNAME[0]	16	Software program
IPN_DATE	14	20050303123434
DATE	14	20050303123434

So, the HMAC source string will be:

            1116Software program14200503031234341420050303123434

and the HMAC MD5 string will be:

            9449ef06f16a0862950008691194d30f

HASH fields values are case insensitive.

Notified server response has to be:

            <EPAYMENT>20050303123434|9449ef06f16a0862950008691194d30f</EPAYMENT>

If it is an invalid answer, the notification is not confirmed. PayU system will resend the notification within a few minutes.