Webhook de Depósito

Webhooks são notificações automáticas que a API envia quando um evento do depósito acontece.

Esta página segue o mesmo contrato estrutural do webhook de transação. O que muda é o prefixo do evento e o valor do campo data.type.

Se você trabalha com transações, veja Webhook de Transação.

Eventos suportados

Evento	Quando é enviado
DEPOSIT_CREATED	Quando o depósito é criado
DEPOSIT_PAID	Quando o depósito é pago
DEPOSIT_INFRACTION	Quando o depósito entra em infração
DEPOSIT_REFUNDED	Quando o depósito é estornado

Formato do payload

Campo	Tipo	Obrigatório	Descrição
type	string (enum) - DEPOSIT_CREATED, DEPOSIT_PAID, DEPOSIT_INFRACTION, DEPOSIT_REFUNDED	Sim	Tipo do evento enviado no webhook
data	object	Sim	Dados do depósito

O campo type na raiz identifica o evento. Dentro de data, o campo type identifica a operação da entidade.

Payload base

Esses campos estão presentes em todos os webhooks de depósito.

Campo	Tipo	Obrigatório	Descrição
id	string (UUID)	Sim	Identificador único do depósito
amount	number	Sim	Valor do depósito, em centavos
paymentMethod	string (enum) - PIX	Sim	Método de pagamento
externalCode	string	Sim	Código de referência externo enviado pela integração
isInfoProduct	boolean	Sim	Indica se o depósito é de produto digital
createdAt	string (ISO)	Sim	Data de criação
status	string (enum) - PENDING, PIX_QRCODE_GENERATED, PAID, PROCESSING_REFUND, PROCESSING_INFRACTION, REFUNDED, INFRACTION, FAILED, BLOCKED	Sim	PENDING: depósito criado, aguardando processamento PIX_QRCODE_GENERATED: QRCode PIX gerado, aguardando pagamento PAID: depósito pago PROCESSING_REFUND: estorno em processamento PROCESSING_INFRACTION: infração em processamento REFUNDED: depósito estornado INFRACTION: depósito estornado (MED) FAILED: erro no processamento BLOCKED: bloqueado devido à abertura de MED
type	string (enum) - DEPOSIT	Sim	Tipo da operação

Variações por evento

DEPOSIT_CREATED

Usa apenas o payload base.

DEPOSIT_PAID

Além do payload base, adiciona:

Campo	Tipo	Obrigatório	Descrição
endToEnd	string	Não	Identificador end-to-end do depósito
amountPaid	number	Sim	Valor efetivamente pago
paymentDate	string (ISO)	Não	Data do pagamento
payer	object	Não	Dados do pagador (ver Sub-Objetos AccountHolder)
paymentReceipt	string	Não	URL do comprovante de pagamento

DEPOSIT_INFRACTION

Além do payload base, adiciona:

Campo	Tipo	Obrigatório	Descrição
endToEnd	string	Não	Identificador end-to-end do depósito
infractionAmount	number	Sim	Valor da infração
infractionDate	string (ISO)	Não	Data da infração

DEPOSIT_REFUNDED

Além do payload base, adiciona:

Campo	Tipo	Obrigatório	Descrição
endToEnd	string	Não	Identificador end-to-end do depósito
refundAmount	number	Sim	Valor do estorno
refundDate	string (ISO)	Não	Data do estorno
endToEndRefund	string	Não	Identificador end-to-end do estorno
refundReceipt	string	Não	URL do comprovante de estorno

Sub-Objetos

AccountHolder

Campo	Tipo	Obrigatório	Descrição
type	string (enum) - PF, PJ	Sim	Tipo do titular
name	string	Sim	Nome do titular
document	string	Sim	Documento do titular
bankAccount	object	Sim	Dados bancários (ver Sub-Objeto BankAccount)
pix	object	Sim	Chave PIX do titular (ver Sub-Objeto PixKeyVo)

BankAccount

Campo	Tipo	Obrigatório	Descrição
type	string	Sim	Tipo de conta
digit	string	Sim	Dígito da conta
ispb	string	Sim	ISPB do banco

PixKeyVo

Campo	Tipo	Obrigatório	Descrição
key	string	Sim	Chave PIX
type	string	Sim	Tipo da chave PIX

Exemplo de payload

Dados mascarados

Valores sensíveis podem estar mascarados com ***.

{
  "type": "DEPOSIT_PAID",
  "data": {
    "id": "553e8400-e29b-41d4-a716-436251480000",
    "amount": 10000,
    "paymentMethod": "PIX",
    "externalCode": "DEPOSIT-123",
    "isInfoProduct": true,
    "createdAt": "2026-03-06T12:49:04.681Z",
    "status": "PAID",
    "type": "DEPOSIT",
    "endToEnd": "E2E123456789",
    "amountPaid": 10000,
    "paymentDate": "2026-03-06T12:49:04.681Z",
    "paymentReceipt": "https://files.exemplo.com.br/receipts/deposit-553e8400-e29b-41d4-a716-436251480000.pdf",
    "payer": {
      "type": "PF",
      "name": "Fulano de Tal",
      "document": "***456789**",
      "bankAccount": {
        "type": "CHECKING",
        "digit": "7",
        "ispb": "12345678"
      },
      "pix": {
        "key": "12345678910",
        "type": "CPF"
      }
    }
  }
}