Webhooks

A Xfin usa webhooks internamente para processar confirmações de pagamento PIX em tempo real. Esta página descreve o fluxo atual e os callbacks de parceiro que estão planejados para breve.

Fluxo atual: webhook interno 4Pay

Quando um pagador efetua o PIX, a 4Pay Finance notifica a Xfin via webhook. O fluxo é:

1. O pagador realiza o pagamento PIX usando o pix_copy_paste.

2. A 4Pay Finance envia POST /webhooks/4pay à Xfin com um token opaco:

   { "token": "eyJhbGciOiJIUzI1NiIsInR..." }

3. O handler Xfin usa o token para buscar o evento completo na API da 4Pay (GET /pix/notification/:token).

4. O evento é processado, o payout é atualizado no banco de dados e a máquina de estados avança.

Note

O endpoint /webhooks/4pay é público — não requer X-Api-Key. Ele é protegido via validação do token recebido contra a API da 4Pay.

Máquina de estados do payout

PENDING → PROCESSING → COMPLETED
                    ↘ FAILED

Status	Descrição
PENDING	Cobrança PIX criada, aguardando pagamento
PROCESSING	Pagamento confirmado pelo banco; transferência USDT iniciada
COMPLETED	USDT liquidado na carteira do destinatário
FAILED	Falha no processamento — entre em contato com o suporte

Transições são unidirecionais — um payout COMPLETED ou FAILED não pode retroceder.

Idempotência do webhook

A Xfin garante que cada evento da 4Pay é processado exatamente uma vez, mesmo que o webhook seja entregue múltiplas vezes pelo provedor. O token do webhook é armazenado com TTL na coleção webhook_idempotency; entregas repetidas do mesmo token são descartadas silenciosamente.

Como acompanhar o status agora

Enquanto os callbacks de parceiro não estão disponíveis, use polling:

PAYOUT_ID="550e8400-e29b-41d4-a716-446655440000"
API_KEY="sua-api-key"
BASE_URL="https://xfin-payouts-ys3int7llq-rj.a.run.app"

while true; do
  STATUS=$(curl -s "$BASE_URL/v1/payouts/$PAYOUT_ID" \
    -H "X-Api-Key: $API_KEY" \
    | python3 -c "import sys,json; print(json.load(sys.stdin)['status'])")
  echo "$(date -u +%H:%M:%S) Status: $STATUS"
  if [ "$STATUS" = "COMPLETED" ] || [ "$STATUS" = "FAILED" ]; then
    break
  fi
  sleep 10
done

Consulte o Quickstart para uma versão completa do loop com parsing da resposta.

Callbacks de parceiro (em breve)

Caution

Esta seção descreve funcionalidade planejada que ainda não está disponível. Não construa integrações de produção contra esta estrutura — ela pode mudar antes do lançamento.

Quando os callbacks de parceiro estiverem disponíveis, a Xfin enviará notificações HTTP diretamente para uma URL configurada na sua conta. Você não precisará mais fazer polling.

Eventos planejados

Evento	Gatilho
payout.completed	Payout atingiu status COMPLETED (USDT liquidado na receiver_wallet)
payout.failed	Payout atingiu status FAILED

Formato tentativo do payload

{
  "event": "payout.completed",
  "payout": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "COMPLETED",
    "amount_brl": 100.00,
    "min_amount_usdt": 18.37,
    "settled_amount_usdt": 19.38,
    "blockchain_tx_id": "0xabc123...",
    "block_explorer_url": "https://arbiscan.io/tx/0xabc123...",
    "paid_at": "2026-06-14T20:15:00Z",
    "confirmed_at": "2026-06-14T20:17:30Z"
  }
}

O objeto payout terá o mesmo formato de GET /v1/payouts/{id}.

Assinatura (planejada)

Os callbacks serão assinados para que você possa verificar a autenticidade. O mecanismo exato (por exemplo, HMAC-SHA256 via header dedicado e segredo compartilhado) ainda está sendo definido.

Próximos passos

Acompanhe as atualizações pelo seu gerente de conta Xfin. Quando o recurso for lançado, a documentação será atualizada com o formato final do payload, esquema de assinatura e instruções de configuração.