Skip to content
Xfin Developers

Changelog

Todas as alterações relevantes da Xfin Payouts API estão documentadas aqui.

v1 — Lançamento inicial

Lançado em: 15 de junho de 2026

Novidades

A Xfin Payouts API (v1) está disponível para parceiros. Esta versão entrega o fluxo ONRAMP completo: clientes pagam BRL via PIX e recebem USDT na Arbitrum.

Endpoints:

  • POST /v1/payouts — Cria um payout (BRL via PIX → USDT na Arbitrum). Retorna pix_copy_paste para o pagador efetuar o pagamento.
  • GET /v1/payouts/{id} — Consulta um payout por ID (escopo por parceiro).
  • GET /v1/payouts — Lista todos os payouts do parceiro autenticado, do mais recente ao mais antigo.

Funcionalidades:

  • Idempotência — Envie o header Idempotency-Key para reenviar POST /v1/payouts com segurança sem gerar cobranças duplicadas. Reenvios com a mesma chave retornam o payout original. Uma duplicata enviada enquanto a original ainda está em processamento retorna 409 Conflict. As chaves são escopadas por parceiro com TTL de 24 horas. Consulte o guia de idempotência para detalhes.
  • Cotação com mínimo garantido — A taxa de câmbio BRL → USDT é calculada no momento da criação do payout e garante um valor mínimo de USDT ao destinatário, independente de variações de mercado durante o processamento. Consulte o guia de cotação para mais informações.
  • PIX copy-paste — A resposta inclui pix_copy_paste (string EMV “copia e cola”) para exibição imediata ao pagador. Também disponível na consulta via GET /v1/payouts/{id}.
  • Escopo por parceiro — Todos os payouts são escopados à sua API Key (partner_id). GET /v1/payouts/{id} retorna 404 para payouts de outros parceiros.
  • Tipos de chave PIX — Suporte a todos os formatos padrão: CPF, CNPJ, EMAIL, TELEFONE, ALEATÓRIA (UUID).
  • Rate limiting — 100 requisições por minuto por API Key (token bucket). Exceder o limite retorna 429 Too Many Requests com header Retry-After: 60.
  • Ciclo de vida de status — PENDING → PROCESSING → COMPLETED / FAILED. Campos de liquidação (blockchain_tx_id, block_explorer_url, settled_amount_usdt, paid_at, confirmed_at) são preenchidos ao atingir COMPLETED.

Em breve:

  • Webhooks para parceiros (payout.completed, payout.failed) — atualmente em construção. Consulte o guia de webhooks para a interface planejada.

Alterações na Payouts API serão documentadas aqui conforme forem lançadas. Acompanhe as comunicações do seu gerente de conta Xfin para anúncios de novos lançamentos.