Pular para o conteúdo principal
O SDK oficial @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

A versão 0.1.4 é distribuída pelo domínio oficial da MingoPay. A instalação usa essa URL versionada, sem exigir publicação no registro npm. O arquivo release.json contém versão e integridade SHA-512. Guarde o lockfile da sua aplicação. Configure 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

Todos os valores monetários são inteiros em centavos. Armazene 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 retorna 503 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 chave mp_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.