Skip to main content
A Legacy oferece suporte a Webhooks, mecanismo que envia requisições HTTP POST diretamente para a sua aplicação toda vez que ocorre uma mudança de evento importante em nossa infraestrutura. Por exemplo, você pode receber um alerta sempre que:
  • O pagamento de um PIX for aprovado pelo banco.
  • Um saque (Payout) finalizar com sucesso.
  • Um pagamento por Cartão de Crédito virar Chargeback.

​
Onde configurar

Durante as requisições, por exemplo na criação de um Payback POST /payin, você envidará nativamente a propriedade webhookUrl. A Legacy enviará todas as atualizações pertencentes àquele pagamento para a URL informada dinamicamente.

​
Validação e Eventos (Payins)

Quando a Legacy enviar um webhook do Payin, nós usaremos o seguinte Payload: 
{
  "id": "payin_12345",
  "status": "APPROVED",
  "paymentMethod": "PIX",
  "amount": 10000,
  "referenceId": "meu-pedido-1234",
  "customer": {
    "name": "Maria Silva",
    "email": "maria@email.com"
  },
  "updatedAt": "2026-03-02T12:00:00.000Z"
}

​
Possíveis Status do Payin

É aconselhável que o seu sistema saiba lidar de forma fluida com estes retornos:
  • PENDING - Gerado, aguardando liquidação.
  • APPROVED - O saldo está disponível para a loja.
  • FAILED - Falha catastrófica (Ex: Adquirente fora do ar).
  • CANCELED - A transação foi cancelada antes de ocorrer.
  • REFUSED - Saldo negado pelo emissor do Cartão ou sistema Anti-Fraudes.
  • REFUNDED - Você aplicou um estorno parcial/total na mesma.
  • CHARGEBACK - Seu cliente contestou com o banco emissor o uso indevido da compra.
  • EXPIRED - Janela de PIX ou Boleto vencidas.

​
Validação e Eventos (Payouts)

Para o saque manual efetuado via API, POST /payout, a estrutura possui o seguinte comportamento de disparos no Webhook: 
{
  "id": "payout_98765",
  "status": "COMPLETED",
  "amount": 50000,
  "pixKey": "maria@email.com",
  "pixKeyType": "EMAIL",
  "referenceId": "saque-afiliado-01",
  "updatedAt": "2026-03-02T12:30:00.000Z"
}
Geralmente, um Payout trafegará pelo status PROCESSING até consolidar-se em COMPLETED ou FAILED.
Sempre retorne qualquer status HTTP no range 2xx (Ex: 200 OK) nos seus controladores de webhook. Se nosso endpoint falhar, tentaremos despachar novamente em janelas crescentes de repetição.