# MingoPay API > Contexto oficial para agentes de IA, ferramentas no-code e assistentes de programação integrarem pagamentos Pix pela MingoPay. Base da API: https://api.mingopay.com.br Documentação humana: https://docs.mingopay.com.br/documentation/introduction OpenAPI 3.1: https://docs.mingopay.com.br/openapi.json Documentação completa: https://docs.mingopay.com.br/llms-full.txt ## Recuperação e troca de senha no painel A recuperação exige o link de uso único recebido por e-mail, válido por uma hora. Se o 2FA estiver ativo, também exige autenticador ou código de recuperação de uso único. Alterar a senha na área Segurança exige a senha atual e o segundo fator ativo. Não há atalho para redefinir a senha apenas informando o e-mail. Esses fluxos são do painel e não usam chaves do SDK. ## Passkeys e biometria no painel Passkeys podem ser cadastradas em Configurações > Segurança para entrar no painel e confirmar saques principais/de subcontas com verificação pelo dispositivo. Windows Hello, Apple e Android podem pedir biometria ou PIN; a Mingo não recebe biometria. Autenticador continua como alternativa, e ações administrativas ainda exigem TOTP. Rotas de passkeys são privadas do painel e não substituem a chave Bearer do SDK/API. KYC, autorização vinculada ao pedido e idempotência continuam obrigatórios. ## 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. ## Criação de chaves no painel No painel, Nova chave inicia com Produção selecionado. Para testes, selecione Sandbox antes de criar a chave. A seleção do ambiente não altera as exigências de habilitação da conta nem as permissões da chave. ## Contas suspensas Organizações suspensas (`restricted`) ou encerradas (`closed`) recebem `403 organization_not_active` em chamadas autenticadas por chave, tanto no sandbox quanto em produção. Uma chave válida não remove a suspensão; corrija a situação da conta antes de tentar novamente. ## Depósitos na dashboard O formulário de depósito solicita valor e validade; nome do cliente e descrição são opcionais. Não pede CPF do pagador. Esses campos identificam cliente e cobrança, sem alterar os dados do titular recebedor mostrados 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. A rota da dashboard usa sessão; na API pública e no SDK, POST /v1/payment-intents continua exigindo payer.name e payer.taxId conforme o OpenAPI. ## SDK oficial JavaScript e TypeScript Guia: https://docs.mingopay.com.br/documentation/sdk Instalação: npm install https://mingopay.com.br/sdk/mingopay-sdk-0.1.4.tgz Pacote: @mingopay/sdk 0.1.4, Node.js 22+, somente no servidor, com ESM e CommonJS. A distribuição usa URL versionada no domínio MingoPay; não assuma publicação no registro npm. Use `new MingoPay({ apiKey: process.env.MINGOPAY_API_KEY })`. Recursos: `paymentIntents.create/get/list/synchronize/refund`, `balance.get`, `subaccounts.create/list/get/update/synchronize/listTransactions/listPaymentIntents` e `sandbox.confirmPaymentIntent/refundPaymentIntent`. Criação e devolução exigem `idempotencyKey` persistida antes da chamada. POST e PATCH não são repetidos automaticamente. `constructWebhookEvent(rawBody, signatureHeader, endpointSecret)` valida HMAC-SHA256 e o tempo do webhook MingoPay; deduplique por `event.id` no banco. O segredo interno do provedor não pertence à integração do lojista. Versão e integridade do pacote: https://mingopay.com.br/sdk/release.json ## Escopo público - Use somente as rotas `/v1` documentadas neste arquivo e no OpenAPI oficial. - Rotas do painel, administração, KYC e infraestrutura são internas e não fazem parte da API pública. - A organização é identificada pela chave. Não aceite `organizationId` enviado pelo navegador para escolher a conta operada. - Nunca invente endpoints, parâmetros, eventos ou estados ausentes do OpenAPI. ## Rotas essenciais - `POST /v1/payment-intents`: criar cobrança Pix com `Idempotency-Key`. - `GET /v1/payment-intents`: listar cobranças da organização autenticada. - `GET /v1/payment-intents/{id}`: consultar cobrança por UUID. - `POST /v1/payment-intents/{id}/synchronize`: reconciliar o estado com o provedor. - `POST /v1/payment-intents/{id}/refunds`: solicitar devolução total ou parcial. - `GET /v1/balance`: consultar saldo disponível. - `POST /v1/subaccounts`: criar subconta com `subaccounts:write` e referência externa única por organização e ambiente. - `GET /v1/subaccounts` e `GET /v1/subaccounts/{id}`: listar e consultar com `subaccounts:read`. - `PATCH /v1/subaccounts/{id}`: editar nome, e-mail ou situação com `subaccounts:write`. - `POST /v1/subaccounts/{id}/sync`: sincronizar o vínculo com `subaccounts:read` e corpo `{}`. - `GET /v1/subaccounts/{id}/transactions` e `GET /v1/subaccounts/{id}/payment-intents`: listar extrato e cobranças com `subaccounts:read`. Para atribuir uma cobrança a uma subconta, envie seu UUID MingoPay em `subaccountId` no `POST /v1/payment-intents`. O líquido confirmado pertence somente à subconta e não integra o saldo principal. As listagens de subcontas usam `data`, `total`, `limit` e `offset`; o padrão é 20 e o limite máximo é 100. Os escopos públicos de subcontas não autorizam saques. `payer.name`, `description`, `externalReference` e o nome da subconta não aceitam HTML. `payer.email` e o e-mail da subconta, quando enviados, precisam ser de um domínio permanente: typos de Gmail e provedores parecidos, e-mails descartáveis e domínios sem entrega são recusados. 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. Todo saque real exige KYC aprovado de quem o autoriza, inclusive administradores e saques de subcontas. Um administrador não pode aprovar a própria verificação. Saques agendados passam por nova conferência 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. O autenticador, o saldo e os bloqueios também são verificados. A API pública e o SDK não oferecem saques. ## 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. 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. ## Rúpias (INR): preparação A integração de rúpia indiana (INR) está em preparação, com adaptador dLocal de sandbox via UPI e comandos locais de criação e consulta. Produção é bloqueada. Nenhuma confirmação de teste gera saldo BRL, faturamento, metas ou saque Pix. Câmbio, webhooks internacionais, liquidação em reais e crédito ao lojista ainda dependem de contrato e homologação. Guia: https://docs.mingopay.com.br/documentation/international-inr . A API pública e o SDK não oferecem cobrança INR ou câmbio nesta versão. ## Tarifas As tarifas padrão são R$ 0,40 por Pix recebido e R$ 0,45 por saída Pix, já incluindo o custo do provedor. Contas novas recebem esses valores no cadastro; subcontas herdam a tarifa da organização e condições negociadas podem ser diferentes. `feeCents` é a tarifa total da cobrança, `providerFeeCents` é o custo do provedor, `platformFeeCents` é a diferença e `netCents` é o valor após a tarifa total. Não desconte o custo outra vez. Operações registradas preservam sua tarifa. ## Simulações - `POST /v1/sandbox/payment-intents/{id}/confirm`: confirmar cobrança apenas no sandbox. - `POST /v1/sandbox/payment-intents/{id}/refund`: simular devolução apenas no sandbox. ## Prompt pronto Copie o bloco abaixo para sua IA. Troque apenas os campos entre colchetes. ```text Implemente a integração completa da MingoPay no meu projeto [DESCREVA O PROJETO E A STACK]. Antes de alterar código: 1. Leia https://docs.mingopay.com.br/llms-full.txt. 2. Leia https://docs.mingopay.com.br/openapi.json como contrato definitivo da API. 3. Inspecione a arquitetura existente e reutilize os padrões do projeto. 4. Se faltar uma decisão indispensável, faça somente perguntas objetivas. Requisitos obrigatórios: - Use https://api.mingopay.com.br e rotas /v1. - Faça todas as chamadas à MingoPay no servidor. Nunca exponha mp_test_, mp_live_ ou whsec_ no navegador, bundle, logs ou respostas públicas. - Leia MINGOPAY_API_KEY e MINGOPAY_WEBHOOK_SECRET do cofre de segredos ou das variáveis do ambiente. - Trabalhe primeiro com uma chave mp_test_. Não execute transações reais. - Envie valores monetários como inteiros em centavos. - Crie cobranças Pix com POST /v1/payment-intents e uma Idempotency-Key única e persistente por tentativa. - Associe externalReference e metadata ao identificador interno do pedido. - Retorne ao frontend somente os campos necessários, incluindo pix.copyPasteCode, pix.expiresAt e o identificador da cobrança. - Não marque um pedido como pago usando a resposta de criação da cobrança. - Crie um endpoint HTTPS de webhook que leia o corpo bruto e valide X-MingoPay-Signature com HMAC-SHA256 sobre timestamp + "." + rawBody. - Rejeite assinaturas inválidas e timestamps com diferença superior a 300 segundos usando comparação timing-safe. - Persista o id do evento com restrição única para impedir processamento duplicado. - Confirme o pedido somente após payment_intent.paid válido. Trate pending, failed, cancelled e refunded com transições idempotentes. - Responda 2xx somente depois de aceitar e persistir o evento. - Use GET /v1/payment-intents/{id} apenas para consulta e reconciliação. - Valide todas as entradas, CPF/CNPJ, e-mail, valor e limites antes da chamada externa. - Não aceite preço, taxa, status pago ou identificadores de organização enviados pelo cliente sem validação no servidor. - Implemente timeouts, erros tipados, logs sem credenciais e mensagens seguras para o usuário. - Crie testes para idempotência, assinatura inválida, replay de evento, pagamento confirmado e falha da API. Entregue: 1. lista curta dos arquivos que serão alterados; 2. implementação pronta para produção seguindo a stack existente; 3. variáveis de ambiente necessárias sem valores secretos; 4. instruções para testar no sandbox; 5. checklist do que ainda depende de credenciais ou homologação de produção. ``` ## Guias - [Introdução](https://docs.mingopay.com.br/documentation/introduction): visão geral e fluxo recomendado. - [Primeira integração](https://docs.mingopay.com.br/documentation/quickstart): cobrança Pix no sandbox. - [Conceitos fundamentais](https://docs.mingopay.com.br/documentation/concepts): estados, centavos e referências externas. - [Chaves de API](https://docs.mingopay.com.br/documentation/authentication): autenticação, escopos e proteção de credenciais. - [Sandbox e produção](https://docs.mingopay.com.br/documentation/sandbox-production): separação de ambientes. - [Idempotência](https://docs.mingopay.com.br/documentation/idempotency): repetição segura de operações. - [Erros e diagnóstico](https://docs.mingopay.com.br/documentation/errors): respostas e tratamento de falhas. - [Webhooks](https://docs.mingopay.com.br/documentation/webhooks): assinatura, deduplicação e eventos. - [Subcontas](https://docs.mingopay.com.br/documentation/subcontas): criação, permissões, cobranças, saldos e extratos separados. - [Checklist de produção](https://docs.mingopay.com.br/documentation/production-checklist): requisitos antes de movimentar dinheiro real. - [Integração com IA e no-code](https://docs.mingopay.com.br/documentation/no-code): n8n, Make, Zapier e agentes. ## Regras de segurança - Chaves de API pertencem exclusivamente ao backend ou ao cofre da ferramenta no-code. - A resposta de criação de cobrança representa estado `pending`, não pagamento confirmado. - Webhooks devem ser validados usando o corpo bruto antes do parse do JSON. - Eventos podem ser repetidos e entregues fora de ordem; use identificador único e máquina de estados. - Produção exige credenciais, homologação e confirmação operacional do provedor. Sandbox não movimenta dinheiro real. ## Devoluções e suporte do provedor Devoluções reais dependem do provedor da cobrança. A integração atual do provedor de pagamentos não oferece devolução Pix pela API MingoPay. Sem suporte, a API responde 503 refund_unavailable antes de criar uma devolução ou reservar saldo, e o painel não exibe a ação de estornar. Devoluções de produção permanecem bloqueadas até a homologação das reservas e dos controles de saldo e bloqueio. A simulação de devolução no sandbox continua 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. Subcontas: name obrigatório; externalReference opcional e estável para deduplicação. GET/PUT /v1/subaccounts/fee-settings configuram comissões globais. PATCH /v1/subaccounts/{id} aceita feeMode global/custom, customFees, pixKey/holderTaxId criptografados (null remove), blockMode none/payouts/all e payoutLimits perPayoutCents/dailyCents/monthlyCents. Comissão adicional à tarifa Mingo, valores registrados por operação, períodos America/Sao_Paulo. SDK subaccounts.getFeeSettings/updateFeeSettings/createPaymentIntent. feeCents = mingoFeeCents + commissionCents. Saques públicos não estão habilitados; painel exige KYC e autenticador. Painel Pix: confirmação antes do envio com chave mascarada, líquido, tarifa, comissão e débito total. Favoritos preenchem apenas o destino; valor e autenticação continuam obrigatórios. Contatos criptografados são separados por organização e ambiente; Recentes e Contatos só aparecem após saques Pix concluídos e só listam destinos já pagos. Favoritos salvos antes do envio só entram na lista após o primeiro Pix concluído para a chave. O provedor de pagamentos não oferece consulta prévia de titular/banco. Dados de pagamentos anteriores, quando retornados pelo provedor, são históricos datados e não comprovam titularidade atual; CPF exibe somente seis dígitos centrais. Não há API pública/SDK de saques, favoritos ou consulta de titular. ## Notificações Discord Webhooks > Novo endpoint > Discord aceita a URL oficial do webhook de um canal e separa sandbox/produção. O token da URL é criptografado e mascarado na listagem. O botão Testar enfileira uma mensagem; confirme a entrega no canal/histórico. Recebe pagamentos confirmados, devoluções, transferências concluídas/com falha e atualizações de disputas. São enviados ID da transação, status do evento, valor, taxa registrada, data/hora de Brasília, ambiente e ID do evento, sem dados pessoais ou menções. Testes não inventam transações. A taxa de disputa/devolução é a da transação original. Discord usa mensagens próprias, sem o envelope HMAC dos endpoints JSON. Falhas usam até dez tentativas; 429 pode ampliar a espera até uma hora; timeouts podem duplicar mensagens. Configuração usa sessão do painel, não Bearer/SDK. Detalhes das entregas: HTTP, tentativa, operação, destino, horários, resposta e corpo enviado criptografado nas novas tentativas. Histórico antigo mostra Dados do evento, sem alegar corpo exato. Reenvio de falhas preserva ID e contador, acrescenta dez tentativas e ignora destinos entregues; exige endpoint ativo e evento falho/esgotado. Não movimenta dinheiro. Testar webhook: HTTP 202 confirma apenas a fila e usa aviso informativo. O resultado é associado pelo eventId; só entrega 2xx registrada gera sucesso, e falhas geram erro. A lista e o resultado atualizam por WebSocket privado/autenticado, com isolamento de organização e papel, sem polling HTTP. Não há contrato público WebSocket ou método SDK para esse stream.