Register an authorized recipient

POST/v1/recipients

Submits a third-party recipient (CPF/CNPJ different from the account holder) for review. Does NOT approve — withdrawals to this recipient are only enabled after INFI's compliance approval.

Registering does not enable withdrawals

This endpoint only records the recipient for review (status: "pending_review"). It does not approve and does not move money. The recipient can only receive a withdrawal after INFI completes verification (KYC/AML) and activates it — at which point it appears in GET /v1/recipients and can be used in POST /v1/withdraw via recipientId.

When to use

You only need this flow if you withdraw to CPFs/CNPJs different from the account holder (e.g., paying recurring suppliers/partners). To withdraw to yourself, omit recipientId in /v1/withdraw — no registration needed.

Headers

Header	Required	Description
`Authorization`	yes	`Bearer <YOUR_API_KEY>`
`Content-Type`	yes	`application/json`

Request body

Field	Type	Required	Description
`legalName`	string	yes	Legal name of the recipient (2–120 chars).
`document`	string	yes	CPF (11 digits) or CNPJ (14 digits). Punctuation is ignored.
`documentType`	string	yes	`cpf` or `cnpj`. Accepts case/whitespace variations (`"CNPJ"` → `"cnpj"`).
`pixKey`	string	yes	The recipient’s PIX key.
`pixKeyType`	string	yes	`cpf`, `cnpj`, `email`, `phone` or `evp`.
`label`	string	no	Free-form alias for your reference (up to 80 chars).

Name-match (anti-fraud)

If pixKeyType is cpf or cnpj, the key must match the document sent (same digits and type). For email/phone/evp, the key holder is validated against the PIX infrastructure at withdrawal time.

Response `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."
}

Field	Description
`recipientId`	24 hex chars, deterministic by document. Save it; it is the same used in `POST /v1/withdraw`.
`status`	`pending_review` (under review) or `active` (already approved — see idempotency).
`note`	Human-readable message reinforcing that registration does not enable withdrawals.

200 OK (instead of 201) when the recipient already existed — see idempotency below.

Idempotency

The recipientId is derived from document (deterministic hash). Resending the same document is safe:

Already under review → returns the same recipientId with status: "pending_review" (no duplicates).
Already approved (active) → returns status: "active" and does not downgrade the approval.
Previously rejected/removed → reactivates as pending_review (new review), updating the data you sent.

There is no externalRef here — idempotency is by the document itself.

Limit

Each account has a ceiling on active + under review recipients (default 10). When the limit is hit, new registrations return 422. Need more? Contact support — the limit is adjustable per account after review.

Errors

HTTP	`error` (examples)
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."` (endpoint rate limit)

End-to-end flow

POST /v1/recipients — you submit the recipient → pending_review.
INFI review (KYC/AML) → approval activates the recipient.
GET /v1/recipients — the approved recipient appears in the list with recipientId.
POST /v1/withdraw with recipientId — withdrawal enabled to the approved recipient.

Examples

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": "Recurring supplier"
  }'

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: 'Recurring supplier',
  }),
})
const { recipientId, status } = await res.json()
// status === 'pending_review' — wait for approval before withdrawing.

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

Initiate a PIX withdrawal List authorized recipients