Registrar destinatario autorizado

POST/v1/recipients

Envía un destinatario tercero (CPF/CNPJ distinto del titular) para análisis. NO aprueba — el retiro a ese destinatario solo se libera tras aprobación de compliance de INFI.

Registrar no libera retiro

Este endpoint solo registra el destinatario para análisis (status: "pending_review"). No aprueba y no mueve dinero. El destinatario solo puede recibir retiro tras la verificación (KYC/AML) y activación por INFI — momento en que aparece en GET /v1/recipients y puede usarse en POST /v1/withdraw vía recipientId.

Cuándo usar

Solo necesitas este flujo si retiras a CPFs/CNPJs distintos del titular de la cuenta (p.ej. pagar proveedores/socios recurrentes). Para retirar a ti mismo, omite recipientId en /v1/withdraw — no necesitas registrar nada.

Encabezados

Encabezado	Obligatorio	Descripción
`Authorization`	sí	`Bearer <TU_API_KEY>`
`Content-Type`	sí	`application/json`

Cuerpo de la solicitud

Campo	Tipo	Obligatorio	Descripción
`legalName`	string	sí	Razón social o nombre del destinatario (2–120 caracteres).
`document`	string	sí	CPF (11 dígitos) o CNPJ (14 dígitos). Se ignora la puntuación.
`documentType`	string	sí	`cpf` o `cnpj`. Acepta variaciones de case/whitespace (`"CNPJ"` → `"cnpj"`).
`pixKey`	string	sí	Clave PIX del destinatario.
`pixKeyType`	string	sí	`cpf`, `cnpj`, `email`, `phone` o `evp`.
`label`	string	no	Alias libre para tu referencia (hasta 80 caracteres).

Name-match (anti-fraude)

Si pixKeyType es cpf o cnpj, la clave debe coincidir con el document informado (mismos dígitos y mismo tipo). Para email/phone/evp, el titular de la clave se valida en la infraestructura PIX en el momento del retiro.

Respuesta `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	Descripción
`recipientId`	24 caracteres hex, determinístico por el documento. Guárdalo; es el mismo que usarás en `POST /v1/withdraw`.
`status`	`pending_review` (en análisis) o `active` (ya aprobado — ver idempotencia).
`note`	Mensaje legible que refuerza que el registro no libera retiro.

200 OK (en vez de 201) cuando el destinatario ya existía — ver idempotencia abajo.

Idempotencia

El recipientId se deriva del document (hash determinístico). Reenviar el mismo documento es seguro:

Ya en análisis → devuelve el mismo recipientId con status: "pending_review" (no duplica).
Ya aprobado (active) → devuelve status: "active" y no rebaja la aprobación.
Anteriormente rechazado/removido → reactiva como pending_review (nuevo análisis), actualizando los datos enviados.

No hay campo externalRef aquí — la idempotencia es por el documento mismo.

Límite

Cada cuenta tiene un tope de destinatarios activos + en análisis (por defecto 10). Alcanzado el tope, los nuevos registros devuelven 422. ¿Necesitas más? Habla con soporte — el límite se ajusta por cuenta tras evaluación.

Errores

HTTP	`error` (ejemplos)
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 del endpoint)

Flujo completo

POST /v1/recipients — envías el destinatario → pending_review.
Análisis de INFI (KYC/AML) → la aprobación activa al destinatario.
GET /v1/recipients — el destinatario aprobado aparece en el listado con recipientId.
POST /v1/withdraw con recipientId — retiro liberado al destinatario aprobado.

Ejemplos

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": "Proveedor recurrente"
  }'

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: 'Proveedor recurrente',
  }),
})
const { recipientId, status } = await res.json()
// status === 'pending_review' — espera la aprobación antes de retirar.

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": "Proveedor recurrente",
    },
)
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'        => 'Proveedor recurrente',
  ],
]);
$data = json_decode($res->getBody(), true);

Iniciar retiro PIX Listar destinatarios autorizados