Como Integrar Pagamentos UPI em Tempo Real no WooCommerce

Oferecer métodos de pagamento instantâneos é um requisito essencial para taxas de conversão elevadas em mercados que utilizam o UPI (Unified Payments Interface). Em uma loja virtual construída com WooCommerce, processar transferências UPI em tempo real exige mais do que um simples redirecionamento: requer validação síncrona ou assíncrona orientada a eventos, geração dinâmica de QR Code e suporte a links de intenção (UPI Intent) para dispositivos móveis.

Neste artigo, você entenderá como funciona a arquitetura técnica para integrar pagamentos UPI no ecossistema WooCommerce de forma segura e automatizada.

### O Desafio dos Pagamentos UPI no Checkout

Diferente dos cartões de crédito convencionais, nos quais o gateway processa a autorização imediatamente por meio de uma requisição síncrona de API, o fluxo UPI opera frequentemente com duas frentes:

1. Desktop: O cliente visualiza um QR Code dinâmico com o valor exato do pedido e a chave VPA (Virtual Payment Address) do lojista, escaneando o código através do aplicativo bancário no smartphone.
2. Dispositivos Móveis: O checkout dispara um esquema de URL específico (upi://pay), abrindo diretamente o aplicativo bancário ou de carteira digital do usuário (Google Pay, PhonePe, Paytm).

O principal desafio técnico reside na confirmação do pagamento: o WooCommerce precisa receber a confirmação de liquidação em tempo real para alterar o status do pedido de pendente (pending payment) para processando (processing), sem depender de intervenção manual.

### Arquitetura de Implementação no WooCommerce

Para estruturar essa solução no WordPress, existem duas abordagens principais: utilizar SDKs de intermediadores locais (como Razorpay, Cashfree ou Stripe Índia) ou desenvolver uma extensão personalizada da classe nativa do WooCommerce.

Em implementações que realizo para lojas com necessidades específicas de checkout customizado, a extensão direta da classe abstrata WC_Payment_Gateway permite controlar com exatidão a interface do usuário e a resposta dos webhooks.

#### 1. Estruturação da Classe do Gateway

O ponto de partida é criar uma classe que estenda WC_Payment_Gateway, declarando o suporte a moedas suportadas (como INR) e implementando o método process_payment($order_id):

php
class WCGatewayUPIRealtime extends WCPayment_Gateway {
public function _construct() {
$this->id = ‘upirealtime’;
$this->methodtitle = ‘UPI Instantâneo’;
$this->hasfields = false;
$this->initformfields();
$this->init_settings();

    add_action('woocommerce_api_wc_gateway_upi_realtime', array($this, 'check_ipn_response'));
}

public function process_payment($order_id) {
    $order = wc_get_order($order_id);

    // Gera o payload do QR Code dinâmico ou link de intenção
    $upi_payload = $this->generate_upi_payload($order);

    return array(
        'result'   => 'success',
        'redirect' => $order->get_checkout_payment_url(true)
    );
}

}

#### 2. Confirmação em Tempo Real via Webhook

Para evitar falhas causadas por queda de conexão no dispositivo do usuário após o pagamento, a atualização do pedido não deve depender do redirecionamento do navegador. O webhook da instituição financeira deve comunicar diretamente com a API do WooCommerce através da action woocommerce_api_{gateway_id}.

No manipulador de callback, valida-se a assinatura criptográfica da notificação (HMAC-SHA256) antes de alterar o estado do pedido:

php
public function checkipnresponse() {
$payload = filegetcontents(‘php://input’);
$signature = $SERVER[‘HTTPXGATEWAYSIGNATURE’] ?? ”;

if (!$this->validate_signature($payload, $signature)) {
    wp_die('Assinatura inválida', 'Erro', array('response' => 403));
}

$data = json_decode($payload, true);
$order = wc_get_order($data['order_id']);

if ($order && $data['status'] === 'SUCCESS') {
    $order->payment_complete($data['transaction_id']);
    $order->add_order_note('Pagamento UPI confirmado via webhook em tempo real.');
}

wp_send_json_success();

}

#### 3. Polling e Experiência do Usuário na Página de Pagamento

Enquanto a transação é processada no smartphone do cliente, a página de confirmação na loja precisa atualizar automaticamente. Uma rotina JavaScript simples em frontend consulta periodicamente um endpoint REST customizado (/wp-json/loja/v1/order-status/{id}). Assim que o webhook processa o pagamento no backend, o script redireciona o cliente para a página de obrigado (order-received), oferecendo feedback imediato sem exigir recarga manual.

### Boas Práticas para Transações Críticas

– Expiração de Pedidos: Configure um tempo limite razoável (ex: 15 minutos) para cancelamento automático de pedidos pendentes via Action Scheduler, liberando o estoque caso a transação UPI seja abandonada.
– Logs de Auditoria: Utilize wc_get_logger() para registrar entradas de webhooks, respostas de APIs e discrepâncias de valor para facilitar a conciliação financeira.
– Idempotência: Garanta que notificações duplicadas do webhook não resultem em transições incorretas de status ou duplicação de e-mails de confirmação.

### Conclusão

Integrar UPI no WooCommerce de forma nativa e em tempo real eleva o padrão de usabilidade e reduz custos de abandono de carrinho. Se você busca implementar uma solução personalizada de pagamentos instantâneos com arquitetura resiliente no seu e-commerce, entre em contato para avaliar a viabilidade técnica do seu projeto.