> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mingopay.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Subcontas

> Separe os recebimentos de lojas e vendedores com saldos próprios dentro da sua operação.

Cada subconta pertence à sua organização e ao ambiente da chave de API. Ela separa cobranças, saldo disponível e valores reservados, sem criar outro login ou uma conta bancária independente.

O saldo retornado por `GET /v1/balance` não inclui os saldos das subcontas. Uma subconta não pode criar outras subcontas.

## Permissões

Use uma chave Bearer no servidor, conforme o guia de [autenticação](https://docs.mingopay.com.br/documentation/authentication.md).

| Operação | Escopo |
| - | - |
| Listar, consultar, sincronizar e consultar extrato | `subaccounts:read` |
| Criar, editar ou desativar uma subconta | `subaccounts:write` |
| Criar cobrança com `subaccountId` | `payment_intents:write` |

Sandbox e produção usam as mesmas rotas. O prefixo `mp_test_` ou `mp_live_` determina o ambiente. Use sempre o UUID da MingoPay, retornado no campo `id`, para identificar a subconta.

## Criar uma subconta

No [SDK oficial](https://docs.mingopay.com.br/documentation/sdk.md), use `mingo.subaccounts.create(...)`. Para receber nela, use `mingo.paymentIntents.create(...)` enviando `subaccountId`. O SDK também oferece consulta, edição, sincronização, extrato e listagem de cobranças.

```bash theme={"system"}
curl -X POST "https://api.mingopay.com.br/v1/subaccounts" \
  -H "Authorization: Bearer $MINGOPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Loja Centro","email":"financeiro@example.com","externalReference":"loja-centro"}'
```

| Campo | Obrigatório | Regra |
| - | - | - |
| `name` | Sim | De 2 a 100 caracteres |
| `externalReference` | Não | De 1 a 100 caracteres, única por organização e ambiente; gerada quando omitida |
| `email` | Não | E-mail válido, com até 254 caracteres |

A resposta `201` contém a subconta. Guarde seu `id` para criar cobranças e consultar movimentos. `name` e `externalReference` não aceitam HTML. O `email`, quando informado, precisa ser de um domínio permanente: typos de Gmail e provedores parecidos, e-mails descartáveis e domínios sem entrega são recusados.

Somente o nome é obrigatório. Para integrações, informe uma `externalReference` estável antes da primeira tentativa. Sem ela, repetir a criação pode criar outra subconta. Repetir a referência recupera o cadastro e não reaplica alterações de taxas ou limites; use `PATCH` para editar.

Repetir `externalReference` com o mesmo nome e e-mail recupera o vínculo existente. Enviar outros dados com a mesma referência retorna `409 subaccount_reference_conflict`. A criação não exige o cabeçalho `Idempotency-Key`; sua referência é a chave de deduplicação dessa operação.

Se o provedor falhar depois de o cadastro ser salvo, consulte a referência pela listagem e sincronize o vínculo. Não gere outra referência para repetir a mesma criação.

## Listar e consultar

```bash theme={"system"}
curl "https://api.mingopay.com.br/v1/subaccounts?search=loja-centro&status=active&limit=20&offset=0" \
  -H "Authorization: Bearer $MINGOPAY_API_KEY"
```

A listagem retorna `data`, `total`, `limit`, `offset`, `environment`, `permissions` e `globalFees`.

| Parâmetro | Regra |
| - | - |
| `search` | Busca por nome, e-mail ou referência, com até 120 caracteres |
| `status` | `all`, `active` ou `inactive`; padrão `all` |
| `limit` | De 1 a 100; padrão 20 |
| `offset` | De 0 a 1000000; padrão 0 |

Para consultar uma subconta, use `GET /v1/subaccounts/{id}`. A chave só acessa subcontas da própria organização e ambiente.

## Criar uma cobrança para a subconta

Envie `subaccountId` em `POST /v1/payment-intents`, com uma [Idempotency-Key](https://docs.mingopay.com.br/documentation/idempotency.md) de 16 a 128 caracteres.

```bash theme={"system"}
curl -X POST "https://api.mingopay.com.br/v1/payment-intents" \
  -H "Authorization: Bearer $MINGOPAY_API_KEY" \
  -H "Idempotency-Key: loja-centro-pedido-1024-001" \
  -H "Content-Type: application/json" \
  -d '{"subaccountId":"10000000-0000-4000-8000-000000000001","externalReference":"pedido-1024","amountCents":1000,"method":"pix","payer":{"name":"Cliente Exemplo","taxId":"52998224725"}}'
```

Substitua o UUID do exemplo pelo `id` retornado na criação da sua subconta. Ela deve estar ativa e vinculada ao provedor para receber cobranças em produção.

A resposta contém `pix.copyPasteCode`. Confirme o pagamento por [webhook assinado](https://docs.mingopay.com.br/documentation/webhooks.md), usando `data.subaccountId` para identificar a subconta. A resposta de criação não confirma pagamento.

Você também pode usar `POST /v1/subaccounts/{id}/payment-intents`, com o mesmo corpo, omitindo `subaccountId`. Essa rota exige `subaccounts:read` e `payment_intents:write`, com `Idempotency-Key` de 16 a 128 caracteres seguros. No SDK, use `subaccounts.createPaymentIntent(id, body, { idempotencyKey })`.

O líquido confirmado, após a tarifa da organização, é creditado somente na subconta. Regras automáticas do cofrinho da conta principal não capturam esse recebimento.

## Tarifas da conta e das subcontas

O padrão da MingoPay é R$ 0,40 por Pix recebido e R$ 0,45 por saque Pix, já incluindo o custo do provedor. As subcontas usam as tarifas da organização proprietária; não há uma segunda cobrança da tarifa da conta principal. Condições negociadas por organização podem alterar esses valores.

Em uma cobrança padrão de R$ 100,00, `feeCents` é `40` e `netCents` é `9960`. Com custo de processamento de R$ 0,25, `providerFeeCents` é `25` e `platformFeeCents` é `15`. Em um saque padrão que entrega R$ 100,00 ao destinatário, são descontados R$ 100,45 do saldo selecionado. Os custos do provedor são conciliados pelo backend e não devem ser somados novamente pelo integrador.

Contas novas já recebem as tarifas padrão no cadastro. Alterações de tarifa valem para operações novas; cobranças e saques registrados preservam seus valores.

### Comissão do criador da subconta

A tarifa Mingo e a comissão do criador são separadas. A comissão começa zerada. Não altere tarifas diretamente no vínculo da subconta: a Mingo mantém as tarifas remotas zeradas e aplica os valores registrados em cada operação.

| Configuração | Comportamento |
| - | - |
| `feeMode: "global"` | Padrão; acompanha as comissões globais da organização e ambiente |
| `feeMode: "custom"` | Usa `customFees` desta subconta |
| `saleFeePercent` e `saleFeeFixedCents` | Percentual sobre o valor bruto da cobrança mais valor fixo |
| `payoutFeePercent` e `payoutFeeFixedCents` | Percentual sobre o valor entregue no Pix mais valor fixo |

Percentuais aceitam até duas casas decimais, entre 0 e 100. A parcela percentual é arredondada para baixo em centavos. Valores fixos são inteiros de 0 a 100000000 centavos. Uma cobrança deve deixar líquido positivo após todos os descontos.

Em uma venda de R$ 100,00 com comissão de 3%: R$ 96,60 ficam na subconta, R$ 3,00 são creditados na conta do criador e R$ 0,40 são tarifa Mingo. Desses R$ 0,40, R$ 0,25 cobrem o custo do provedor e R\$ 0,15 são receita Mingo. Não desconte o custo do provedor novamente.

Em um saque que entrega R$ 100,00 com comissão fixa de R$ 0,70: o débito total é R$ 101,15, sendo R$ 0,70 para o criador e R$ 0,45 de tarifa Mingo. Desses R$ 0,45, R$ 0,40 cobrem o custo do provedor e R$ 0,05 são receita Mingo. A comissão só é creditada depois da liquidação; falhas liberam a reserva inteira.

`feeCents` representa todos os descontos, `commissionCents` a comissão do criador, `mingoFeeCents` a tarifa Mingo e `platformFeeCents` a receita Mingo depois do custo do provedor. `netCents = amountCents - feeCents`. Operações antigas preservam os valores registrados.

Consulte `GET /v1/subaccounts/fee-settings` com `subaccounts:read` e atualize via `PUT` com `subaccounts:write`. No painel, use **Taxas globais**. Alterações afetam novas operações; cobranças já criadas e saques já solicitados preservam suas taxas.

```json theme={"system"}
{
  "saleFeePercent": 3,
  "saleFeeFixedCents": 0,
  "payoutFeePercent": 0,
  "payoutFeeFixedCents": 70
}
```

Para definir uma condição própria, envie no `PATCH /v1/subaccounts/{id}`:

```json theme={"system"}
{
  "feeMode": "custom",
  "customFees": {
    "saleFeePercent": 2.5,
    "saleFeeFixedCents": 0,
    "payoutFeePercent": 0,
    "payoutFeeFixedCents": 70
  },
  "blockMode": "none",
  "payoutLimits": {
    "perPayoutCents": 100000,
    "dailyCents": 500000,
    "monthlyCents": 1000000
  }
}
```

### Chave Pix, titular, bloqueios e limites

`pixKey` e `holderTaxId` são opcionais na criação e edição, armazenados com criptografia e retornados somente como `pixKeyMasked` e `holderTaxIdMasked`. Omita para preservar; envie `null` para remover. `email: null` remove o e-mail. O documento valida formato e dígitos verificadores, sem comprovar identidade ou substituir o KYC.

`blockMode: "none"` não adiciona bloqueio, `"payouts"` bloqueia novos saques e `"all"` bloqueia também novas cobranças. Cobranças já emitidas podem ser pagas; Pix já enviados continuam sendo conciliados.

Taxas, bloqueios e limites são regras da MingoPay e podem ser atualizados mesmo quando o provedor de pagamentos está indisponível. Alterações de nome, e-mail ou ativação do vínculo também dependem da confirmação do provedor. Uma falha anterior ao envio do Pix libera a reserva; uma resposta incerta após o envio mantém o valor reservado até a conciliação, sem reenviar o dinheiro.

`payoutLimits` define o débito total máximo por saque, por dia e por mês, incluindo tarifa e comissão. Zero deixa sem limite adicional. Operações agendadas, pausadas, em processamento e concluídas entram no consumo; canceladas e falhas ficam fora. Períodos seguem `America/Sao_Paulo`, com nova conferência na execução. Os limites da conta e do provedor de pagamentos continuam valendo.

Cada subconta retorna `customFees`, `effectiveFees`, `feeMode`, `blockMode` e `payoutLimits`. `effectiveFees` mostra a comissão efetivamente aplicada a novas operações.

## Saldo, extrato e cobranças

| Campo da subconta | Significado |
| - | - |
| `availableCents` | Saldo disponível na MingoPay |
| `reservedCents` | Saldo reservado para solicitações de saque |
| `providerAvailableCents` | Disponível informado pelo provedor; pode ser `null` |
| `providerBlockedCents` | Retido no provedor; pode ser `null` |
| `linked` | Indica se o vínculo está disponível |
| `syncedAt` | Data da última sincronização |
| `syncErrorCode` | Código da última falha de sincronização, quando houver |

Todos os valores monetários são inteiros em centavos. O saldo do provedor é uma consulta auxiliar e não representa um crédito adicional. Retenções podem reduzir o valor sacável.

Use `GET /v1/subaccounts/{id}/transactions?limit=20&offset=0` para o extrato. A resposta inclui `data`, `total`, `limit`, `offset` e `subaccount`. Cada lançamento contém `direction`, `amountCents`, `accountCode`, `description` e `createdAt`.

Use `GET /v1/subaccounts/{id}/payment-intents?limit=20&offset=0` para listar as cobranças. A resposta inclui `data`, `total`, `limit` e `offset`. As duas listagens exigem `subaccounts:read` e usam os mesmos limites de paginação da listagem de subcontas.

## Editar, desativar e sincronizar

| Método e rota | Uso |
| - | - |
| `PATCH /v1/subaccounts/{id}` | Alterar cadastro, comissões, dados de saque, bloqueios e limites, com `subaccounts:write` |
| `POST /v1/subaccounts/{id}/sync` | Recuperar o vínculo e consultar o provedor, com `subaccounts:read` |

Para desativar, envie `{"active":false}` no `PATCH`. Isso impede novas cobranças e preserva o saldo e o histórico. A referência e a organização proprietária não podem ser alteradas.

Para sincronizar, envie o corpo `{}`. A consulta não transfere dinheiro nem cria crédito no saldo da MingoPay.

## Saques pelo painel

Na dashboard, acesse **Movimentações > Subcontas**, abra a subconta e escolha **Sacar**. O débito usa o saldo selecionado e inclui a tarifa de saída da organização. A solicitação passa pelas verificações de identidade, autenticador, disponibilidade e bloqueios da conta principal.

O campo de valor nesta tela informa quanto o destinatário receberá. A revisão mostra a tarifa Mingo, a comissão e o débito total. A chave Pix salva pode ser selecionada sem revelar seu conteúdo completo no navegador. Revise o destino antes de confirmar.

A revisão abre antes de qualquer envio e mostra a chave mascarada, o valor líquido, a tarifa Mingo, a comissão quando houver e o débito total. Você pode voltar para corrigir o destino ou salvar um apelido nos favoritos. Escolher um favorito preenche apenas o destino; valor, confirmação e autenticação continuam obrigatórios.

Contatos são separados por organização e ambiente. A chave fica criptografada no servidor e não é devolvida completa ao navegador. As seções Recentes e Contatos aparecem somente após saques Pix concluídos e mostram apenas destinos com um envio concluído. Um favorito salvo antes do envio fica disponível na lista após o primeiro Pix concluído para aquela chave. Salvar um favorito não cria uma transferência.

O provedor de pagamentos não disponibiliza consulta do titular e banco de uma chave Pix antes do pagamento. Quando um Pix concluído retorna nome, banco ou documento do destinatário, a revisão identifica esses dados como histórico, com a data da confirmação anterior. O CPF, quando disponível, mostra somente os seis dígitos centrais. Esse histórico não comprova a titularidade atual de uma chave que pode ter sido transferida a outra pessoa. Nunca use um apelido salvo como confirmação bancária.

Saques reais dependem da habilitação do provedor e da conta. Os escopos públicos `subaccounts:read` e `subaccounts:write` não autorizam saques pela API.

## Erros frequentes

| Código | Como tratar |
| - | - |
| `insufficient_scope` | Revise os escopos da chave |
| `subaccount_not_found` | Confira o UUID, a organização e o ambiente |
| `subaccount_reference_conflict` | Use os mesmos dados ao repetir uma referência existente |
| `subaccount_inactive` | Consulte a situação antes de criar outra cobrança |
| `subaccount_not_linked` | Sincronize o vínculo antes de cobrar |
| `subaccount_limit` | O limite de 1000 subcontas por organização e ambiente foi atingido |
| `subaccounts_unavailable` | O provedor da implantação não oferece subcontas nesse ambiente |
| `subaccount_payouts_blocked` | Revise o bloqueio antes de solicitar outro saque |
| `subaccount_payout_limit` | O débito total excede o limite por saque |
| `subaccount_daily_payout_limit` | O limite diário, incluindo reservas, foi atingido |
| `subaccount_monthly_payout_limit` | O limite mensal, incluindo reservas, foi atingido |
| `fee_changed` | Recalcule a tarifa e a comissão antes de confirmar |

Para os detalhes de cada endpoint e os formatos das respostas, consulte a aba **Referência**, no grupo **Subcontas**.

O saque Pix pelo painel solicita a chave de destino, sem um campo adicional de CPF/CNPJ do destinatário. A confirmação continua sujeita a KYC, autenticador, tarifa e saldo disponível da subconta.

Após confirmar um saque Pix, a MingoPay reconcilia também o repasse da margem da tarifa para a conta principal no provedor de pagamentos. O repasse é idempotente e separado do pagamento: repetir sua confirmação não envia outro Pix nem cobra outra tarifa. Se o pagamento falhar, não há repasse da margem.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.