Pular para o conteúdo principal
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. 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, 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.
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

A listagem retorna data, total, limit, offset, environment, permissions e globalFees. 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 de 16 a 128 caracteres.
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, 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 é R0,40porPixrecebidoeR 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 R100,00,‘feeCents‘eˊ‘40‘e‘netCents‘eˊ‘9960‘.ComcustodeprocessamentodeR 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 R100,00aodestinataˊrio,sa~odescontadosR 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. 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 R100,00comcomissa~ode3 100,00 com comissão de 3%: R 96,60 ficam na subconta, R3,00sa~ocreditadosnacontadocriadoreR 3,00 são creditados na conta do criador e R 0,40 são tarifa Mingo. Desses R0,40,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 R100,00comcomissa~ofixadeR 100,00 com comissão fixa de R 0,70: o débito total é R101,15,sendoR 101,15, sendo R 0,70 para o criador e R0,45detarifaMingo.DessesR 0,45 de tarifa Mingo. Desses R 0,45, R0,40cobremocustodoprovedoreR 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.
Para definir uma condição própria, envie no PATCH /v1/subaccounts/{id}:

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

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

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

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.