Cadastrar destinatário autorizado

POST/v1/recipients

Submete um destinatário terceiro (CPF/CNPJ diferente do titular) para análise. NÃO aprova — o saque a esse destinatário só é liberado após aprovação de compliance pela INFI.

Cadastrar não libera saque

Este endpoint apenas registra o destinatário para análise (status: "pending_review"). Ele não aprova e não move dinheiro. O destinatário só pode receber saque depois que a INFI concluir a verificação (KYC/AML) e ativá-lo — quando ele passa a aparecer em GET /v1/recipients e pode ser usado em POST /v1/withdraw via recipientId.

Quando usar

Só precisa deste fluxo se for sacar para CPFs/CNPJs diferentes do titular da conta (ex.: pagar fornecedores/parceiros recorrentes). Para sacar pra você mesmo, omita recipientId no /v1/withdraw — não precisa cadastrar nada.

Cabeçalhos

Cabeçalho	Obrigatório	Descrição
`Authorization`	sim	`Bearer <SUA_API_KEY>`
`Content-Type`	sim	`application/json`

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`legalName`	string	sim	Razão social ou nome do destinatário (2–120 chars).
`document`	string	sim	CPF (11 dígitos) ou CNPJ (14 dígitos). Pontuação é ignorada.
`documentType`	string	sim	`cpf` ou `cnpj`. Aceita variações de case/whitespace (`"CNPJ"` → `"cnpj"`).
`pixKey`	string	sim	Chave PIX do destinatário.
`pixKeyType`	string	sim	`cpf`, `cnpj`, `email`, `phone` ou `evp`.
`label`	string	não	Apelido livre para sua referência (até 80 chars).

Name-match (anti-fraude)

Se pixKeyType for cpf ou cnpj, a chave tem que bater com o document informado (mesmos dígitos e mesmo tipo). Para email/phone/evp, o titular da chave é validado na infraestrutura PIX no momento do saque.

Resposta `201 Created`

{
  "recipientId": "abc123def456abc123def456",
  "status": "pending_review",
  "note": "Destinatário recebido e EM ANÁLISE. O saque a esse destinatário só é liberado após aprovação pela INFI."
}

Campo	Descrição
`recipientId`	24 chars hex, determinístico pelo documento. Guarde-o; é o mesmo usado em `POST /v1/withdraw`.
`status`	`pending_review` (em análise) ou `active` (já aprovado — ver idempotência).
`note`	Mensagem legível reforçando que o cadastro não libera saque.

200 OK (em vez de 201) quando o destinatário já existia — ver idempotência abaixo.

Idempotência

O recipientId é derivado do document (hash determinístico). Reenviar o mesmo documento é seguro:

Já em análise → retorna o mesmo recipientId com status: "pending_review" (não duplica).
Já aprovado (active) → retorna status: "active" e não rebaixa a aprovação.
Anteriormente recusado/removido → reativa para pending_review (nova análise), atualizando os dados enviados.

Não há campo externalRef aqui — a idempotência é pelo próprio documento.

Limite

Cada conta tem um teto de destinatários ativos + em análise (padrão 10). Atingido o teto, novos cadastros retornam 422. Precisa de mais? Fale com o suporte — o limite é ajustado por conta após avaliação.

Erros

HTTP	`error` (exemplos)
400	`"legalName é obrigatório (mínimo 2 caracteres)."` · `"document deve ter 11 dígitos para cpf. Recebido: 10."` · `"Chave PIX (CPF/CNPJ) não corresponde ao documento informado."`
401	`"API key inválida ou revogada."`
403	`"IP de origem não autorizado..."`
422	`"Limite de 10 destinatários atingido. Remova um inativo ou fale com o suporte."`
429	`"Limite de requisições atingido."` (rate limit do endpoint)

Fluxo completo

POST /v1/recipients — você submete o destinatário → pending_review.
Análise da INFI (KYC/AML) → aprovação ativa o destinatário.
GET /v1/recipients — o destinatário aprovado aparece na lista com recipientId.
POST /v1/withdraw com recipientId — saque liberado para o destinatário aprovado.

Exemplos

curl -X POST https://api.internationalfinance.com.br/v1/recipients \
  -H "Authorization: Bearer $INFI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "legalName": "Fornecedor XYZ LTDA",
    "document": "12345678000199",
    "documentType": "cnpj",
    "pixKey": "12345678000199",
    "pixKeyType": "cnpj",
    "label": "Fornecedor recorrente"
  }'

const res = await fetch('https://api.internationalfinance.com.br/v1/recipients', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.INFI_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    legalName: 'Fornecedor XYZ LTDA',
    document: '12345678000199',
    documentType: 'cnpj',
    pixKey: '12345678000199',
    pixKeyType: 'cnpj',
    label: 'Fornecedor recorrente',
  }),
})
const { recipientId, status } = await res.json()
// status === 'pending_review' — aguarde aprovação antes de sacar.

import os, requests
 
res = requests.post(
    "https://api.internationalfinance.com.br/v1/recipients",
    headers={
        "Authorization": f"Bearer {os.environ['INFI_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "legalName": "Fornecedor XYZ LTDA",
        "document": "12345678000199",
        "documentType": "cnpj",
        "pixKey": "12345678000199",
        "pixKeyType": "cnpj",
        "label": "Fornecedor recorrente",
    },
)
data = res.json()  # {"recipientId": "...", "status": "pending_review", ...}

<?php
$client = new GuzzleHttp\Client();
$res = $client->post('https://api.internationalfinance.com.br/v1/recipients', [
  'headers' => [
    'Authorization' => 'Bearer ' . getenv('INFI_API_KEY'),
    'Content-Type'  => 'application/json',
  ],
  'json' => [
    'legalName'    => 'Fornecedor XYZ LTDA',
    'document'     => '12345678000199',
    'documentType' => 'cnpj',
    'pixKey'       => '12345678000199',
    'pixKeyType'   => 'cnpj',
    'label'        => 'Fornecedor recorrente',
  ],
]);
$data = json_decode($res->getBody(), true);

Listar destinatários autorizados Listar transações