Subcontas | Dom Docs

Subcontas permitem que plataformas credenciadas criem e gerenciem contas filhas, cada uma com seu próprio token de autenticação para realizar transações de forma independente.

[!IMPORTANT] Este recurso exige credenciamento prévio com a Dom Pagamentos. Entre em contato com seu gerente de contas para habilitar o acesso.

Casos de uso

Marketplace — cada vendedor tem sua subconta; você controla o repasse financeiro
Plataforma SaaS — cada cliente da sua plataforma opera com sua própria conta Dom

Crie a subconta

Envie os dados da empresa ou pessoa para `POST /subaccount`. A subconta é criada com status `pending`.

Aguarde a análise

A Dom analisa o cadastro e atualiza o status para `approved` ou `rejected`.

Use o token da subconta

Ao criar a subconta, a API retorna um `token` único. Use-o como chave de API para transações da subconta.

Configure o modo de repasse

Defina se os valores das transações são repassados `automatic` (imediatamente) ou `manual` (você controla quando transferir).

Passo 1 — Criar uma subconta

curl --request POST \
  --url "{apiUrl}/subaccount" \
  --header "Authorization: Bearer {token}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Loja do João",
    "document": "12345678000190",
    "email": "joao@loja.com",
    "phone": "11999990000"
  }'

[!WARNING] O campo token da subconta é retornado apenas na criação. Armazene-o de forma segura — não há como recuperá-lo posteriormente.

Status da subconta

Status	Descrição
`pending`	Aguardando análise de risco
`approved`	Aprovada e apta para transacionar
`rejected`	Reprovada pela análise
`blocked`	Bloqueada para operações
`cancelled`	Cancelada permanentemente

Passo 2 — Consultar status

curl --request GET \
  --url "{apiUrl}/subaccount/{id}" \
  --header "Authorization: Bearer {token}"

Passo 3 — Configurar modo de repasse

curl --request PUT \
  --url "{apiUrl}/subaccount/{id}/change/financial-transfer" \
  --header "Authorization: Bearer {token}" \
  --header "Content-Type: application/json" \
  --data '{ "financial_transfer": "automatic" }'

Modo	Descrição
`automatic`	Valores repassados automaticamente após compensação
`manual`	Você controla quando transferir o saldo para a subconta

Testando em Sandbox

Use esses CNPJs para simular diferentes status de aprovação:

CNPJ	Status retornado
`21111111111111`	`pending`
`31111111111111`	`rejected`

Próximos passos

Subcontas — referência completa da API
Testando em Sandbox — dados de teste disponíveis