Confirmation URL

PayU uses this URL to send an asynchronous HTTP POST request directly to your server once a transaction reaches a final state (Approved, Rejected, or Declined). Because this process occurs in the background, it remains invisible to the customer. Therefore, while the Response URL handles the customer-facing experience, the Confirmation URL manages the backend communication between PayU and your server.

Implementation Guidelines

• Automatic Updates: Use this mechanism to trigger automated workflows, such as updating databases, adjusting inventory levels, and finalizing order statuses.

• Retry Handling: PayU generates a unique confirmation for every transaction attempt. If a payer retries a payment, your system will receive a notification for each individual result, regardless of the outcome.

• Format Requirements: Since this URL serves purely for data transmission, your endpoint must not return HTML code or visual elements.

• Server-Side Logic: You must implement server-side logic in your preferred programming language to capture, parse, and process the variables transmitted by PayU.

Integration Methods

Depending on your integration type, use the following parameters to define your webhook endpoint:

Considerations

• Public Accessibility: The URL must be public. Avoid localhosts or internal intranets.

• Disable Authentication: Ensure the endpoint does not require Basic Auth or any security measures that would block PayU’s automated POST request.

• SSL/TLS Certificates: If you are using HTTPS for your Confirmation URL, you must employ a valid SSL/TLS certificate. Do not use elliptic curve security certificates or those with the TLS_ECDHE_ECDSA_WITH_RC4_128_SHA encryption suite for your Confirmation URL.

• Content Type: our server must be configured to process data in x-www-form-urlencoded format.

• Final Transaction Status Reporting: PayU will only trigger the Confirmation URL once a transaction reaches a final status (e.g., approved, rejected, or expired). You will not receive reports for transactions that are still in progress (waiting for payment or analysis).

• No HTML Output: Since this is a system-to-system call, your script should process the logic and return a standard HTTP 200 OK status without rendering HTML code.

Whitelist of IP Addresses for PayU Servers

To ensure that your server receives requests and notifications from PayU Latam, 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

• 34.233.144.154
• 184.73.94.138
• 52.73.124.136

Sandbox Environment

• 54.158.171.129

POST Parameters

PayU transmits a wide array of parameters to your server.

Important Considerations

• Dynamic Payloads: PayU adjusts the payload dynamically based on the payment method used. For example, PayU sends cc_number, cc_holder, and cardType for credit card transactions but excludes them for cash payments or bank transfers.

• Error Handling: Your integration must handle optional or missing keys to avoid script errors when specific variables are absent from the POST request.

• Configurable Variables: To include extended data—such as cardType, transaction_type, bank_reference_code, payment_method_id, expiration_date, or adminFee—please contact your PayU representative. These parameters are not sent by default and must be enabled specifically for your account.

POST Request Example for the Confirmation URL

The following example shows how our system sends parameters to your Confirmation URL using an HTTP POST request:

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=

Implementation Example (PHP)

This script captures the POST data sent by PayU (compatible with both WebCheckout and API notifications):

<?php
/**
 * PayU Confirmation URL / notifyUrl Listener
 * Signature algorithm: MD5
 *
 * This endpoint receives server-to-server notifications from PayU.
 * It must be publicly accessible and return HTTP 200 on success.
 */

// -----------------------------------------------------------------------------
// 1. Configuration
// -----------------------------------------------------------------------------

// Store securely (environment variable recommended)
$apiKey = 'YOUR_API_KEY_HERE';

// -----------------------------------------------------------------------------
// 2. Capture incoming data
//    - WebCheckout sends application/x-www-form-urlencoded
//    - API notifyUrl may send application/json
// -----------------------------------------------------------------------------

$data = $_POST;

if (empty($data)) {
    $rawBody = file_get_contents('php://input');
    $decoded = json_decode($rawBody, true);
    if (is_array($decoded)) {
        $data = $decoded;
    }
}

// -----------------------------------------------------------------------------
// 3. Extract required parameters (from Confirmation URL payload)
// -----------------------------------------------------------------------------

$merchantId     = $data['merchant_id']     ?? '';
$referenceSale  = $data['reference_sale']  ?? '';
$value          = $data['value']            ?? '';
$currency       = $data['currency']         ?? '';
$statePol       = $data['state_pol']        ?? '';
$receivedSign   = $data['sign']             ?? '';

// -----------------------------------------------------------------------------
// 4. Format value for signature (NO floats)
//    Rule:
//    - If second decimal is 0 → 1 decimal (150.00 → 150.0)
//    - Otherwise → 2 decimals (150.25 → 150.25)
// -----------------------------------------------------------------------------

$parts = explode('.', $value);

if (!isset($parts[1])) {
    $formattedValue = $parts[0] . '.0';
} elseif (strlen($parts[1]) > 1 && $parts[1][1] !== '0') {
    $formattedValue = $parts[0] . '.' . substr($parts[1], 0, 2);
} else {
    $formattedValue = $parts[0] . '.' . $parts[1][0];
}

// -----------------------------------------------------------------------------
// 5. Generate and validate signature (MD5)
// -----------------------------------------------------------------------------

$signatureString = implode('~', [
    $apiKey,
    $merchantId,
    $referenceSale,
    $formattedValue,
    $currency,
    $statePol
]);

$calculatedSign = md5($signatureString);

if (!hash_equals(strtolower($receivedSign), strtolower($calculatedSign))) {
    // Invalid signature — do NOT process the transaction
    http_response_code(403);
    echo 'Invalid signature';
    exit;
}

// -----------------------------------------------------------------------------
// 6. Signature valid — process transaction
// -----------------------------------------------------------------------------

switch ($statePol) {
    case '4':
        // APPROVED
        // ✔ Mark order as paid
        // ✔ Trigger fulfillment
        break;

    case '6':
        // REJECTED
        // ✔ Mark order as rejected
        break;

    case '5':
        // EXPIRED
        // ✔ Mark order as expired
        break;

    default:
        // Other states (optional handling)
        break;
}

// -----------------------------------------------------------------------------
// 7. Respond to PayU
// -----------------------------------------------------------------------------

http_response_code(200);
echo 'OK';

Signature Validation

To ensure the integrity of the data and verify that the notification originated from PayU, you must generate a signature on your server and compare it with the sign parameter sent in the HTTP POST request.

Rounding Rules for Webhooks

The rounding for the value field in webhooks follows these specific rules for the signature string:

• If the second decimal of the value is zero, format the new_value using one decimal place (e.g., 150.00 becomes 150.0).
• If the second decimal is not zero, retain two decimal places in the new_value (e.g., 150.25 remains 150.25).

Signature Format

Always use the values from the Confirmation URL (merchant_id, reference_sale, value, currency, and state_pol) to generate the signature. Do not use values from your own database.

The string to hash is:

apiKey~merchant_id~reference_sale~new_value~currency~state_pol

Signature Examples

The following examples illustrate how to generate a signature, in this case, using HMAC-SHA256.

Signature with One Decimal

Use this example when the second decimal of the value is 0. In this case, format the value with only one decimal place.

Signature with Two Decimals

Use the following example when the second decimal of the value is not 0. Format the value with two decimal places.

Validate Your Signature

Use this generator to create a signature with any of the available encryption methods. This functionality assists you in verifying the sign value that PayU sends to your Confirmation URL.

Payment Retries

If a transaction is rejected, the payer may retry using a different method. PayU sends a confirmation for each attempt.

• Each attempt shares the same payment reference (reference_sale) and order identifier (reference_pol).
• Each attempt has a unique transaction identifier (transaction_id).

Below is an example showing a rejected attempt followed by an 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