Listar destinatarios autorizados

GET/v1/recipients

Lista los destinatarios terceros pre-aprobados por el equipo INFI para tu cuenta. Usa los recipientId devueltos en POST /v1/withdraw.

Cuándo usar

Solo necesitas este endpoint si retiras a CPFs/CNPJs distintos del titular de tu cuenta. Para retirar a ti mismo, omite recipientId en /v1/withdraw — es el comportamiento por defecto.

Encabezados

Encabezado	Obligatorio	Descripción
`Authorization`	sí	`Bearer <TU_API_KEY>`

Respuesta `200 OK`

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

Campo	Descripción
`recipientId`	24 caracteres hex. Úsalo exactamente como vino en `POST /v1/withdraw`.
`legalName`	Razón social o nombre del destinatario.
`documentType`	`cpf` o `cnpj`.
`documentMasked`	Documento enmascarado (LGPD). Ya conoces a quién aprobaste — útil solo para UX/logs.
`label`	Alias libre que el equipo INFI asignó en la aprobación. Puede ser `null`.
`approvedAt`	Timestamp Unix en milisegundos cuando fue aprobado.
`count`	Total de destinatarios activos. Límite de 10 por cuenta.

La lista contiene solo destinatarios activos. Los destinatarios desactivados por el equipo (vía auditoría/compliance) no aparecen aquí — intentar usar un recipientId desactivado en /v1/withdraw devuelve 422.

Cómo registrar un nuevo destinatario

Usa POST /v1/recipients para enviar un destinatario (nombre legal + CPF/CNPJ + clave PIX). Entra como pending_review — registrar no aprueba.

Cada aprobación pasa por compliance/AML de INFI. Tras la aprobación, el recipientId aparece en este listado (solo activos) en pocos minutos y puede usarse en POST /v1/withdraw.

Errores

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

Ejemplos

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()
 
// Usa el recipientId en /v1/withdraw para pagar al destinatario aprobado:
const supplier = recipients.find(r => r.label === 'Fornecedor X')
if (!supplier) throw new Error('destinatario no registrado — solicita aprobación')
 
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: 'pago-proveedor-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'];

Registrar destinatario Listar transacciones