Changelog

Mudanças relevantes da API pública da INFI.

2026-06-04 — Cadastro de destinatário terceiro via API

Novo endpoint POST /v1/recipients para submeter destinatários terceiros (CPF/CNPJ diferente do titular) direto pela API — antes, o cadastro só era feito pelo suporte.

• O cadastro registra o destinatário como pending_review: não aprova e não libera saque. A aprovação (KYC/AML) continua sendo feita pela INFI. Só após ativado o destinatário aparece em GET /v1/recipients e pode ser usado em POST /v1/withdraw via recipientId.
• Idempotente pelo documento: reenviar o mesmo CPF/CNPJ retorna o mesmo recipientId (não duplica); um destinatário já aprovado não é rebaixado.
• Name-match: chave cpf/cnpj precisa bater com o document. Limite padrão de 10 destinatários (ativos + em análise) por conta — ajustável por conta via suporte.

Veja Cadastrar destinatário.

2026-06-02 — Retry automático de webhook

Entregas de webhook que falham por erro transiente (timeout, erro de rede, HTTP 5xx, 429, 408) agora são reentregues automaticamente com backoff: 1min → 5min → 30min → 2h → 6h (até 6 tentativas, ~9h). Antes, havia uma única tentativa automática — a recuperação dependia de polling ou reenvio manual.

• 4xx não é retentado (400/401/403/422…): significa que o endpoint recusou o evento; martelar não resolveria. Corrija a causa e use o reenvio manual.
• eventId é preservado entre tentativas — deduplicar por X-Infi-Event-Id é obrigatório. O timestamp e a X-Infi-Signature são regenerados a cada tentativa; o eventId não.
• Com isso, recomenda-se um fluxo event-driven: reaja ao webhook + mantenha seu saldo a partir de netCents + reconcile leve, sem polling agressivo de GET /v1/balance.

Mudança de comportamento, não de contrato: nenhum campo novo, nenhuma ação necessária para quem já deduplica por eventId. Veja Retentativa e idempotência.

2026-05-27 — Normalização automática de document.type e pixKeyType + erros mais informativos

Mudança aditiva: requests que já enviam valores corretos continuam funcionando sem ajuste. O que muda é como tratamos variações e como reportamos erros.

Normalização automática (Postel’s law) em campos enum:

• customer.document.type em POST /v1/pix: aceita "CNPJ", "Cpf", " cnpj " etc. — variações de case e whitespace são normalizadas internamente para lowercase. Antes, qualquer não-lowercase era silenciosamente convertido em "cpf" no sanitize, fazendo o provedor rejeitar números com tamanho incompatível e gerando 502 Erro ao comunicar com gateway confuso.
• pixKeyType em POST /v1/withdraw: mesma normalização — "CPF", "Email", " evp " aceitos.

Validação de tamanho de documento: customer.document.number precisa ter 11 dígitos quando type=cpf ou 14 dígitos quando type=cnpj (após remover pontuação). Antes, números com tamanho incompatível eram aceitos pela INFI e rejeitados pelo PSP.

Erros mais informativos — todas as mensagens de 400 em validação de payload agora incluem o valor recebido (truncado) e o esperado:

// Antes
{ "error": "Erro ao comunicar com gateway. Tente novamente." }
// status: 502
 
// Agora
{ "error": "customer.document.type deve ser 'cpf' ou 'cnpj'. Recebido: 'CNPJ '." }
// status: 400

Recomendação: enviar valores em lowercase sem whitespace é o padrão limpo, mas a API não exige mais.

Veja Criar cobrança, Iniciar saque e Erros.

2026-05-09 — Saque a terceiros pré-aprovados via API

POST /v1/withdraw ganhou suporte ao campo opcional recipientId para sacar para destinatários terceiros (CPF/CNPJ que não é o titular da conta).

• Sem recipientId (default): comportamento de antes — só CPF/CNPJ do titular cadastrado, outros tipos rejeitados.
• Com recipientId: libera os 5 tipos de chave PIX (cpf, cnpj, email, phone, evp) para um destinatário pré-aprovado pelo time INFI (compliance/AML).

A aprovação do recipientId é manual — contate o suporte informando o nome legal e CPF/CNPJ do destinatário. Não há endpoint para auto-cadastro.

Novo endpoint GET /v1/recipients retorna a lista de destinatários ativos pré-aprovados para sua conta com os respectivos recipientId — use-os no POST /v1/withdraw. Veja Listar destinatários.

