Destinatário

Um Destinatário (beneficiário) é a pessoa ou empresa que recebe os fundos. Destinatários são criados usando os mesmos endpoints de participantes que os remetentes — o sistema distingue os papéis com base em como o participantId é usado em uma transação (campo recipientId).

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}/people
Autenticação: Nível de tenant (x-api-key)

Exemplo: Destinatário Brasileiro

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/people \
  --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/people \
  --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 Participantes

Participantes são entidades reutilizáveis:

• Uma pessoa criada como destinatário pode depois ser usada como remetente (se atender aos requisitos de conformidade)
• Uma pessoa pode atuar como remetente e destinatário na mesma transação (envio para si mesmo) passando o mesmo participantId tanto em senderId quanto em recipientId
• Um participante só precisa ser criado uma vez e pode ser referenciado em transações futuras ilimitadas

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.