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

# SDK JavaScript e TypeScript

> Integre cobranças Pix, subcontas e webhooks com o SDK oficial da MingoPay para Node.js.

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

```bash theme={"system"}
npm install https://mingopay.com.br/sdk/mingopay-sdk-0.1.4.tgz
```

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](https://mingopay.com.br/sdk/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

```typescript theme={"system"}
import { MingoPay } from "@mingopay/sdk";

const mingo = new MingoPay({
  apiKey: process.env.MINGOPAY_API_KEY!
});

const payment = await mingo.paymentIntents.create({
  externalReference: "pedido-1024",
  amountCents: 14990,
  method: "pix",
  payer: {
    name: "Cliente Exemplo",
    taxId: "52998224725",
    email: "cliente@example.com"
  }
}, {
  idempotencyKey: "pedido-1024-cobranca-001"
});

console.log(payment.id, payment.pix.copyPasteCode);
```

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:

```javascript theme={"system"}
const { MingoPay } = require("@mingopay/sdk");
const mingo = new MingoPay({ apiKey: process.env.MINGOPAY_API_KEY });
```

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

```typescript theme={"system"}
const payment = await mingo.paymentIntents.get(paymentId);
const page = await mingo.paymentIntents.list({ limit: 25 });
const nextPage = page.nextCursor
  ? await mingo.paymentIntents.list({ limit: 25, cursor: page.nextCursor })
  : null;
const balance = await mingo.balance.get();

const refund = await mingo.paymentIntents.refund(paymentId, {
  amountCents: 1000,
  reason: "Cancelamento parcial do pedido"
}, {
  idempotencyKey: "pedido-1024-devolucao-001"
});
```

`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

```typescript theme={"system"}
const store = await mingo.subaccounts.create({
  name: "Loja Centro",
  email: "financeiro@example.com",
  externalReference: "loja-centro"
});

const stores = await mingo.subaccounts.list({ status: "active", limit: 20, offset: 0 });
const statement = await mingo.subaccounts.listTransactions(store.id, { limit: 20 });
const charges = await mingo.subaccounts.listPaymentIntents(store.id, { limit: 20 });

const globalFees = await mingo.subaccounts.getFeeSettings();
await mingo.subaccounts.updateFeeSettings({
  saleFeePercent: 3,
  saleFeeFixedCents: 0,
  payoutFeePercent: 0,
  payoutFeeFixedCents: 70
});
await mingo.subaccounts.update(store.id, {
  feeMode: "global",
  blockMode: "none",
  payoutLimits: { perPayoutCents: 100000, dailyCents: 500000, monthlyCents: 1000000 }
});
const charge = await mingo.subaccounts.createPaymentIntent(store.id, {
  amountCents: 10000,
  method: "pix",
  externalReference: "pedido-subconta-1024",
  payer: { name: "Cliente Exemplo", taxId: "52998224725" }
}, { idempotencyKey: "pedido-subconta-1024-001" });
```

`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](https://docs.mingopay.com.br/documentation/subcontas.md) 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](https://docs.mingopay.com.br/documentation/subcontas.md). 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

```typescript theme={"system"}
import { constructWebhookEvent, MingoPayWebhookError } from "@mingopay/sdk";

try {
  const event = constructWebhookEvent(
    rawBody,
    signatureHeader,
    process.env.MINGOPAY_WEBHOOK_SECRET!
  );
  console.log(event.id, event.type);
} catch (error) {
  if (error instanceof MingoPayWebhookError) {
    console.error("Webhook inválido");
  } else {
    throw error;
  }
}
```

`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](https://docs.mingopay.com.br/documentation/webhooks.md).

## Erros, tempo limite e novas tentativas

```typescript theme={"system"}
import { MingoPayApiError, MingoPayConnectionError } from "@mingopay/sdk";

const controller = new AbortController();

try {
  await mingo.balance.get({ signal: controller.signal, timeoutMs: 15000 });
} catch (error) {
  if (error instanceof MingoPayApiError) {
    console.error(error.status, error.code, error.requestId);
  } else if (error instanceof MingoPayConnectionError) {
    console.error(error.code);
  } else {
    throw error;
  }
}
```

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

| Opção do cliente | Padrão | Regra |
| - | - | - |
| `apiKey` | Obrigatória | Chave MingoPay somente no servidor |
| `baseUrl` | `https://api.mingopay.com.br` | Origem HTTPS, sem caminho; HTTP local somente com sandbox |
| `timeoutMs` | 30000 | De 1 a 120000 |
| `maxRetries` | 2 | De 0 a 3, somente GET elegíveis |
| `maxResponseBytes` | 8388608 | De 1024 a 67108864 |

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.

| Recurso | Métodos |
| - | - |
| `paymentIntents` | `create`, `get`, `list`, `synchronize`, `refund` |
| `balance` | `get` |
| `subaccounts` | `create`, `list`, `get`, `update`, `synchronize`, `listTransactions`, `listPaymentIntents` |
| `sandbox` | `confirmPaymentIntent`, `refundPaymentIntent` |

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](https://mingopay.com.br/sdk/changelog.md).

Devoluções de produção permanecem bloqueadas até a homologação das reservas e dos controles de saldo e bloqueio.


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