Confirmation Page

This page allows you to get system confirmations related with the transaction results. You can update your system’s inventories, orders, or databases. This page is not visible to the customer and its goal is to enable communication between systems. The data is sent via the HTTP POST method.
If the payer generates payment retries during the payment process, a confirmation page is generated for each transaction. This page is invoked for approved and rejected states.

The confirmation page lets you update the databases in your system; hence, this page should not include HTML code as it’s not visible to the buyer. This page is optional; when a transaction is complete (i.e., when approved, rejected, or when canceled) our platform sends the variables via the HTTP POST method.

In the confirmation page, you must capture the data you want to store in the database. This capture depends on the programming language you use.

Considerations

  • If your site is restricted with basic access authentication or similar, disable it for the confirmation url.
  • The IP associated with the confirmation URL should be public; do not use URL accessible from intranet or localhost.
  • If you’re using HTTPS, you must have a valid certificate.
  • Do not use security certificates elliptic curve or those who have the suite of encryption TLS_ECDHE_ECDSA_WITH_RC4_128_SHA on your confirmation page.
  • PayU assumes that the confirmation page is reported correctly when receives the HTTP 200 code; otherwise, PayU makes a maximum of nine (9) attempts to send the confirmation page to your system. If after these attempts, HTTP 200 code is not received, PayU sends an email alert.
  • PayU reports the confirmation page once the transaction has a final status for example, when approved, rejected or expired. If a transaction is in progress (waiting for payment or analysis), PayU does not report until the transaction has a final status.

Variables sent with the confirmation page

