Conta do Destinatário

Uma Conta do Destinatário representa a conta bancária ou o destino de payout onde os fundos serão entregues. Antes de criar uma conta de destinatário, você deve primeiro criar o destinatário como participante e consultar o schema da conta para o país de destino.

Criação Orientada por Schema

Os requisitos da conta do destinatário variam por país. Sempre consulte o schema da conta antes de construir seu formulário ou chamada de API:

# Consultar o schema de conta para a Colômbia
curl --request GET \
  --url https://{FQDN}/organizations/$TENANT/payout/recipientAccounts/schema/co \
  --header "x-api-key: $API_KEY" \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY"

O schema retorna um objeto JSON Schema (draft-07) que define os campos obrigatórios, os valores permitidos e as regras de validação. Os campos comuns incluem:

Dica: Para países que exigem um bankCode, use o endpoint Bancos em um País para popular um dropdown na sua interface.

Criando uma Conta de Destinatário

Endpoint: POST /organizations/{tenant}/payout/participants/{participantId}/recipientAccounts/gateway
Autenticação: Nível de agente (x-api-key + x-agent-id + x-agent-api-key)

Corpo da Requisição

Campos por tipo de método de payout:

O schema da conta de cada país é a fonte da verdade sobre quais tipos e campos seu corredor suporta.

Exemplo: Colômbia (Depósito Bancário)

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/payout/participants/$RECIPIENT_ID/recipientAccounts/gateway \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $API_KEY" \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY" \
  --data '{
  "externalId": "acct-co-001",
  "asset": "COP",
  "payoutMethod": {
    "type": "BANK_DEPOSIT",
    "countryCode": "CO",
    "bankCode": "1001",
    "routingNumber": "1234",
    "accountNumber": "9876543210",
    "accountType": "SAVINGS"
  }
}'

Exemplo: México (CLABE)

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/payout/participants/$RECIPIENT_ID/recipientAccounts/gateway \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $API_KEY" \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY" \
  --data '{
  "externalId": "acct-mx-001",
  "asset": "MXN",
  "payoutMethod": {
    "type": "BANK_DEPOSIT",
    "countryCode": "MX",
    "bankCode": "002",
    "routingNumber": "002",
    "accountNumber": "012345678901234567",
    "accountType": "CHECKING"
  }
}'

Exemplo: Peru (Depósito Bancário)

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/payout/participants/$RECIPIENT_ID/recipientAccounts/gateway \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $API_KEY" \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY" \
  --data '{
  "externalId": "acct-pe-001",
  "asset": "PEN",
  "payoutMethod": {
    "type": "BANK_DEPOSIT",
    "countryCode": "PE",
    "bankCode": "BINPPEPL",
    "routingNumber": "1234",
    "accountNumber": "1345",
    "accountType": "CHECKING"
  }
}'

Guarde o id retornado — este é o recipientAccountId necessário ao criar uma transação.

Consultando uma Conta de Destinatário

Endpoint: GET /organizations/{tenant}/payout/recipientAccounts/{recipientAccountId}
Autenticação: Nível de agente

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

Os campos sensíveis (accountNumber, routingNumber, key do PIX) são retornados mascarados — os valores completos nunca são expostos após a criação.

Excluindo uma Conta de Destinatário

Endpoint: DELETE /organizations/{tenant}/payout/recipientAccounts/{recipientAccountId}
Autenticação: Nível de agente

curl --request DELETE \
  --url https://{FQDN}/organizations/$TENANT/payout/recipientAccounts/$ACCOUNT_ID \
  --header "x-api-key: $API_KEY" \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY"

Retorna 204 No Content.

Requisitos Específicos por País

Sempre use o endpoint de schema como fonte da verdade — a tabela acima é apenas orientativa.

Fluxo de Integração

1. Consultar o schema da conta  →  GET /payout/recipientAccounts/schema/{countryCode}
2. Consultar a lista de bancos  →  GET /payout/{countryCode}/banks (se bankCode for obrigatório)
3. Coletar os dados do usuário  →  Construir o formulário a partir do schema
4. Criar a conta                →  POST /payout/participants/{id}/recipientAccounts/gateway
5. Salvar o ID da conta         →  Usar em POST /fx/transactions

Todos os Endpoints

Documentação Interativa da API