PortuguêsReferência da APISaquesIniciar saque PIX

Iniciar saque PIX

POST/v1/withdraw
Inicia um saque PIX para uma chave externa.
Pré-condições

Saldo disponível ≥ amountCents + feeCents, KYC aprovado, conta não bloqueada, tipo de chave PIX permitido. Falhas síncronas não debitam saldo.

Cabeçalhos

CabeçalhoObrigatórioDescrição
AuthorizationsimBearer <SUA_API_KEY>
Content-Typesimapplication/json

Corpo

{
  "amountCents": 5000,
  "pixKey": "12345678901",
  "pixKeyType": "cpf",
  "description": "Repasse de comissões",
  "externalRef": "withdraw-2026-05-08-001"
}
CampoTipoObrig.Descrição
amountCentsinteirosimValor em centavos. Mínimo: 100.
pixKeystringsimChave PIX do destinatário. Máx. 150 caracteres.
pixKeyTypestringsimcpf, cnpj, email, phone ou evp (ver restrições por modo abaixo). Variações de case e whitespace são normalizadas automaticamente — "CPF", "Cnpj", " email " são aceitos.
descriptionstringnãoDescrição livre. Máx. 200 caracteres.
externalRefstringnãoRecomendado. Chave de idempotência sua (máx. 100 caracteres). Dois requests com o mesmo externalRef recebem a mesma transação — protege contra duplicação em retries. Ver callout abaixo.
recipientIdstringnãoID do destinatário terceiro pré-aprovado pelo time INFI (24 caracteres hex). Sem este campo, saque vai pro titular (CPF/CNPJ cadastrado). Com este campo, saque vai pro terceiro autorizado. Ver “Saque a terceiros” abaixo.
Idempotência via externalRef (recomendado)

Sempre que possível, envie um externalRef único por saque. Se a sua chamada falhar com timeout, queda de rede ou crash do seu sistema, reenvie o request com o mesmo externalRef — a resposta retornará a transação original com idempotent: true, sem criar saque duplicado.

Sem externalRef, retries criam saques separados — risco real de duplicação. Use sempre algo único e estável (ex.: ID interno do seu sistema, UUID).

Dois modos de saque

Modo 1 — Saque para o titular (default, sem recipientId)

Comportamento padrão. Aceita apenas chaves do tipo cpf ou cnpj que pertençam ao titular da conta:

  • pixKeyType: "cpf" → a chave deve coincidir com o CPF do responsável cadastrado.
  • pixKeyType: "cnpj" → a chave deve coincidir com o CNPJ da empresa cadastrada.

Outros tipos (email, phone, evp) só são aceitos via Modo 2 (terceiro autorizado).

Modo 2 — Saque para terceiro autorizado (com recipientId)

Para sacar para um CPF/CNPJ que não é o titular (ex.: fornecedor recorrente, transferência inter-empresas), o destinatário precisa ser pré-aprovado pelo time da INFI.

Como solicitar aprovação: contate o suporte da INFI informando o nome legal e CPF/CNPJ do destinatário. O time avalia a operação (compliance/AML) e, se aprovada, o recipientId (24 caracteres hexadecimais) fica disponível pelo endpoint GET /v1/recipients. Não há endpoint para auto-cadastro — toda aprovação é manual com auditoria.

Restrições no Modo 2:

  • Aceita os 5 tipos de chave PIX (cpf, cnpj, email, phone, evp).
  • Para pixKeyType: "cpf" ou "cnpj": a chave deve coincidir exatamente com o documento do destinatário aprovado.
  • Para email/phone/evp: a INFI confia que o destino vai resolver no DICT do BACEN para o documento aprovado. PSP rejeita se houver divergência.
  • Cada saque a terceiro dispara alerta interno na INFI (auditoria contínua).
Aprovação prévia obrigatória

Você não pode sacar para qualquer CPF/CNPJ via API — apenas para os destinatários que o time INFI aprovou previamente para sua conta. Cada aprovação passa por verificação de compliance e gera audit trail.

Resposta 201 Created

Modo automático (default)

{
  "transactionId": "...",
  "status": "processing",
  "amountCents": 5000,
  "feeCents": 100,
  "totalDeducted": 5100
}

Saldo já foi debitado (totalDeducted = amountCents + feeCents). Aguarde o webhook TRANSFER_PAID ou consulte o status.