Variables in the confirmation page
Field Type Size Description
merchant_id Numeric 12 Merchant’s ID number in PayU’s system, you find this number in the account creation mail.
state_pol Alphanumeric 32 Indicates the status of the transaction in the system.
See the transaction status in the given column.
risk Decimal (#.00) Risk associated with the transaction. Values between 0 and 1.
The higher value, the greater the risk.Format ###.00.
response_code_pol Alphanumeric 255 PayU’s response code.
See the response codes in the given column.
reference_sale Alphanumeric 255 Reference of the sale or order. It must be unique for each transaction that is sent to the system.
reference_pol Alphanumeric 255 The reference or transaction number generated by PayU.
sign Alphanumeric 255 Digital signature created for each of one the transactions.
extra1 Alphanumeric 255 Additional field to send information about the purchase. For example, description of the purchase if you would like to display it on the confirmation page
extra2 Alphanumeric 255 Additional field to send information about the purchase. For example, internal codes of the products
payment_method Numeric The internal identifier of the payment method used.
See the codes of the payment methods.
payment_method_type Numeric The payment method type used for the payment.
installments_number Numeric Number of installments in which the credit card payment was deferred.
value Numeric 14,2 Total amount of the transaction. It can contain two decimal digits. For example, 10000.00 or 10000
tax Numeric 14,2 VAT value of the transaction, if VAT zero is sent the system will automatically apply the 19%. It can contain two decimal digits. For example: 19000.00. In case you have no VAT you should fill out 0.
additional_value Numeric 14,2 Non commissionaire Additional Value.
transaction_date Date(YYYY-MM-DD HH:mm:ss) The date the transaction was made.
currency Alphanumeric 3 The currency in which the payment is made.
See the accepted currencies.
email_buyer Alphanumeric 255 Field that contains the buyer’s email to notify the transaction’s result by email. It’s recommended to validate it when the data is taken from a form.
cus Alphanumeric 64 The cus (unique tracking code) is the payment’s reference within the Bank, it applies only to payments with PSE
pse_bank Alphanumeric 255 The name of the bank, applies only to payments with PSE.
test Boolean (true, false) Variable to identify whether the operation was a test.
description Alphanumeric 255 Description of the sale.
billing_address Alphanumeric 255 The billing address
shipping_address Alphanumeric 50 The delivery address for the merchandise.
phone Alphanumeric 20 The buyer’s residence phone.
office_phone Alphanumeric 20 The buyer’s daytime phone.
account_number_ach Alphanumeric 36 The transaction’s identifier.
account_type_ach Alphanumeric 36 The transaction’s identifier.
administrative_fee Decimal (#.00) Value of the administrative fee
administrative_fee_base Decimal (#.00) Base value of the administrative fee
administrative_fee_tax Decimal (#.00) Tax value of the administrative fee
airline_code Alphanumeric 4 Airline code
attempts Numeric Number of attempts of sending the confirmation.
authorization_code Alphanumeric 12 Sale’s authorization code
bank_id Alphanumeric 255 Bank identifier
billing_city Alphanumeric 255 The billing city.
billing_country Alphanumeric 2 The ISO code of the country associated with the billing address.
commision_pol Decimal (#.00) Value of the commission.
commision_pol_currency Alphanumeric 3 Currency of the commission
customer_number Numeric Customer number.
date Date (YYYY-MM-DD HH:mm:ss) Date of the operation.
error_code_bank Alphanumeric 255 Error code of the bank.
error_message_bank Alphanumeric 255 Error message of the bank
exchange_rate Decimal (#.00) Value of the exchange rate.
ip Alphanumeric 39 The IP address from which the transaction was made.
nickname_buyer Alphanumeric 150 Short name of the buyer.
nickname_seller Alphanumeric 150 Short name of the seller.
payment_method_id Numeric Identifier of payment methods.
See the codes of the payment methods.
payment_request_state Alphanumeric 32 Status of the payment request.
pseReference1 Alphanumeric 255 Reference no. 1 for PSE payments.
pseReference2 Alphanumeric 255 Reference no. 2 for PSE payments.
pseReference3 Alphanumeric 255 Reference no. 3 for PSE payments.
response_message_pol Alphanumeric 255 PayU’s response message.
See the response messages in the given column.
shipping_city Alphanumeric 50 The city where the merchandise is delivered.
shipping_country Alphanumeric 2 The ISO code associated with the country where the merchandise is delivered.
transaction_bank_id Alphanumeric 255 ID of the transaction in the bank’s system.
transaction_id Alphanumeric 36 Transaction identifier.
payment_method_name Alfa Numeric 255 Payment method used in the payment, for example VISA.

POST example send to the confirmation page

The following is a basic example of the variables sent to the response page via POST:

response_code_pol=5
phone=
additional_value=0.00
test=1
transaction_date=2015-05-27 13:07:35
cc_number=************0004
cc_holder=test_buyer
error_code_bank=
billing_country=CO
bank_referenced_name=
description=test_payu_01
administrative_fee_tax=0.00
value=100.00
administrative_fee=0.00
payment_method_type=2
office_phone=
email_buyer=test@payulatam.com
response_message_pol=ENTITY_DECLINED
error_message_bank=
shipping_city=
transaction_id=f5e668f1-7ecc-4b83-a4d1-0aaa68260862
sign=e1b0939bbdc99ea84387bee9b90e4f5c
tax=0.00
payment_method=10
billing_address=cll 93
payment_method_name=VISA
pse_bank=
state_pol=6
date=2015.05.27 01:07:35
nickname_buyer=
reference_pol=7069375
currency=USD
risk=1.0
shipping_address=
bank_id=10
payment_request_state=R
customer_number=
administrative_fee_base=0.00
attempts=1
merchant_id=508029
exchange_rate=2541.15
shipping_country=
installments_number=1
franchise=VISA
payment_method_id=2
extra1=
extra2=
antifraudMerchantId=
extra3=
nickname_seller=
ip=190.242.116.98
airline_code=
billing_city=Bogota
pse_reference1=
reference_sale=2015-05-27 13:04:37
pse_reference3=
pse_reference2=

Signature validation

The signature validation allows you to check the data integrity, you must generate the signature with the information you find in the confirmation page and compare it with the information from the signature parameter.

To validate the signature in the confirmation page, you should consider:

  • If the second decimal is zero, the new_value to generate the signature must have one decimal. Example (150.00 -> 150.0).
  • If the second decimal is not zero, the new_value to generate the signature must keep the same two decimals. Example (150.26 -> 150.26).
  • Get the parameters to generate the signature (merchant_id, reference_sale, value, currency, and state_pol) from the confirmation page, do not get them from your database.
  • You must store your ApiKey safely.
  • Create the signature as follows:
"ApiKey~merchant_id~reference_sale~new_value~currency~state_pol"

Example

With one decimal

Your apiKey: 4Vj8eK4rloUd272L48hsrarnUA 
Parameters obtained from the confirmation page
- merchant_id = 508029
- reference_sale = TestPayU04
- value = 150.00
- currency = USD
- state_pol = 6

The signature is generated in the following way: 
MD5(4Vj8eK4rloUd272L48hsrarnUA~508029~TestPayU04~150.0~USD~6) = b607a2c2fa100e0947b206d41864fb86

sign = b607a2c2fa100e0947b206d41864fb86

With two decimals

Your apiKey: 4Vj8eK4rloUd272L48hsrarnUA 
Parameters obtained from the confirmation page:
- merchant_id = 508029
- reference_sale = TestPayU05
- value = 150.26
- currency = USD
- state_pol = 4

The signature is generated in the following way: 
MD5(4Vj8eK4rloUd272L48hsrarnUA~508029~TestPayU05~150.26~USD~4) = 1d95778a651e11a0ab93c2169a519cd6

sign = 1d95778a651e11a0ab93c2169a519cd6 

Compare your signature

Algorithm:  

 ( ~ ~ ~ ~ ~ )


Result: 

This calculator lets you generate the signature using any of the available encryption methods.

Payment retries

When a transaction is rejected, the payer has the option to retry the payment using the same payment method or another. Keep in mind that for each attempt, PayU makes the call to the confirmation page with the corresponding transaction status.

Each of these calls are made with the same payment reference (reference_sale), the same order identifier (reference_pol) but with different transaction identifier (transaction_id). Therefore, you can receive several calls to the confirmation page for the same sale.

Below, you find an example of a rejected attempt and its approved retry:

reference_sale=2015-05-27 13:04:37
reference_pol=7069375
transaction_id=f5e668f1-7ecc-4b83-a4d1-0aaa68260862
state_pol=6

reference_sale=2015-05-27 13:04:37
reference_pol=7069375
transaction_id=01cfdce8-68d5-4a4c-aabf-d89370a0b92f
state_pol=4

Note that if one of those calls to the confirmation page indicates that a payment reference (reference_sale) was approved, you can be certain that you will not receive any report to the same reference.