List authorized recipients

GET/v1/recipients

Lists third-party recipients pre-approved by the INFI team for your account. Use the returned recipientId in POST /v1/withdraw.

When to use

You only need this endpoint if you withdraw to CPFs/CNPJs different from the account holder. To withdraw to yourself, omit recipientId in /v1/withdraw — that is the default behavior.

Headers

Header	Required	Description
`Authorization`	yes	`Bearer <YOUR_API_KEY>`

Response `200 OK`

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

Field	Description
`recipientId`	24 hex chars. Use exactly as returned in `POST /v1/withdraw`.
`legalName`	Legal name of the recipient.
`documentType`	`cpf` or `cnpj`.
`documentMasked`	Masked document (LGPD). You already know who approved it — useful only for UX/logs.
`label`	Free-form alias assigned by the INFI team at approval. May be `null`.
`approvedAt`	Unix timestamp in milliseconds when it was approved.
`count`	Total active recipients. Limit of 10 per account.

The list contains active recipients only. Recipients deactivated by the team (via audit/compliance) do not appear here — trying to use a deactivated recipientId in /v1/withdraw returns 422.

How to register a new recipient

Use POST /v1/recipients to submit a recipient (legal name + CPF/CNPJ + PIX key). It enters as pending_review — registering does not approve.

Each approval goes through INFI’s compliance/AML. Once approved, the recipientId appears in this listing (active only) within a few minutes and can be used in POST /v1/withdraw.

Errors

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

Examples

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 the recipientId in /v1/withdraw to pay the approved recipient:
const supplier = recipients.find(r => r.label === 'Fornecedor X')
if (!supplier) throw new Error('recipient not registered — request approval')
 
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: 'supplier-payment-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'];