Confirmation Page
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.
- The format of your confirmation page must be
x-www-form-urlencoded
. - 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 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.
Whitelist of IP Addresses for PayU Latam Servers
To ensure seamless communication between your server and PayU Latam servers, it is necessary to whitelist our IP addresses. This is especially important if your server is protected by a firewall. All webhook requests and communication from PayU servers will originate from the IP addresses listed below.
Production Environment
- 198.61.156.98
- 190.216.203.233
- 34.233.144.154
Sandbox Environment
- 50.56.9.170
- 74.205.10.14
- 54.158.171.129
By whitelisting these addresses, you can ensure that requests and notifications from PayU are properly received.
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. |
extra2 | Alphanumeric | 255 | Additional field to send information about the purchase. |
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 e-mail address to notify the transaction’s result. 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. |
pse_reference1 | Alphanumeric | 255 | Reference no. 1 for PSE payments. |
pse_reference2 | Alphanumeric | 255 | Reference no. 2 for PSE payments. |
pse_reference3 | 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 confirmation 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
, andstate_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
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.