@mingopay/sdk funciona no servidor com Node.js 22 ou superior, em JavaScript e TypeScript. Aceita ESM e CommonJS e inclui tipos gerados do contrato OpenAPI. Não o importe em componentes do navegador nem em um aplicativo distribuído.
Instalar
MINGOPAY_API_KEY no cofre de segredos do servidor. O prefixo mp_test_ seleciona sandbox e mp_live_, produção. Produção continua dependendo da habilitação da conta e do provedor.
Criar uma cobrança Pix
payment.id e o código Pix junto ao seu pedido. A criação de uma cobrança não confirma o pagamento; valide o webhook e o estado confirmado antes de liberar a venda.
Guarde a idempotencyKey com o pedido antes da primeira chamada e reutilize a mesma chave e o mesmo corpo após timeout ou falha de conexão. createIdempotencyKey() gera um UUID, mas não salva a chave por você. Criar outra chave em cada repetição pode criar outra cobrança.
Para CommonJS:
Consultas, saldo e devoluções
Devoluções reais dependem do provedor da cobrança. Na integração atual do provedor de pagamentos, a API retorna503 refund_unavailable antes de criar a devolução ou reservar saldo. A simulação no sandbox continua disponível.
paymentIntents.synchronize(paymentId) consulta o estado no provedor para reconciliação. Devoluções podem ficar em processing; acompanhe os eventos e a consulta. Os escopos da chave continuam sendo exigidos pela API.
Subcontas
getFeeSettings exige subaccounts:read; updateFeeSettings e update exigem subaccounts:write. createPaymentIntent exige subaccounts:read e payment_intents:write, com chave idempotente de 16 a 128 caracteres. A comissão é adicional à tarifa Mingo: feeCents = mingoFeeCents + commissionCents. Saques continuam disponíveis pelo painel autenticado, com KYC e autenticador. Veja Subcontas para dados criptografados, limites, bloqueios e exemplos de divisão dos valores.
Para cobrar para essa loja, envie subaccountId: store.id em paymentIntents.create. Use subaccounts.get(id), subaccounts.update(id, { name, email, active }) e subaccounts.synchronize(id) para manutenção. A sincronização não transfere dinheiro.
O SDK segue o contrato público de subcontas. A referência externa deduplica a criação; os saldos e lançamentos pertencem à organização e ao ambiente da chave. Os métodos públicos não autorizam saques.
Validar webhooks
rawBody deve ser a string ou os bytes originais do POST; não aplique JSON.stringify a um objeto já interpretado. signatureHeader é o valor de X-MingoPay-Signature.
A validação usa HMAC-SHA256, comparação em tempo constante e tolerância de cinco minutos, para corpos de até 2 MiB. O segredo whsec_ pertence ao seu endpoint MingoPay. O segredo interno de assinatura do provedor de pagamentos não é usado pelo lojista.
Registre event.id com unicidade no banco e processe o pedido de forma idempotente antes de confirmar o recebimento com HTTP 2xx. O SDK não persiste nem deduplica eventos automaticamente. Veja o guia de webhooks.
Erros, tempo limite e novas tentativas
MingoPayApiError inclui status HTTP, código público, identificador da requisição e retryAfterSeconds, quando informado. MingoPayConnectionError.code distingue request_timeout, request_aborted, network_error, invalid_response e response_too_large.
O tempo limite padrão é 30 segundos para toda a operação, incluindo corpo da resposta e novas tentativas. Somente consultas GET com HTTP 429, 502, 503 ou 504 são repetidas, até duas vezes. O SDK respeita Retry-After de até dez segundos; valores maiores são entregues ao chamador sem repetir antes do prazo. Falhas de rede, POST e PATCH não são repetidos automaticamente.
Toda chamada aceita
signal e timeoutMs. Criação de cobrança exige idempotencyKey com 16 a 128 caracteres seguros; devoluções, com 8 a 100. O SDK recusa redirecionamentos para impedir o envio da chave a outra origem.
Sandbox e métodos disponíveis
Com uma chavemp_test_, use sandbox.confirmPaymentIntent(id) e sandbox.refundPaymentIntent(id). Esses métodos recusam chaves de produção antes de enviar a requisição.
O SDK não concede novas permissões à chave nem expõe rotas internas de administração, KYC ou criação de chaves. Novas versões serão informadas nesta página e no histórico do SDK.
Devoluções de produção permanecem bloqueadas até a homologação das reservas e dos controles de saldo e bloqueio.
