Ambientes
O ambiente é definido pela chave. Rotas
/v1/sandbox/* rejeitam chaves de produção.
Valores monetários
Envie valores como inteiros em centavos.14990 representa R$ 149,90. Não envie número decimal nem texto formatado.
Estados de uma cobrança
Depósitos pelo painel
Em Movimentações > Movimentar saldo > Depositar, informe o valor e a validade do Pix. No formulário de depósito, o nome do cliente e a descrição são opcionais; o formulário não solicita CPF do pagador. O nome informado é enviado como identificação do cliente e a descrição como descrição da cobrança, sem substituir os dados do titular recebedor exibidos pelo banco. Antes de gerar o Pix, o formulário consulta a taxa da conta e calcula o valor líquido a receber. Após gerar o Pix, o painel exibe o QR Code, o código Pix Copia e Cola completo e o botão para copiá-lo. O cartão mantém a taxa e o líquido registrados na cobrança, mesmo que a tarifa da conta seja alterada depois. A tela rola automaticamente até o cartão ao gerar o código e ao confirmar o recebimento, respeitando a preferência por movimento reduzido. O QR Code é gerado no navegador a partir do mesmo código retornado pela API, sem enviar o conteúdo a serviços externos. No sandbox, ele representa apenas o código de teste e não pode ser pago. Depois da confirmação autenticada do provedor, o cartão muda automaticamente para PIX recebido, retira o QR Code e o botão de copiar, e saldo, extrato e metas recebem a atualização por WebSocket. Uma reconexão recupera o estado atual, sem consultas HTTP periódicas. A meta de recebimentos considera o valor bruto dos Pix confirmados, incluindo depósitos do painel, abatendo devoluções; o faturamento de vendas continua separado dos depósitos. O fluxo financeiro inclui vendas e depósitos confirmados, em valores brutos após devoluções; as saídas incluem a taxa da transferência. Faturamento, aprovação, meios de pagamento e clientes por volume continuam considerando apenas vendas. Últimas ocorrências e atividade recente incluem também os depósitos e as demais movimentações do extrato. No extrato, recebimentos confirmados sem devolução mostram valor bruto, taxa e valor líquido. A referência abreviada permite copiar o identificador completo, e a coluna de ações aparece apenas quando há ações disponíveis. Esse formulário usa a sessão da dashboard. Na API pública e no SDK,POST /v1/payment-intents continua exigindo payer.name e payer.taxId conforme o OpenAPI. payer.name, description e externalReference não aceitam HTML. payer.email, quando enviado, 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.
Transferências Pix pelo painel
Todo saque real exige o KYC aprovado da pessoa que o autoriza, inclusive administradores e saques de subcontas. Um administrador autorizado precisa revisar a verificação de outro usuário. O saque agendado passa por uma nova checagem antes de sair. Se não for possível confirmar a autorização, o envio é bloqueado antes da reserva do saldo. Após atingir o limite de tentativas do autenticador, aguarde o tempo indicado na confirmação do saque e use um código novo. No painel, transferências e saques Pix solicitam apenas a chave Pix de destino (CPF, CNPJ, e-mail, telefone ou chave aleatória), sem um segundo campo de documento do destinatário. No painel, o envio de transferências começa em Agora e a validade do Pix de depósito começa em 30 minutos; as opções podem ser alteradas antes de confirmar. O valor, a tarifa e o destino são revisados antes da confirmação; KYC, autenticador, saldo e bloqueios continuam sendo verificados. A API pública e o SDK não oferecem saques. No formulário principal de transferência, o valor informado é o total a debitar, já incluindo a tarifa. Por exemplo, com R 0,45, informar R 9,75 ao destino e zera o saldo. A confirmação mostra o líquido, a tarifa e o total. Depois da confirmação bancária, a margem da MingoPay (tarifa da conta menos custo do provedor) é repassada da subconta para a conta principal com uma chave idempotente própria. Se o repasse ficar sem resposta, a transferência permanece em reconciliação e o PIX não é repetido. Saques recusados não geram esse repasse.Identificadores
id é o UUID da cobrança na MingoPay. externalReference é a referência opcional do seu sistema, como o número do pedido. Guarde os dois para suporte e reconciliação.
Disponibilidade de devoluções
Devoluções em produção dependem do provedor da cobrança. A integração atual do provedor de pagamentos não oferece devolução Pix pela API MingoPay. Nessa situação, a API retorna503 refund_unavailable antes de criar uma devolução ou reservar saldo, e o extrato não exibe a ação de estornar. Em provedores com suporte, uma devolução parcial limita a próxima solicitação ao valor ainda não devolvido. A simulação de devolução no sandbox permanece disponível.