Modo aprovação manual

{
  "transactionId": "...",
  "status": "pending_approval",
  "amountCents": 5000,
  "feeCents": 100,
  "totalDeducted": 5100
}

Saldo não foi debitado ainda. Aguarda revisão da equipe da INFI. Veja Ciclo de um saque.

Resposta 200 OK (retry idempotente)

Quando você reenvia um request com externalRef que já existe, a resposta tem status 200 (em vez de 201) e inclui idempotent: true:

{
  "transactionId": "...",
  "status": "processing",
  "amountCents": 5000,
  "feeCents": 100,
  "totalDeducted": 5100,
  "idempotent": true
}

O transactionId é o mesmo da primeira chamada. Nenhum novo saque é criado, nenhum saldo adicional é debitado.

Respostas de erro / casos especiais

HTTPCorpoSignificado
400"amountCents deve ser inteiro ≥ 100..."Valor inválido.
400"pixKey obrigatória."Chave faltando.
400"pixKeyType deve ser 'cpf', 'cnpj', 'email', 'phone' ou 'evp'. Recebido: '<valor>'."Tipo desconhecido após normalização.
400"Saque para chaves email/telefone/aleatória exige destinatário autorizado."pixKeyType é email/phone/evp mas você não enviou recipientId. Use Modo 2.
400"recipientId inválido."Formato de recipientId errado (esperado: 24 chars hex).
400"Tipo de chave (CPF/CNPJ) não bate com o tipo do documento do destinatário."Você enviou pixKeyType: "cpf" mas o destinatário aprovado é CNPJ (ou vice-versa).
404"Destinatário autorizado não encontrado."recipientId não existe para esta conta. Verifique com o suporte.
422"Destinatário desativado pelo time INFI. Saque cancelado."O destinatário foi desativado (compliance/AML). Solicite reaprovação.
403"Chave PIX (CPF/CNPJ) não corresponde ao documento do destinatário autorizado."Modo 2 com cpf/cnpj exige chave PIX igual ao documento aprovado.
400"Saque acima do máximo..."Excede limite por transação.
401"API key inválida ou revogada."
403"Tipo de chave PIX 'X' não autorizado para esta conta."Restrição da conta.
403"Saque com chave CNPJ só permitido para o CNPJ cadastrado..."Titularidade.
403"Saque com chave CPF só permitido para o CPF do responsável..."Titularidade.
403"IP de origem não autorizado..."IP allowlist.
422"Saldo insuficiente para realizar o saque."Saldo + taxa > disponível.
429"Aguarde alguns segundos antes do próximo saque."Rate limit anti-burst (1/segundo).
429"Muitos saques em curto intervalo. Aguarde alguns instantes."Rate limit anti-burst (2/minuto).
429"Limite de saques atingido."Rate limit horário (10/hora).
502"Erro ao processar saque. O valor não foi debitado."Falha do provedor com rollback.
502"Saque iniciado mas confirmação interrompida..."Operação concluída, resposta interrompida. Consulte o transactionId retornado.
202"Saque em verificação. Saldo debitado..."Estado indeterminado. Não reenvie. Veja failed_unknown.

Exemplos

curl -X POST https://api.internationalfinance.com.br/v1/withdraw \
  -H "Authorization: Bearer $INFI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amountCents": 5000,
    "pixKey": "12345678901",
    "pixKeyType": "cpf",
    "description": "Repasse",
    "externalRef": "withdraw-2026-05-08-001"
  }'

Exemplo: saque a terceiro autorizado (Modo 2)

Use o recipientId retornado pelo time INFI após aprovar seu destinatário:

curl -X POST https://api.internationalfinance.com.br/v1/withdraw \
  -H "Authorization: Bearer $INFI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amountCents": 5000,
    "pixKey": "fornecedor@empresa.com.br",
    "pixKeyType": "email",
    "recipientId": "abc123def456abc123def456",
    "description": "Pagamento fornecedor X",
    "externalRef": "supplier-payment-2026-05-15"
  }'

A resposta tem o mesmo formato dos exemplos anteriores. Você pode misturar cpf/cnpj/email/phone/evp no pixKeyType desde que o destinatário esteja aprovado e (para cpf/cnpj) a chave coincida exatamente com o documento aprovado.