Skip to main content

​
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

{
  "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, 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

{
  "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

medStatusQuando ocorre
DEFENSE_SUBMITTEDDefesa entregue ao PSP com sucesso (logo após o PATCH /med-contest/exposes/{medId}).
APPROVEDPSP aceitou a defesa — valor permanece com o parceiro.
REJECTEDPSP rejeitou a defesa — estorno realizado em favor do reclamante.
REFUNDEDEstorno efetivamente devolvido ao reclamante (pode chegar junto ou após REJECTED).
CANCELLEDMED 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.

Guia completo: Segurança dos Webhooks

Headers de segurança, fórmula da assinatura e exemplos de validação (Node.js, Python, PHP).

​
Boas Práticas

1
Valide a assinatura HMAC (X-Webhook-Signature) antes de processar — veja Segurança dos Webhooks
2
Confirme o recebimento do webhook com uma resposta 200 OK
3
Implemente verificações de idempotência usando o transactionId e externalId
4
Processe webhooks de forma assíncrona
5
Mantenha logs dos webhooks recebidos para resolução de problemas
6
Implemente lógica de retry para entregas de webhook falhas

​
O Webhook deve retornar Status Code 200

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

​
Consulta de Comprovante

​
Endpoint

GET /transaction/{transactionId}/receipt

​
Parâmetros do Path

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

​
Exemplo de Requisição

GET /transaction/b6e0ee4e-b3a3-4042-ac4d-fba92ebd96a5/receipt

​
Resposta de Sucesso

  • Status Code: 200 OK
{
    "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