> ## Documentation Index > Fetch the complete documentation index at: https://developers.uvvipay.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Subcontas > Como criar e operar subcontas pela API pública: caminhos de criação, status e identificadores 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](/authentication). 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. | Caminho | Endpoint | Resposta | Quando usar | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | ----------------------------------------------------------- | | Criação direta | [`POST /v1/submerchants`](/api-reference/submerchants/create) | `201` com `id` | Seu backend envia dados e documentos e já recebe a subconta | | Onboarding assíncrono | [`POST /v2/submerchants/onboarding/pf`](/api-reference/submerchants/onboarding-pf) ou [`/pj`](/api-reference/submerchants/onboarding-pj) | `202` com `registration_id` | Seu backend inicia o cadastro e consulta o resultado depois | | Link hospedado | [`POST /v2/submerchants/links`](/api-reference/submerchants/create-onboarding-link) | `201` com `url` | O usuário final preenche o formulário na URL retornada | **NOTA:** Não misture os caminhos para a mesma subconta. Se iniciou pelo onboarding assíncrono, continue com `registration_id` até o fim. ## Identificadores | Campo | Origem | Uso | | ------------------- | ----------------------------------------------------- | ----------------------------------------------------------------- | | `id` | Resposta de `POST /v1/submerchants` | Identifica a subconta criada | | `internalId` | Path ou query em endpoints `/v1/submerchants/...` | Mesmo identificador UUID da subconta nas consultas e atualizações | | `registration_id` | Resposta de `POST /v2/submerchants/onboarding/pf\|pj` | Identifica o processo de onboarding até a conclusão | | `x-idempotency-key` | Header no create e no onboarding | Evita duplicar a mesma criação lógica | **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. | Endpoint | O que mede | Valores típicos | | -------------------------------------------------------------------------------------------------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | [`GET /v2/submerchants/onboarding/{registrationId}/status`](/api-reference/submerchants/get-onboarding-status) | Processo de onboarding assíncrono | `processing`, `approved`, `rejected`, `action_required` | | [`GET /v1/submerchants/status`](/api-reference/submerchants/get-status) | Subconta já criada | `pending`, `documentation_pending`, `onboarding`, `kyc_approved`, `kyc_rejected`, `active`, `inactive`, `blocked` | 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`](/api-reference/submerchants/onboarding-pf) ou [`POST /v2/submerchants/onboarding/pj`](/api-reference/submerchants/onboarding-pj). 2. Guarde o `registration_id` da resposta `202`. 3. Consulte [`GET /v2/submerchants/onboarding/{registrationId}/status`](/api-reference/submerchants/get-onboarding-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`](/api-reference/submerchants/resend-onboarding-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`](/api-reference/submerchants/list) 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 | `status` | `can_resubmit` | Ação | | ----------------- | -------------- | ------------------------------------------- | | `processing` | `false` | Aguarde e consulte de novo | | `approved` | `false` | Liste a subconta e opere com o `internalId` | | `action_required` | `true` | Reenvie documentos | | `rejected` | `false` | Contate o suporte. Não reenvie | **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`](/api-reference/submerchants/create-onboarding-link). 2. Entregue a `url` ao usuário final. 3. Consulte o link ativo em [`GET /v2/submerchants/links`](/api-reference/submerchants/get-onboarding-link) 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: | Objetivo | Endpoint | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | Consultar dados | [`GET /v1/submerchants/{internalId}`](/api-reference/submerchants/get) | | Consultar status | [`GET /v1/submerchants/status`](/api-reference/submerchants/get-status) | | Atualizar dados | [`PATCH /v1/submerchants/{internalId}`](/api-reference/submerchants/update) | | Consultar taxas | [`GET /v1/submerchants/{internalId}/fees`](/api-reference/submerchants/get-fees) | | Atualizar taxas | [`PATCH /v1/submerchants/{internalId}/fees`](/api-reference/submerchants/update-fees) | | Consultar conta bancária | [`GET /v1/submerchants/{internalId}/bank-account`](/api-reference/submerchants/get-bank-account) | | Solicitar alteração bancária | [`PATCH /v1/submerchants/{internalId}/bank-account/account-data`](/api-reference/submerchants/request-account-data-change) | | Solicitar alteração de PIX | [`PATCH /v1/submerchants/{internalId}/bank-account/pix-key`](/api-reference/submerchants/request-pix-key-change) | | Consultar saldo | [`GET /v1/submerchants/{internalId}/balance`](/api-reference/submerchants/get-balance) | | Solicitar saque | [`POST /v1/submerchants/withdrawals`](/api-reference/submerchants/request-withdrawal) | **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 Criação direta via API Onboarding assíncrono pessoa física Onboarding assíncrono pessoa jurídica Consultar processamento e reenvio Dividir valor entre subcontas