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, usemingo.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
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
EnviesubaccountId em POST /v1/payment-intents, com uma Idempotency-Key de 16 a 128 caracteres.
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 é 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 0,25,providerFeeCents é 25 e platformFeeCents é 15. Em um saque padrão que entrega 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 R 96,60 ficam na subconta, R 0,40 são tarifa Mingo. Desses 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 0,70: o débito total é R 0,70 para o criador e R 0,45, 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.
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úblicossubaccounts: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.
