URL de Confirmação

A PayU utiliza esta URL para enviar uma requisição HTTP POST assíncrona diretamente para o seu servidor assim que uma transação atinge um estado final (Aprovada, Rejeitada ou Recusada). Como este processo ocorre em segundo plano, ele permanece invisível para o cliente. Portanto, enquanto a URL de Resposta gerencia a experiência do cliente, a URL de Confirmação gerencia a comunicação de backend entre a PayU e o seu servidor.

Diretrizes de Implementação

• Atualizações Automáticas: Utilize este mecanismo para disparar fluxos de trabalho automatizados, como atualizar bancos de dados, ajustar níveis de estoque e finalizar status de pedidos.

• Tratamento de Reentativas: A PayU gera uma confirmação exclusiva para cada tentativa de transação. Se um pagador tentar refazer um pagamento, seu sistema receberá uma notificação para cada resultado individual, independentemente do desfecho.

• Requisitos de Formato: Como esta URL serve puramente para transmissão de dados, seu endpoint não deve retornar código HTML ou elementos visuais.

• Lógica do Lado do Servidor: Você deve implementar a lógica do lado do servidor na sua linguagem de programação de preferência para capturar, analisar (parse) e processar as variáveis transmitidas pela PayU.

Métodos de Integração

Dependendo do seu tipo de integração, use os seguintes parâmetros para definir seu endpoint de webhook:

Considerações

• Acessibilidade Pública: A URL deve ser pública. Evite localhosts ou intranets internas.

• Desabilitar Autenticação: Certifique-se de que o endpoint não exija Basic Auth ou qualquer medida de segurança que bloqueie a requisição POST automatizada da PayU.

• Certificados SSL/TLS: Se você estiver usando HTTPS para sua URL de Confirmação, deverá utilizar um certificado SSL/TLS válido. Não utilize certificados de segurança de curva elíptica ou aqueles com a suíte de criptografia TLS_ECDHE_ECDSA_WITH_RC4_128_SHA.

• Tipo de Conteúdo (Content Type): Seu servidor deve estar configurado para processar dados no formato x-www-form-urlencoded.

• Relatório de Status Final da Transação: A PayU acionará a URL de Confirmação apenas quando uma transação atingir um status final (ex: aprovada, rejeitada ou expirada). Você não receberá relatórios de transações que ainda estão em andamento (aguardando pagamento ou em análise).

• Sem Saída HTML: Como esta é uma chamada de sistema para sistema, seu script deve processar a lógica e retornar um status HTTP 200 OK padrão, sem renderizar código HTML.

Lista de IPs Permitidos (Whitelist) para Servidores PayU

Para garantir que seu servidor receba as requisições e notificações da PayU Latam, é necessário incluir nossos endereços IP na lista de permissões. Isso é especialmente importante se o seu servidor estiver protegido por um firewall. Todas as requisições de webhook e comunicações dos servidores PayU originarão dos endereços IP listados abaixo.

Ambiente de Produção

• 34.233.144.154
• 184.73.94.138
• 52.73.124.136

Ambiente de Sandbox

• 54.158.171.129

Parâmetros POST

A PayU transmite uma ampla gama de parâmetros para o seu servidor.

Considerações Importantes

• Payloads Dinâmicos: A PayU ajusta o payload dinamicamente com base no método de pagamento utilizado. Por exemplo, a PayU envia cc_number, cc_holder e cardType para transações com cartão de crédito, mas os exclui para pagamentos em dinheiro ou transferências bancárias.

• Tratamento de Erros: Sua integração deve lidar com chaves opcionais ou ausentes para evitar erros de script quando variáveis específicas estiverem ausentes na requisição POST.

• Variáveis Configuráveis: Para incluir dados estendidos — como cardType, transaction_type, bank_reference_code, payment_method_id, expiration_date ou adminFee — entre em contato com seu representante PayU. Esses parâmetros não são enviados por padrão e devem ser habilitados especificamente para sua conta.

Exemplo de Requisição POST para a URL de Confirmação

O exemplo a seguir mostra como nosso sistema envia parâmetros para sua URL de Confirmação usando uma requisição HTTP 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=

Exemplo de Implementação (PHP)

Este script captura os dados POST enviados pela PayU (compatível com notificações de WebCheckout e API):

<?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';

Validação de Assinatura (Signature)

Para garantir a integridade dos dados e verificar se a notificação foi originada pela PayU, você deve gerar uma assinatura em seu servidor e compará-la com o parâmetro sign enviado na requisição HTTP POST.

Regras de Arredondamento para Webhooks

O arredondamento para o campo value em webhooks segue estas regras específicas para a string de assinatura:

• Se a segunda casa decimal do value for zero, formate o new_value usando uma casa decimal (ex: 150.00 torna-se 150.0).
• Se a segunda casa decimal não for zero, mantenha duas casas decimais no new_value (ex: 150.25 permanece 150.25).

Formato da Assinatura

Sempre use os valores da URL de Confirmação (merchant_id, reference_sale, value, currency e state_pol) para gerar a assinatura. Não use valores do seu próprio banco de dados.

A string para o hash é:

apiKey~merchant_id~reference_sale~new_value~currency~state_pol

Exemplos de Assinatura

Os exemplos a seguir ilustram como gerar uma assinatura, neste caso, usando HMAC-SHA256.

Assinatura com uma Casa Decimal

Use este exemplo quando a segunda casa decimal do value for 0. Neste caso, formate o valor com apenas uma casa decimal.

Assinatura com duas Casas Decimais

Use o exemplo a seguir quando a segunda casa decimal do value não for 0. Formate o valor com duas casas decimais.

Valide sua Assinatura

Use este gerador para criar uma assinatura com qualquer um dos métodos de criptografia disponíveis. Esta funcionalidade auxilia na verificação do valor sign que a PayU envia para sua URL de Confirmação.

Reentativas de Pagamento

Se uma transação for rejeitada, o pagador pode tentar novamente usando um método diferente. A PayU envia uma confirmação para cada tentativa.

• Cada tentativa compartilha a mesma referência de pagamento (reference_sale) e identificador de pedido (reference_pol).
• Cada tentativa possui um identificador de transação exclusivo (transaction_id).

Abaixo está um exemplo mostrando uma tentativa rejeitada seguida por uma reentativa aprovada:

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