VersellAPI

Webhooks

Receba notificações em tempo real sobre eventos de pagamento

O que são Webhooks?

Webhooks são notificações HTTP enviadas automaticamente pela Versell para o seu servidor quando eventos importantes ocorrem, como o recebimento de um Pix ou a conclusão de uma transferência. Em vez de consultar a API repetidamente (polling), seu sistema recebe as atualizações em tempo real.

*
Você também pode configurar seus webhooks diretamente pelo painel do Finance (finance.versell.com.br), sem precisar fazer chamadas à API. O Finance também permite consultar o histórico de transações, acompanhar pagamentos recebidos e enviados, e verificar o status de webhooks configurados.

Webhook Cash In

O webhook de Cash In notifica seu sistema quando um Pix é recebido. Apenas transações Pix que possuem txid são notificadas. Os IPs de origem são dinâmicos — identifique a Versell pelo header customizado.

Configuração

Registre sua URL de webhook associada a uma chave Pix:

curl -X PUT https://api.pix.basspago.com.br/webhook/{chave_pix} \
  --cert ./client.crt \
  --key ./client.key \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://your-server.com/webhook/pix"
  }'
!
Ao configurar o webhook de Cash In, o sufixo /pix é automaticamente adicionado à URL informada. Por exemplo, se você registrar "https://your-server.com/webhook", as notificações serão enviadas para "https://your-server.com/webhook/pix". Certifique-se de que seu servidor escuta nessa rota completa.

Exemplo de Payload

{
  "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"
}
!
Os IPs de origem do webhook de Cash In são dinâmicos e podem mudar sem aviso. Não filtre por IP. Use o header X-Webhook-Secret para validar a autenticidade das notificações.

Webhook Cash Out

O webhook de Cash Out notifica seu sistema quando uma transferência é liquidada (settled) ou cancelada (cancelled).

Configuração

Registre sua URL de webhook para notificações de transferência:

curl -X POST https://pagamentos.basspago.com.br/api/v2/webhooks/transfer \
  --cert ./client.crt \
  --key ./client.key \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "uri": "https://your-server.com/webhook/transfer",
    "enabled": true,
    "method": "POST"
  }'

Exemplo de Payload

{
  "data": {
    "id": 825100,
    "txId": null,
    "pixKey": null,
    "status": "LIQUIDATED",
    "payment": {
      "amount": "250.00",
      "currency": "BRL"
    },
    "endToEndId": "E12345678202301011234abcdefghijkl",
    "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": "2024-01-15T14: 30: 00.000Z"
  },
  "type": "TRANSFER"
}

Webhook Infração / MED

O webhook de Infração notifica seu sistema quando uma solicitação de devolução por infração (MED — Mecanismo Especial de Devolução) é aberta contra uma transação Pix. Isso ocorre quando o pagador contesta a transação junto ao seu banco.

Os possíveis status da infração são:

  • WAITING_PSPInfração aberta, aguardando análise do PSP recebedor
  • CLOSEDInfração encerrada após análise
  • CANCELEDInfração cancelada
X
Infrações MED exigem resposta dentro do prazo estabelecido pelo Banco Central. O status "WAITING_PSP" indica que a Versell aguarda sua análise. Trate esse webhook com prioridade.

Exemplo de Payload

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

Segurança

A Versell envia um header X-Webhook-Secret em cada notificação de webhook. Use esse valor para validar que a requisição realmente veio da Versell e não de um terceiro malicioso.

app.post('/webhook/pix', (req, res) => {
  const receivedSecret = req.headers['x-webhook-secret'];
  const expectedSecret = process.env.WEBHOOK_SECRET;

  if (receivedSecret !== expectedSecret) {
    return res.status(401).json({ error: 'Invalid webhook secret' });
  }

  // Process the webhook payload
  const { pix } = req.body;
  console.log('Pix received:', pix);

  // Respond with 200 quickly
  res.status(200).json({ received: true });

  // Process asynchronously
  processPixPayment(pix).catch(console.error);
});
*
Sempre valide o header X-Webhook-Secret antes de processar qualquer notificação de webhook. Armazene o secret em uma variável de ambiente segura.

Boas Práticas

  • 1.Responda com 200 rapidamente — Retorne HTTP 200 imediatamente ao receber o webhook. Processe os dados de forma assíncrona para evitar timeouts.
  • 2.Processamento assíncrono — Use filas (RabbitMQ, SQS, Redis) para processar webhooks em background. Não bloqueie a resposta com lógica de negócio.
  • 3.Trate duplicatas — Webhooks podem ser enviados mais de uma vez. Use o endToEndId ou transferId como chave de idempotência para evitar processar o mesmo evento duas vezes.
  • 4.Lógica de retry — Se seu servidor não responder com 200, a Versell tentará reenviar a notificação. Certifique-se de que seu endpoint é idempotente.
  • 5.Validação de segurança — Sempre valide o X-Webhook-Secret e, se possível, verifique a assinatura do payload.