Listar destinatários autorizados

GET/v1/recipients

Lista os destinatários terceiros pré-aprovados pelo time INFI para sua conta. Use os recipientId retornados em POST /v1/withdraw.

Quando usar

Você só precisa deste endpoint se sacar para CPFs/CNPJs diferentes do titular da sua conta. Para sacar pra você mesmo, omita recipientId no /v1/withdraw — comportamento padrão.

Cabeçalhos

Cabeçalho	Obrigatório	Descrição
`Authorization`	sim	`Bearer <SUA_API_KEY>`

Resposta `200 OK`

{
  "recipients": [
    {
      "recipientId": "abc123def456abc123def456",
      "legalName": "Fornecedor XYZ LTDA",
      "documentType": "cnpj",
      "documentMasked": "**.***.***/****-99",
      "label": "Fornecedor recorrente",
      "approvedAt": 1715000000000
    }
  ],
  "count": 1
}

Campo	Descrição
`recipientId`	24 chars hex. Use exatamente como veio em `POST /v1/withdraw`.
`legalName`	Razão social ou nome do destinatário.
`documentType`	`cpf` ou `cnpj`.
`documentMasked`	Documento mascarado (LGPD). Você já conhece quem aprovou — útil só pra UX/logs.
`label`	Apelido livre que o time INFI atribuiu na aprovação. Pode ser `null`.
`approvedAt`	Unix timestamp em milissegundos quando foi aprovado.
`count`	Total de destinatários ativos. Limite de 10 por conta.

A lista contém apenas destinatários ativos. Destinatários desativados pelo time (via auditoria/compliance) não aparecem aqui — tentar usar um recipientId desativado em /v1/withdraw retorna 422.

Como cadastrar um novo destinatário

Use POST /v1/recipients para submeter um destinatário (nome legal + CPF/CNPJ + chave PIX). Ele entra como pending_review — cadastrar não aprova.

Cada aprovação passa por compliance/AML da INFI. Após aprovado, o recipientId aparece nesta listagem (apenas ativos) em até alguns minutos e pode ser usado em POST /v1/withdraw.

Erros

HTTP	`error`
401	`"API key inválida ou revogada."`
403	`"IP de origem não autorizado..."`

Exemplos

curl https://api.internationalfinance.com.br/v1/recipients \
  -H "Authorization: Bearer $INFI_API_KEY"

const res = await fetch('https://api.internationalfinance.com.br/v1/recipients', {
  headers: { Authorization: `Bearer ${process.env.INFI_API_KEY}` },
})
const { recipients } = await res.json()
 
// Use o recipientId em /v1/withdraw para sacar pro destinatário aprovado:
const supplier = recipients.find(r => r.label === 'Fornecedor X')
if (!supplier) throw new Error('destinatário não cadastrado — peça aprovação')
 
await fetch('https://api.internationalfinance.com.br/v1/withdraw', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.INFI_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amountCents: 50000,
    pixKey: '12345678000199',
    pixKeyType: 'cnpj',
    recipientId: supplier.recipientId,
    externalRef: 'pagamento-fornecedor-X-2026-05',
  }),
})

import os, requests
 
res = requests.get(
    "https://api.internationalfinance.com.br/v1/recipients",
    headers={"Authorization": f"Bearer {os.environ['INFI_API_KEY']}"},
)
data = res.json()
recipients = data["recipients"]

<?php
$client = new GuzzleHttp\Client();
$res = $client->get('https://api.internationalfinance.com.br/v1/recipients', [
  'headers' => ['Authorization' => 'Bearer ' . getenv('INFI_API_KEY')],
]);
$data = json_decode($res->getBody(), true);
$recipients = $data['recipients'];

Iniciar saque PIX Cadastrar destinatário autorizado