Defesas atuais inalteradas: API key, IP allowlist, rate limit, anti-burst, caps diário/mensal, validação de saldo, idempotência via externalRef. Cada saque a terceiro dispara alerta interno na INFI (auditoria contínua).

Veja Iniciar saque para schema completo, restrições por tipo de chave e exemplos.

2026-05-09 — Dados do PIX nos webhooks e na consulta REST

Novos campos opcionais entregues quando a transação foi efetivamente liquidada na rede SPI. Mudança aditiva — clientes que não usam ignoram, sem necessidade de adaptação.

• Webhooks transaction.paid, transaction.refunded, transaction.partially_refunded agora trazem:

  • endToEndId — E2E ID padrão BACEN do PIX (formato E<ISPB><YYYYMMDDhhmm><id>).
  • payer — quem pagou: { name, document, documentType, bankAccount: { ispb, branch, account } }.

• Webhooks transfer.paid, transfer.refunded, transfer.partially_refunded agora trazem:

  • endToEndId — E2E ID do PIX OUT.
  • beneficiary — quem recebeu o saque: mesma estrutura de payer.
  • refundEndToEndId — apenas em devoluções (transfer.refunded / transfer.partially_refunded): E2E ID do PIX de devolução, distinto do PIX OUT original.

• REST GET /v1/transactions/:id e GET /v1/transactions retornam os mesmos campos quando aplicáveis. Polling vira fallback equivalente ao webhook.

Eventos sem liquidação (transaction.failed, cancelled, expired, transfer.created, processing, pending_approval, approved, rejected, failed, cancelled) não trazem esses campos — omitidos do JSON, não vêm como null.

Atenção LGPD: payer.* e beneficiary.* contêm dados pessoais (nome, CPF/CNPJ, conta bancária). Você é o controlador do tratamento posterior. Ver Eventos.

2026-05-08 — Multi-webhook + histórico de entregas

• Múltiplas URLs de webhook por conta (até 6). Cada URL filtra eventos por nome canônico ou por categoria semântica (cashin, cashout, refund, dispute, chargeback). Veja Configurando webhook.
• Catálogo de eventos canônicos padronizado: 21 eventos transaction.* e transfer.*, com nomes estáveis no X-Infi-Event e no campo event do corpo. Veja Eventos.
• Eventos novos entregues pela primeira vez: transaction.partially_refunded, transaction.infraction, transaction.dispute, transaction.protest, transaction.blocked, transaction.chargeback, transfer.created, transfer.processing, transfer.partially_refunded.
• Header novo: X-Infi-Event-Id com um identificador único por evento. Mesmo entre URLs do fanout e em reenvios manuais — use para dedupe.
• Histórico de entregas no painel (60 dias de retenção): timeline de cada tentativa com payload exato, status HTTP e duração. Disponível na transação ou na lista global.
• Reenvio manual de webhook: botão pra disparar nova tentativa de uma entrega histórica. eventId é preservado (idempotência), timestamp e signature regenerados. Limite 10/h por conta. Veja Redespacho manual.

Quebras de naming (notar se você integrou antes de maio/2026)

Os nomes a seguir foram substituídos pelos canônicos:

Se você comparava pelo nome antigo, atualize. O status no corpo (campo estável) continua igual.

2026-05-08 — 2FA no painel (sem impacto na API)

• Lojistas agora podem ativar autenticação em dois fatores (TOTP) no painel, em Configurações → Segurança.
• Nenhuma mudança no contrato da API REST. API keys continuam funcionando exatamente como antes — sem código adicional, sem header novo, sem mudança em requests ou respostas.
• Saques iniciados pelo painel passam a exigir código TOTP no momento da operação. Saques via POST /v1/withdraw permanecem inalterados (autenticação por API key + IP allowlist + rate limit).

2026-05 — Lançamento da documentação pública

• Versão inicial cobrindo:
  • POST /v1/pix — criação de cobrança PIX.
  • POST /v1/withdraw — saque PIX.
  • GET /v1/balance — saldo.
  • GET /v1/transactions e GET /v1/transactions/:id — listagem e consulta.
  • Webhook único entregue ao endpoint configurado pelo lojista, assinado por HMAC.

[VERIFICAR COM EQUIPE INFI]: alinhar política de versionamento da API (semver, breaking changes, prazos de deprecação) e formato definitivo deste changelog.