> ## 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.

# Conceitos fundamentais

> Entenda ambientes, valores, estados, escopos e identificadores da API.

## Ambientes

| Ambiente | Prefixo da chave | Uso |
| - | - | - |
| Sandbox | `mp_test_` | Desenvolvimento e simulações sem dinheiro real |
| Produção | `mp_live_` | Operações reais após habilitação da conta e do provedor |

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

| Estado | Significado |
| - | - |
| `created` | Registro interno criado antes da ativação no provedor |
| `pending` | Pix emitido e aguardando pagamento |
| `processing` | Atualização em processamento |
| `paid` | Pagamento confirmado |
| `failed` | Falha ao criar ou processar |
| `cancelled` | Cobrança cancelada |
| `partially_refunded` | Parte do valor foi devolvida |
| `refunded` | Valor integral devolvido |

## 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$ 10,20 de saldo e tarifa de R$ 0,45, informar R$ 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.


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