# 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.

***

### <i class="fa-thumbtack-angle">:thumbtack-angle:</i> 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

***

### <i class="fa-rotate">:rotate:</i> 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
```

***

### <i class="fa-credit-card">:credit-card:</i> 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.

***

### <i class="fa-download">:download:</i> 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](/guias/webhooks/campos-dos-webhooks.md)
* [Pedidos (Orders) e Assinaturas (Subscriptions)](/guias/webhooks/pedidos-orders-e-assinaturas-subscriptions.md)
* [Pedidos Físicos (Maquininhas)](/guias/webhooks/pedidos-fisicos-maquininhas.md)
* [Disputas e Chargebacks](/guias/webhooks/disputas-e-chargebacks.md)

***

### <i class="fa-check">:check:</i> 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.

***

### <i class="fa-arrow-right-arrow-left">:arrow-right-arrow-left:</i> 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.

***

### <i class="fa-lightbulb">:lightbulb:</i> 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

***

### <i class="fa-hexagon-xmark">:hexagon-xmark:</i> 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

***

#### <i class="fa-exclamation">:exclamation:</i>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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.barte.com/guias/passo-a-passo-do-vendedor/3o-pos-pagamento/confirmando-pagamento-via-webhook.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.