⌘K

Exemplos de Teste de Webhook

Esses payloads simulam o que a Versell envia para seu endpoint de webhook. Use-os para desenvolvimento e testes locais.

Cash In — Pix Recebido

Este payload é enviado quando um Pix é recebido na sua chave. Ele chega no endpoint de webhook que você configurou para Cash In.

{
  "data": {
    "id": 825099,
    "txId": "0e7a2986324d6a9644cb6bf3458286",
    "pixKey": "33aba435-7926-42ef-aa81-fbbe90dd0f6f",
    "status": "LIQUIDATED",
    "payment": {
      "amount": "25.00",
      "currency": "BRL"
    },
    "refunds": [],
    "createdAt": "2026-04-08T19: 13: 43.290+00: 00",
    "errorCode": null,
    "endToEndId": "E0036030520260408191371b6dafecba",
    "ticketData": {},
    "webhookType": "RECEIVE",
    "debtorAccount": {
      "ispb": "00360305",
      "name": "MARCELO GOMES DOS PASSOS",
      "issuer": "0000",
      "number": "0000",
      "document": "35504589835",
      "accountType": "SVGS"
    },
    "idempotencyKey": null,
    "creditDebitType": "CREDIT",
    "creditorAccount": {
      "ispb": "37293930",
      "name": "VERSELL TECHNOLOGY LTDA",
      "issuer": "0000",
      "number": "0000",
      "document": "38322428000123",
      "accountType": "TRAN"
    },
    "localInstrument": "QRDN",
    "transactionType": "PIX",
    "remittanceInformation": null
  },
  "type": "RECEIVE"
}

Campo	Tipo	Descrição
type	string	Tipo do webhook — "RECEIVE" para Pix recebido
data.id	number	ID interno da transação na Versell
data.txId	string	Identificador da cobrança (definido na criação do QR Code)
data.pixKey	string	Chave Pix que recebeu o pagamento
data.status	string	Status da transação — "LIQUIDATED" indica pagamento confirmado
data.payment.amount	string	Valor do Pix em reais (formato decimal com ponto)
data.payment.currency	string	Moeda da transação (BRL)
data.endToEndId	string	Identificador único da transação no Banco Central
data.webhookType	string	Tipo do evento — "RECEIVE" para recebimento
data.debtorAccount	object	Dados da conta do pagador (nome, documento, ISPB, tipo de conta)
data.creditorAccount	object	Dados da conta recebedora (nome, documento, ISPB, tipo de conta)
data.localInstrument	string	Instrumento de pagamento — QRDN (QR Code dinâmico), QRES (QR Code estático), DICT (chave), MANU (manual)
data.createdAt	string (ISO 8601)	Data e hora em que o Pix foi recebido
data.refunds	array	Lista de devoluções associadas a esta transação (vazia se não houver)

Cash Out — Transferência Liquidada

Enviado quando uma transferência Pix de saída é liquidada com sucesso.

{
  "data": {
    "id": 825100,
    "txId": null,
    "pixKey": null,
    "status": "LIQUIDATED",
    "payment": {
      "amount": "250.00",
      "currency": "BRL"
    },
    "endToEndId": "E12345678202301011234abcdef12345",
    "webhookType": "TRANSFER",
    "debtorAccount": {
      "ispb": "37293930",
      "name": "VERSELL TECHNOLOGY LTDA",
      "issuer": "0000",
      "number": "0000",
      "document": "38322428000123",
      "accountType": "TRAN"
    },
    "creditorAccount": {
      "ispb": "00360305",
      "name": "JOHN DOE",
      "issuer": "0001",
      "number": "12345678",
      "document": "12345678900",
      "accountType": "CACC"
    },
    "creditDebitType": "DEBIT",
    "localInstrument": "DICT",
    "transactionType": "PIX",
    "createdAt": "2025-01-15T10: 35: 00.000Z"
  },
  "type": "TRANSFER"
}

Campo	Tipo	Descrição
type	string	Tipo do webhook — "TRANSFER" para transferência liquidada
data.id	number	ID interno da transação na Versell
data.status	string	Status da transferência — "LIQUIDATED" indica sucesso
data.payment.amount	string	Valor da transferência em reais (formato decimal com ponto)
data.endToEndId	string	Identificador único da transação no Banco Central
data.webhookType	string	Tipo do evento — "TRANSFER" para transferência
data.debtorAccount	object	Dados da conta de origem (nome, documento, ISPB, tipo de conta)
data.creditorAccount	object	Dados da conta de destino (nome, documento, ISPB, tipo de conta)
data.creditDebitType	string	Tipo da operação — "DEBIT" para saída de recursos
data.createdAt	string (ISO 8601)	Data e hora da criação da transferência

