Pular para o conteúdo principal

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 R10,20desaldoetarifadeR 10,20 de saldo e tarifa de R 0,45, informar R10,20enviaR 10,20 envia 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 retorna 503 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.

Preparação de respostas a disputas

A preparação automática preenche um resumo para revisão e complementação. Quando a contestação MED está vinculada a uma cobrança e à subconta corretas, ela aparece em Disputas e MED e gera um aviso na conta. A defesa em texto só é enviada depois de confirmação no painel. O painel indica se a entrega ao banco foi confirmada ou se ainda está em conferência. Registros manuais continuam disponíveis para análise interna.

Cofrinhos pelo painel

Os cofrinhos do painel aparecem em uma lista com saldo guardado, meta, progresso e regra automática. Novo cofrinho abre um drawer; Abrir mostra Movimentar, Automação e Histórico no mesmo drawer. Guardar e retirar valores usam o saldo disponível e a confirmação por autenticador quando exigida. A regra automática pode ser configurada por percentual ou valor fixo, com limite opcional por pagamento. Um cofrinho vazio pode ser arquivado.

Sons de movimentações

As notificações da dashboard usam sons curtos de moedas diferentes para recebimentos confirmados e saídas concluídas. O áudio exige uma interação anterior com a página e respeita o botão de ativar ou desativar sons em Atividade. O carregamento inicial e eventos já conhecidos não disparam sons.