Confirmando pagamento via Webhook

Pagamentos na Barte podem ocorrer de forma síncrona ou assíncrona, dependendo do método de pagamento. Independentemente do método utilizado, a confirmação oficial de qualquer pagamento deve ser feita via webhook.

Webhooks garantem que seu sistema seja notificado sempre que uma transação sofrer alteração de status, permitindo manter seus pedidos sincronizados com a Barte.

---

Quando usar este fluxo?

Este fluxo deve ser utilizado quando:

• O pagamento for via PIX ou boleto (pagamentos assíncronos)

• O pagamento for via cartão de crédito, mesmo com retorno síncrono

• Seu sistema precisar reagir automaticamente a mudanças de status

• Você quiser garantir consistência em casos de estorno, cancelamento ou disputa

---

Como funciona a confirmação de pagamento

Pedido criado
     ↓
Pagamento iniciado
     ↓
Status da transação muda na Barte
     ↓
Webhook é enviado para seu sistema
     ↓
Seu sistema valida o evento
     ↓
Pedido é atualizado automaticamente

---

Pagamentos via cartão também disparam webhooks

Pagamentos via cartão de crédito normalmente retornam um status imediato no momento da criação da transação. Ainda assim, a Barte dispara webhooks para pagamentos com cartão sempre que houver qualquer alteração de status.

Isso inclui:

• Confirmação final do pagamento

• Atualizações pós-processamento

• Cancelamentos

• Estornos

• Disputas e chargebacks

💡 Recomendação: utilize sempre o webhook como fonte de verdade, inclusive para pagamentos com cartão.

---

Recebendo o webhook

Sempre que uma transação sofre alteração de status, a Barte envia uma requisição HTTP POST para a URL configurada no webhook.

O payload enviado contém as informações necessárias para identificar:

• O pedido

• O tipo de evento

• O status atual da transação

Você pode verificar mais detalhes sobre os payloads dos Webhooks aqui:

• Campos dos Webhooks

• Pedidos (Orders) e Assinaturas (Subscriptions)

• Pedidos Físicos (Maquininhas)

• Disputas e Chargebacks

---

Confirmando o pagamento corretamente

Ao receber um webhook, seu sistema deve seguir as etapas abaixo:

1. Identificar o pedido

   • Utilize o identificador do pedido (uuid) enviado no payload.

2. Validar o status da transação

   • Verifique se o status recebido representa pagamento confirmado.

3. Atualizar o pedido no seu sistema

   • Marque o pedido como pago.

   • Libere o produto, serviço ou acesso.

4. Retornar HTTP 200

   • Indica que o webhook foi processado com sucesso.

---

Reenvio de webhooks e idempotência

Caso seu sistema:

• Retorne erro

• Não responda

• Esteja indisponível

A Barte poderá reenviar o webhook.

Por isso, seu endpoint deve ser idempotente, ou seja, capaz de processar o mesmo evento mais de uma vez sem gerar duplicidade ou inconsistência.

---

Boas práticas

• Utilize webhooks como fonte principal de atualização

• Processe eventos de forma assíncrona

• Registre logs do payload recebido

• Evite lógica complexa no endpoint de webhook

• Garanta que a mesma transação não seja processada duas vezes

---

O que não fazer

• Confirmar pagamento sem webhook

• Depender apenas do retorno síncrono do cartão

• Ignorar eventos de cancelamento, estorno ou disputa

---

Observação final

Para todos os métodos de pagamento, o webhook é o meio oficial de confirmação e atualização de status das transações na Barte, embora transações no cartão de crédito tragam uma confirmação síncrona.