Cash Out — Transferência Rejeitada

Enviado quando uma transferência Pix de saída é rejeitada pelo PSP ou pelo Banco Central.

{
  "data": {
    "id": 825101,
    "txId": null,
    "pixKey": null,
    "status": "REJECTED",
    "payment": {
      "amount": "500.00",
      "currency": "BRL"
    },
    "endToEndId": "E98765432202301011234abcdef67890",
    "errorMessage": "Conta do destinatario encerrada",
    "webhookType": "CASHOUT",
    "debtorAccount": {
      "ispb": "37293930",
      "name": "VERSELL TECHNOLOGY LTDA",
      "issuer": "0000",
      "number": "0000",
      "document": "38322428000123",
      "accountType": "TRAN"
    },
    "creditorAccount": {
      "ispb": "00360305",
      "name": "JANE DOE",
      "issuer": "0001",
      "number": "87654321",
      "document": "98765432100",
      "accountType": "CACC"
    },
    "creditDebitType": "DEBIT",
    "localInstrument": "DICT",
    "transactionType": "PIX",
    "createdAt": "2025-01-15T11: 00: 00.000Z"
  },
  "type": "CASHOUT"
}

Campo	Tipo	Descrição
type	string	Tipo do webhook — "CASHOUT" para transferência rejeitada
data.id	number	ID interno da transação na Versell
data.status	string	Status da transferência — "REJECTED" indica rejeição
data.payment.amount	string	Valor da transferência em reais (formato decimal com ponto)
data.endToEndId	string	Identificador único da transação no Banco Central
data.errorMessage	string	Mensagem de erro descrevendo o motivo da rejeição
data.debtorAccount	object	Dados da conta de origem (nome, documento, ISPB, tipo de conta)
data.creditorAccount	object	Dados da conta de destino (nome, documento, ISPB, tipo de conta)
data.createdAt	string (ISO 8601)	Data e hora da criação da transferência

Devolução — Refund

Enviado quando uma devolução de Pix é processada com sucesso.

{
  "data": {
    "id": 825102,
    "txId": null,
    "pixKey": null,
    "status": "REFUNDED",
    "payment": {
      "amount": "100.00",
      "currency": "BRL"
    },
    "endToEndId": "E12345678202301011234abcdef99999",
    "webhookType": "REFUND",
    "debtorAccount": {
      "ispb": "00360305",
      "name": "JOHN DOE",
      "issuer": "0001",
      "number": "12345678",
      "document": "12345678900",
      "accountType": "CACC"
    },
    "creditorAccount": {
      "ispb": "37293930",
      "name": "VERSELL TECHNOLOGY LTDA",
      "issuer": "0000",
      "number": "0000",
      "document": "38322428000123",
      "accountType": "TRAN"
    },
    "creditDebitType": "CREDIT",
    "localInstrument": "DICT",
    "transactionType": "PIX",
    "createdAt": "2025-01-15T12: 00: 00.000Z"
  },
  "type": "REFUND"
}

Campo	Tipo	Descrição
type	string	Tipo do webhook — "REFUND" para devolução
data.id	number	ID interno da transação na Versell
data.status	string	Status da devolução — "REFUNDED" indica devolução concluída
data.payment.amount	string	Valor devolvido em reais (formato decimal com ponto)
data.endToEndId	string	Identificador único da transação no Banco Central
data.creditDebitType	string	Tipo da operação — "CREDIT" para entrada de recursos (devolução recebida)
data.createdAt	string (ISO 8601)	Data e hora da devolução

Infração / MED — Contestação de Pagamento

Este payload é enviado quando uma infração MED (Mecanismo Especial de Devolução) é aberta contra uma transação Pix recebida. Trate com prioridade pois exige resposta dentro do prazo do Banco Central.

{
  "data": {
    "id": "94adeefa-c487-4a68-b9be-7963b5f1b9d7",
    "type": "REFUND_REQUEST",
    "status": "WAITING_PSP",
    "endToEndId": "E60701190202604081701DY50PZW0MK6",
    "reportedBy": "DEBITED_PARTICIPANT",
    "creationDate": "2026-04-08T18: 56: 00.130+00: 00",
    "reportDetails": "Motivo da contestação informado pelo pagador...",
    "transactionId": "819568",
    "analysisResult": null,
    "analysisDetails": null,
    "transactionAmount": {
      "amount": 25,
      "currency": "BRL"
    },
    "lastModificationDate": "2026-04-08T18: 56: 00.143+00: 00"
  },
  "type": "INFRACTION"
}

