> ## Documentation Index
> Fetch the complete documentation index at: https://docs.3xpay.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook de Infração

> Documentação completa das notificações do webhook para infrações em transações

# Documentação do Webhook de Infração

## Visão Geral

Nosso sistema de webhook envia notificações em tempo real sobre infrações detectadas em transações. Quando uma infração é identificada, uma requisição POST é enviada para a URL configurada com informações detalhadas da ocorrência.

## Payload do Webhook

O webhook envia um payload JSON contendo os detalhes da infração e da transação relacionada.

### Exemplo de Payload

```json theme={null}
{
  "transactionId": "5a94d48d-c9f3-46be-8448-83510ca42bde",
  "transactionStatus": "MED",
  "transactionType": "CASH_IN",
  "value": "18",
  "externalId": "T&ste378",
  "e2e_id": "E082535392025011818245238600338f",
  "medStatus": "ACKNOWLEDGED"
}
```

### Descrição dos Campos

#### Informações da Transação

* `transactionId` (string): Identificador único da transação no formato UUID
* `transactionStatus` (string): Status atual da transação. Valores possíveis:
  * `MED`: Transação solicitada MED
* `transactionType` (string): Tipo da transação, neste caso "CASH\_IN"
* `value` (string): Valor da transação
* `externalId` (string): ID de referência externa fornecido pelo cliente
* `medStatus` (string): Status do MED. Valores possíveis:
  * `ACKNOWLEDGED`: Quando a solicitação do MED é recebida
  * `CANCELLED`: Quando o MED é cancelado e o valor estornado para conta
  * `DEBITED`: Quando a defesa do MED não é aceita e o valor enviado para o cliente.

## Resolução da disputa (após envio da defesa)

Quando o parceiro responde à solicitação de MED via [API de Disputa de MED](/api-reference/endpoint/med-contest-create), o resultado final do PSP é entregue por este mesmo webhook. O payload inclui o `externalId` original e o `e2e_id` da transação.

### Exemplo de Payload

```json theme={null}
{
  "transactionId": "01a51b3e-e17d-45eb-b8a2-e2392b6b1b28",
  "transactionStatus": "MED",
  "transactionType": "CASH_IN",
  "value": "18",
  "externalId": "PARTNER-REF-001",
  "e2e_id": "E35...20260510...",
  "medStatus": "APPROVED"
}
```

### Valores de `medStatus` após a defesa

| medStatus           | Quando ocorre                                                                          |
| ------------------- | -------------------------------------------------------------------------------------- |
| `DEFENSE_SUBMITTED` | Defesa entregue ao PSP com sucesso (logo após o `PATCH /med-contest/exposes/{medId}`). |
| `APPROVED`          | PSP aceitou a defesa — valor permanece com o parceiro.                                 |
| `REJECTED`          | PSP rejeitou a defesa — estorno realizado em favor do reclamante.                      |
| `REFUNDED`          | Estorno efetivamente devolvido ao reclamante (pode chegar junto ou após `REJECTED`).   |
| `CANCELLED`         | MED cancelado — o valor é estornado para a conta do parceiro.                          |

## Segurança: Verificação de Assinatura

Toda requisição deste webhook é assinada com **HMAC-SHA256** (header
`X-Webhook-Signature`), usando o seu `api_secret` como chave. **Valide a assinatura
antes de processar o payload** para garantir que a notificação veio realmente da
3X Pay e não foi adulterada no caminho.

<Card title="Guia completo: Segurança dos Webhooks" icon="shield-check" href="/api-reference/webhook/webhook-seguranca">
  Headers de segurança, fórmula da assinatura e exemplos de validação (Node.js, Python, PHP).
</Card>

## Boas Práticas

<Steps>
  Valide a assinatura HMAC (`X-Webhook-Signature`) antes de processar — veja [Segurança dos Webhooks](/api-reference/webhook/webhook-seguranca)

  Confirme o recebimento do webhook com uma resposta 200 OK

  Implemente verificações de idempotência usando o `transactionId` e `externalId`

  Processe webhooks de forma assíncrona

  Mantenha logs dos webhooks recebidos para resolução de problemas

  Implemente lógica de retry para entregas de webhook falhas
</Steps>

## O Webhook deve retornar Status Code 200

<Warning>
  Para que a transação tenha seu fluxo finalizado com sucesso é de extrema importância que seja retornado 200 na resposta!
</Warning>

## Consulta de Comprovante

### Endpoint

```http theme={null}
GET /transaction/{transactionId}/receipt
```

### Parâmetros do Path

* `transactionId` (string): Identificador único da transação no formato UUID

### Exemplo de Requisição

```http theme={null}
GET /transaction/b6e0ee4e-b3a3-4042-ac4d-fba92ebd96a5/receipt
```

### Resposta de Sucesso

* **Status Code:** 200 OK

```json theme={null}
{
    "status": "SUCCESS",
    "data": {
        "receipt": "JVBERi0xLjMKJf.....", // String em base64 do arquivo PDF
        "mimeType": "application/pdf"
    }
}
```

### Descrição dos Campos da Resposta

* `status` (string): Status da requisição
* `data` (object): Objeto contendo os dados do comprovante
  * `receipt` (string): Conteúdo do comprovante em formato base64
  * `mimeType` (string): Tipo do arquivo do comprovante (application/pdf)

### Observações

* O campo `receipt` contém o arquivo PDF codificado em base64
* Para visualizar o comprovante, é necessário decodificar o conteúdo base64 para PDF

export default function MDXPage({children}) {
  return <div className="docs-container">{children}</div>;
}