Destinatário

Um Destinatário (beneficiário) é a pessoa ou empresa que recebe os fundos. Destinatários são criados no seu próprio endpoint por papel, POST /v2/beneficiaries, que registra a pessoa com o papel BENEFICIARY. Os remetentes têm um endpoint paralelo, POST /v2/senders.

⚠️ Os endpoints /people estão obsoletos. Integrações anteriores criavam remetentes e destinatários pelo endpoint compartilhado POST /people e deixavam o papel ser inferido de como o ID era usado em uma transação. Esse modelo foi superado — crie destinatários em POST /v2/beneficiaries e remetentes em POST /v2/senders. As rotas legadas /people e /v2/people continuam ativas para a migração (ambas estampam SENDER), então não podem criar um beneficiário — use a rota por papel.

Criação de Destinatário Orientada por Esquema

Os requisitos de dados do destinatário variam conforme o país de destino. Antes de coletar dados do usuário, sempre busque o esquema de destinatário:

curl --request GET \
  --url https://{FQDN}/organizations/$TENANT/payout/recipients/schema/co \
  --header "x-api-key: $API_KEY" \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY"

Isso retorna um JSON Schema (draft-07) definindo exatamente quais campos são obrigatórios para aquele país. Veja Esquema de Destinatário para detalhes.

Criando um Destinatário

Endpoint: POST /organizations/{tenant}/v2/beneficiaries
Autenticação: Nível de tenant (x-api-key)

O formato da requisição corresponde ao do endpoint de remetente — beneficiários também são linhas de persons, distinguidas apenas pelo papel — e executa o mesmo pipeline de validação de documentos. Uma criação retorna 201 (ou 200 se já existir uma pessoa com o mesmo externalId).

Exemplo: Destinatário Brasileiro

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/v2/beneficiaries \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $API_KEY" \
  --data '{
  "firstName": "Maria",
  "lastName": "Silva",
  "phoneNumber": "+5511999998888",
  "documents": [
    {
      "type": "cpf",
      "document": "12345678901",
      "countryCode": "BR"
    }
  ]
}'

Exemplo: Destinatário Colombiano

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/v2/beneficiaries \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $API_KEY" \
  --data '{
  "firstName": "Carlos",
  "lastName": "Gutierrez",
  "phoneNumber": "+573001234567",
  "address": {
    "countryCode": "CO",
    "city": "Bogotá",
    "line1": "Calle 100 #15-20"
  },
  "documents": [
    {
      "type": "cc",
      "document": "1234567890",
      "countryCode": "CO"
    }
  ]
}'

Guarde o id retornado — este é o recipientId usado na transação.

Tipos de Documento Específicos por País

Sempre consulte o esquema de destinatário para obter a lista oficial de tipos de documento aceitos por país.

Reutilizando Destinatários

Um destinatário só precisa ser criado uma vez e pode ser referenciado como o recipientId em transações futuras ilimitadas.

Uma pessoa é criada com um único papel. Se o mesmo indivíduo precisar enviar e receber, crie-o uma vez em cada endpoint (/v2/senders e /v2/beneficiaries) — o papel de remetente carrega as obrigações completas de KYC/conformidade, enquanto o papel de beneficiário se limita a receber payouts.

Depois de Criar o Destinatário

Depois de ter o recipientId, o próximo passo é vincular uma conta bancária:

1. Busque o esquema da conta — GET /payout/recipientAccounts/schema/{countryCode}
2. Busque a lista de bancos (se necessário) — GET /payout/{countryCode}/banks
3. Crie a conta do destinatário — POST /payout/participants/{recipientId}/recipientAccounts/gateway

Veja Conta do Destinatário para todos os detalhes.

Boas Práticas

• Sempre use o endpoint de esquema para determinar os campos obrigatórios — não fixe requisitos de campos por país no código.
• Renderize formulários dinamicamente com base na resposta do esquema para suportar novos países automaticamente.
• Colete apenas os campos obrigatórios — enviar dados desnecessários pode disparar verificações adicionais de conformidade.
• Valide a entrada no lado do cliente usando as restrições pattern, minLength e enum do esquema antes de enviar.
• Trate o requisito de address — alguns países exigem endereço do destinatário, outros não. O esquema é a sua fonte de verdade.