Campo	Tipo	Descrição
type	string	Tipo do webhook — "INFRACTION" para infrações MED
data.id	string (UUID)	Identificador único da infração
data.type	string	Tipo da infração — "REFUND_REQUEST" para solicitação de devolução
data.status	string	Status da infração — WAITING_PSP (aguardando análise), CLOSED (encerrada), CANCELED (cancelada)
data.endToEndId	string	Identificador da transação original no Banco Central
data.reportedBy	string	Quem reportou — "DEBITED_PARTICIPANT" (banco do pagador)
data.reportDetails	string	Motivo da contestação informado pelo pagador
data.transactionId	string	ID da transação original na Versell
data.transactionAmount	object	Valor da transação contestada (amount em reais, currency em BRL)
data.creationDate	string (ISO 8601)	Data e hora de abertura da infração
data.analysisResult	string \| null	Resultado da análise (null enquanto aguarda, preenchido após análise)

Pix Automático — Recorrência

Enviado quando o status de uma recorrência do Pix Automático muda (ex: CRIADA, APROVADA). Chega via POST no seu endpoint configurado em /webhookrec, com o sufixo /rec adicionado à URL — POST {webhookUrl}/rec.

{
  "recs": [
    {
      "idRec": "RR1026652320260821lab77511abf",
      "status": "APROVADA",
      "atualizacao": [
        {
          "status": "CRIADA",
          "data": "2026-06-16T10: 12: 07.567Z"
        },
        {
          "status": "APROVADA",
          "data": "2026-06-18T12: 43: 53.337Z"
        }
      ],
      "ativacao": {
        "tipoJornada": "JORNADA_3",
        "dadosJornada": {
          "txid": "r9eFIFmwcZ55Nm4RsKZAAtIvvCrlcNN6"
        }
      }
    }
  ]
}

Campo	Tipo	Descrição
recs	array	Lista de recorrências que tiveram mudança de status
recs[].idRec	string	Identificador da recorrência
recs[].status	string	Status atual da recorrência (ex: APROVADA)
recs[].atualizacao	array	Histórico de mudanças de status com data e hora de cada transição
recs[].ativacao	object	Dados da jornada de ativação da recorrência (tipoJornada e dadosJornada, como o txid)

Pix Automático — Cobrança Recorrente

Enviado quando o status ou as tentativas de liquidação de uma cobrança recorrente mudam. Chega via POST no seu endpoint configurado em /webhookcobr, com o sufixo /cobr adicionado à URL — POST {webhookUrl}/cobr.

{
  "cobsr": [
    {
      "idRec": "RR1234567820260801abcdefghijk",
      "txid": "3136957d93134f2184b369e8f1c0729d",
      "status": "ATIVA",
      "atualizacao": [
        {
          "status": "ATIVA",
          "data": "2026-06-16T12: 34: 21.300Z"
        }
      ],
      "tentativas": [
        {
          "dataLiquidacao": "2026-06-20",
          "tipo": "AGND",
          "status": "SOLICITADA",
          "endToEndId": "E12345678202606201221abcdef12345"
        }
      ]
    }
  ]
}

Campo	Tipo	Descrição
cobsr	array	Lista de cobranças recorrentes que tiveram mudança de status ou tentativas
cobsr[].idRec	string	Identificador da recorrência associada à cobrança
cobsr[].txid	string	Identificador da cobrança recorrente
cobsr[].status	string	Status atual da cobrança recorrente (ex: ATIVA)
cobsr[].atualizacao	array	Histórico de mudanças de status com data e hora de cada transição
cobsr[].tentativas	array	Tentativas de liquidação da cobrança (dataLiquidacao, tipo, status e endToEndId)

Dicas de Teste

Use o ngrok ou ferramentas similares (localtunnel, Cloudflare Tunnel) para expor seu servidor local na internet e receber webhooks reais durante o desenvolvimento.

Sempre valide o header X-Webhook-Secret em produção. Nunca processe payloads de webhook sem verificar que o secret corresponde ao valor configurado na sua conta Versell.

Para testar localmente, inicie seu servidor e use os comandos cURL acima diretamente no terminal. Siga este fluxo:

Inicie seu servidor local (ex: npm run dev)
Copie um dos comandos cURL acima e execute no terminal
Verifique os logs do servidor para confirmar que o payload foi recebido e processado
Teste cenários de erro alterando o header X-Webhook-Secret para um valor incorreto