Webhooks

A EvoPay envia uma notificação HTTP POST para a callbackUrl informada na criação da transação sempre que o status é atualizado.

Configuração

A callbackUrl é opcional e informada nos endpoints de criação:

POST /v1/pix/ — campo callbackUrl
POST /v1/withdraw/ — campo callbackUrl
POST /v1/withdraw/qrcode — campo callbackUrl

Seu servidor deve responder com qualquer status HTTP 2xx para confirmar o recebimento.

Política de entrega

Parâmetro	Valor
Tentativas máximas	5
Backoff	Exponencial, base 2 minutos + 50% de jitter
Timeout por tentativa	10 segundos

Após 5 falhas consecutivas o reenvio para. Use Reenvio de callbacks em lote ou Reenvio de callback por transação para reenviar manualmente.

Headers enviados

Content-Type: application/json
User-Agent: Callback-Service/1.0
X-Callback-Attempt: <n>

X-Callback-Attempt começa em 0 na primeira tentativa e vai até 4 na quinta.

Payload

DEPOSIT e WITHDRAW recebem o mesmo schema. Os campos null variam conforme o status e o tipo da transação.

{
  "id": "EPB1694C2C35E94053874D53B1",
  "type": "DEPOSIT",
  "status": "COMPLETED",
  "amount": 100.00,
  "serviceFeeCharged": 2.50,
  "clientReference": "pedido-123",

  "qrCodeText": "00020101...",
  "qrCodeUrl": "https://...",
  "qrCodeBase64": "iVBORw0KGgo...",

  "generatedName": "João Silva",
  "generatedDocument": "12345678901",
  "generatedEmail": "joao@email.com",

  "payerName": "João Silva",
  "payerDocument": "12345678901",
  "payerInstitutionIspb": "60746948",
  "payerInstitutionName": "Itaú",

  "receiverName": null,
  "receiverDocument": null,
  "receiverInstitutionIspb": null,
  "receiverInstitutionName": null,

  "withdrawPixKey": null,
  "withdrawPixType": null,
  "withdrawQrCodeText": null,

  "endToEndId": "E60746948...",
  "cancellationReason": null,
  "paidAt": "2024-01-01T12:05:00.000Z",

  "refundEndToEndId": null,
  "refundAmount": null,
  "refundStatus": null,
  "refundReason": null,
  "refundDescription": null,
  "refundedAt": null,

  "createdAt": "2024-01-01T12:00:00.000Z",
  "updatedAt": "2024-01-01T12:05:00.000Z"
}

Campos principais

Campo	Tipo	Descrição
`id`	`string`	ID da transação
`type`	`TransactionType`	`DEPOSIT` ou `WITHDRAW`
`status`	`TransactionStatus`	Status atual
`amount`	`number`	Valor em reais
`serviceFeeCharged`	`number \| null`	Taxa cobrada
`clientReference`	`string \| null`	Referência externa enviada na criação
`cancellationReason`	`string \| null`	Motivo do cancelamento
`endToEndId`	`string \| null`	ID fim a fim Pix
`paidAt`	`string \| null`	Timestamp do pagamento (ISO 8601)

Campos típicos por tipo

Campo	DEPOSIT	WITHDRAW
`qrCodeText / qrCodeUrl / qrCodeBase64`	Preenchido	`null`
`generatedName / generatedDocument / generatedEmail`	Preenchido se informado na criação	`null`
`payerName / payerDocument / payerInstitutionIspb / payerInstitutionName`	Fornecido pelo provedor quando disponível	Fornecido pelo provedor quando disponível
`receiverName / receiverDocument / receiverInstitutionIspb / receiverInstitutionName`	`null`	Preenchido após liquidação
`withdrawPixKey / withdrawPixType`	`null`	Preenchido (saque via chave)
`withdrawQrCodeText`	`null`	Preenchido (saque via QR Code)

Campos de estorno

Preenchidos quando status é WAITING_FOR_REFUND ou REFUNDED.

Campo	Tipo	Descrição
`refundStatus`	`RefundStatus` \| null	Status do estorno
`refundReason`	`RefundReason` \| null	Motivo do estorno
`refundAmount`	`number \| null`	Valor estornado
`refundEndToEndId`	`string \| null`	ID fim a fim do estorno
`refundDescription`	`string \| null`	Descrição livre
`refundedAt`	`string \| null`	Timestamp do estorno (ISO 8601)

Campo `infraction` (opcional)

Presente apenas quando o webhook é disparado por uma atualização de infração Pix associada à transação. Em callbacks normais de depósito e saque, este campo não aparece no payload.

{
  "id": "EPB1694C2C35E94053874D53B1",
  "type": "DEPOSIT",
  "status": "WAITING_FOR_REFUND",
  ...
  "infraction": {
    "id": "uuid",
    "protocol": "PROTOCOL123",
    "status": "OPEN",
    "type": "FRAUD",
    "reportDetails": "Transação não reconhecida pelo pagador",
    "reportedBy": "DEBITED_PARTICIPANT",
    "analysisResult": null,
    "analysisDetails": null,
    "reportedAt": "2024-01-01T13:00:00.000Z",
    "expiresAt": "2024-02-01T13:00:00.000Z",
    "createdAt": "2024-01-01T13:00:00.000Z",
    "updatedAt": "2024-01-01T13:00:00.000Z"
  }
}

Campo	Tipo	Descrição
`id`	`string`	ID da infração
`protocol`	`string`	Protocolo fornecido pelo provedor
`status`	`InfractionStatus`	Status da infração
`type`	`InfractionType`	Tipo da infração
`reportDetails`	`string`	Descrição do motivo
`reportedBy`	`ReportedType`	Quem reportou
`analysisResult`	`AnalysisResult` \| null	Resultado da análise
`analysisDetails`	`string \| null`	Justificativa da decisão
`reportedAt`	`string`	Timestamp do reporte (ISO 8601)
`expiresAt`	`string \| null`	Prazo de resolução (ISO 8601)
`createdAt`	`string`	Timestamp de criação (ISO 8601)
`updatedAt`	`string`	Timestamp da última atualização (ISO 8601)