Subcontas

Este guia explica como criar e operar subcontas pela API pública. Use este documento antes da referência de endpoints.

​

Pré-requisitos

1. Obtenha client-id e client-secret. Veja Autenticação.
2. Gere um UUID v4 novo para cada criação lógica (x-idempotency-key).

​

Escolher o caminho de criação

Existem 3 caminhos. Escolha um por subconta. NOTA: Não misture os caminhos para a mesma subconta. Se iniciou pelo onboarding assíncrono, continue com registration_id até o fim.

​

Identificadores

NOTA: registration_id não substitui internalId. Depois que a subconta existe, use internalId nos endpoints /v1/submerchants/....

​

Dois tipos de status

Não confunda os endpoints de status. Use o status de onboarding somente depois de POST /v2/.../onboarding/pf|pj. Use o status da subconta somente quando já tiver internalId.

​

Onboarding assíncrono (PF ou PJ)

1. Envie o cadastro com documentos em POST /v2/submerchants/onboarding/pf ou POST /v2/submerchants/onboarding/pj.
2. Guarde o registration_id da resposta 202.
3. Consulte GET /v2/submerchants/onboarding/{registrationId}/status até sair de processing.
4. Se status for action_required e can_resubmit for true, reenvie documentos em POST /v2/submerchants/onboarding/{registrationId}/resend-documents.
5. Se status for rejected e can_resubmit for false, contate o suporte.
6. Se status for approved, a subconta está pronta para operação.
7. Obtenha o internalId: liste com GET /v1/submerchants filtrando pelo documento do cadastro (cnpj na query). O campo id da resposta é o internalId.

NOTA: O endpoint de status do onboarding não retorna internalId. Use a listagem pelo documento depois de approved.

​

Decisão após consultar o status

ATENÇÃO: Se can_resubmit for false, o reenvio retorna 409. Consulte o status antes de chamar o endpoint de reenvio. NOTA: A resposta 202 do submit ou do reenvio pode trazer um status intermediário. Para decidir a próxima ação, use sempre o endpoint de consulta de status do onboarding.

​

Link hospedado

1. Chame POST /v2/submerchants/links.
2. Entregue a url ao usuário final.
3. Consulte o link ativo em GET /v2/submerchants/links quando precisar.

NOTA: Se já existir link ativo, o POST reutiliza esse link. Se o ativo estiver expirado, o POST cria um novo.

​

Depois da criação

Com internalId da subconta: NOTA: Alterações de conta bancária e de chave PIX ficam pendentes até aprovação. O endpoint cria a solicitação; a mudança não é imediata.

​

Documentos de verificação

No onboarding assíncrono e no reenvio:

1. Envie documentoFrente e documentoVerso, ou envie cnhCompleta.
2. Envie selfie.
3. Não use o campo selfieComDocumento.

Em PJ, no submit inicial, envie também contratoSocial e cartaoCnpj. No reenvio, não envie contratoSocial nem cartaoCnpj. ATENÇÃO: Fotos borradas, escuras ou cortadas podem gerar action_required. Reenvie imagens nítidas quando can_resubmit for true.

​

Referência