Docs
EntrarCriar conta
Ambiente
Base URLhttps://api.sancopay.com/api/v1
Arquivo para IA
Webhooks

Eventos e payloads

Todos os eventos chegam por POST nas URLs cadastradas, no mesmo envelope. Decida o que fazer pelo campo event, que também vem no header X-Webhook-Event-Type de toda entrega.

EnvelopePOST na sua URL
{  "event": "<nome do evento>",  "created_at": "2026-11-09T15:04:41.000000Z",  "data": {}}

Eventos

charge.paid
Cobrança paga. Também charge.failed, charge.refunded, charge.expired e charge.pending: o sufixo é o status da cobrança.
payout.completed
Saque concluído. Também payout.failed, payout.refunded e payout.processing.
pre_approval.created
Pré-aprovação criada; data traz amount_blocked (se reservou o saldo), balance_before e balance_after.
pre_approval.approved
Pré-aprovação aprovada e Pix enviado.
pre_approval.rejected
Pré-aprovação cancelada; failure_reason quando houver.
pre_approval.failed
O envio falhou; failure_reason. Recusa do processador traz processor_rejected: true e processor_status.
recurring_charge.*
created, paid, overdue, cancelled e duplicate_payment, só nas contas com a recorrência liberada. Detalhes em Recorrência.
webhook.test
Entrega de teste (botão “Testar” da tela de Webhooks); data.test é true.
Exemplos de payload
{  "event": "charge.paid",  "created_at": "2026-11-09T15:04:41.000000Z",  "data": {    "id": 4821,    "tracking_id": "c62abd1d-9092-4892-b163-cef2951912ad",    "reference": "PED-123",    "status": "paid",    "amount": 150,    "fee": 1.5,    "currency": "BRL",    "customer": {      "name": "Maria Souza",      "email": "[email protected]",      "tax_id": "12345678909"    },    "end_to_end_id": "E18236120202611091504s0a1b2c3d4e",    "metadata": {      "order_id": "123",      "coupon": "OFF10"    },    "failure_reason": null,    "created_at": "2026-11-09T15:04:05.000000Z",    "updated_at": "2026-11-09T15:04:41.000000Z"  }}

Campos do data

charge.*
id, tracking_id, reference, status, amount, fee, currency (BRL), customer {name, email, tax_id}, end_to_end_id, metadata, failure_reason, created_at, updated_at.
payout.*
Os mesmos, com recipient {name, tax_id} no lugar de customer. id é o id do saque na SancoPay (pode vir null); tracking_id é o código de rastreio do Pix.
pre_approval.*
O recurso da pré-aprovação, mais os extras de cada evento.

Boas práticas

  • Responda 2xx rápido e processe depois (fila). Respostas lentas ou com erro são reenviadas.
  • Trate entregas repetidas: use event + data.id (ou data.reference) para não processar duas vezes.
  • Confira a assinatura antes de confiar no conteúdo. Veja Assinatura.
  • Na recorrência, o Pix de cada ciclo também gera o charge.*, com reference iniciada por REC- e metadata com recurring_charge_id, recurring_subscription_id e cycle. Dê baixa no ciclo pelo recurring_charge.paid e trate esse charge.paid só como registro.