MuPag SDK para Node.js

SDK TypeScript/Node.js oficial da MuPag. A ideia e deixar pagamento tao facil quanto criar um cliente, chamar mupag.charges.create(...) e seguir com o produto.

Ele foi desenhado para parecer uma biblioteca escrita por pessoa: nomes curtos, erros uteis, retries seguros e idempotencia automatica. Sem cliente HTTP pesado, sem codigo gerado vazando para sua aplicacao.

Install

npm install mupag-sdk

Migração: se seu projeto ainda usa mupay-sdk, atualize a dependência e os imports para mupag-sdk.

Quickstart em menos de 1 minuto

import { MuPag } from 'mupag-sdk';

const mupag = new MuPag({
  apiKey: process.env.MUPAG_API_KEY!,
  env: 'test'
});

const charge = await mupag.charges.create({
  amount_cents: 9990,
  payment_method: 'pix',
  customer: {
    id: 'cus_123',
    name: 'Ana Silva',
    email: '[email protected]',
    tax_id: '12345678901'
  }
});

console.log(charge.charge_id);

Pronto: o SDK escolhe a URL do sandbox, envia Authorization, gera Idempotency-Key, serializa JSON e faz retry seguro para respostas transientes.

Por que integrar com a SDK e nao montar HTTP na mao?

• mupag.charges.create(...) e legivel por quem acabou de chegar no codigo.
• Todo POST financeiro recebe idempotencia automaticamente.
• Erros vem tipados com code, suggestion, documentationUrl e requestId.
• Webhooks validam HMAC-SHA256, timestamp e payload bruto.
• Bundle minificado+gzip fica abaixo de 50KB; hoje esta em torno de 1.7KB gzip.

Examples

PIX charge

const charge = await mupag.charges.create({
  amount_cents: 9990,
  payment_method: 'pix',
  customer: {
    id: 'cus_123',
    name: 'Ana Silva',
    email: '[email protected]',
    tax_id: '12345678901'
  },
  description: 'Plano Pro mensal'
});

Card charge

const charge = await mupag.charges.create({
  amount_cents: 14990,
  payment_method: 'credit_card',
  customer: {
    id: 'cus_123',
    name: 'Ana Silva',
    email: '[email protected]',
    tax_id: '12345678901'
  },
  card_token_id: '11111111-1111-1111-1111-111111111111',
  payer_ip: '203.0.113.10',
  installments: 1,
  metadata: { cart_id: 'cart_789' }
});

payer_ip deve ser o IP literal observado no checkout do pagador e atestado pelo merchant; nao envie o IP do servidor que chama a MuPag. O contrato atual aceita somente uma parcela, rejeita soft_descriptor e falha fechado quando o merchant exige 3DS.

Cancel subscription

const subscription = await mupag.subscriptions.cancel('sub_123', {
  mode: 'immediate',
  reason: 'customer_request'
});

Cancel charge

O cancelamento exige uma chave estável definida pela aplicação porque o mesmo valor precisa sobreviver a processos e filas diferentes:

const cancellation = await mupag.charges.cancel('ch_123', {
  idempotencyKey: 'cancel_order_123_attempt_1',
  reason: 'payment_attempt_cancelled'
});

Refund

const refund = await mupag.refunds.create('ch_123', {
  amount_cents: 9990,
  reason: 'requested_by_customer'
});

Webhook validation

const event = await mupag.webhooks.constructEvent(
  rawPayload,
  request.headers.get('mupag-signature')!,
  process.env.MUPAG_WEBHOOK_SECRET!
);

if (event.type === 'charge.paid') {
  console.log(event.data);
}

Errors

Erros da API preservam os campos DX-first do Problem Details:

import { ValidationError } from 'mupag-sdk';

try {
  await mupag.charges.create({
    amount_cents: 0,
    payment_method: 'pix',
    customer: {
      id: 'cus_123',
      name: 'Ana Silva',
      email: '[email protected]',
      tax_id: '12345678901'
    }
  });
} catch (error) {
  if (error instanceof ValidationError) {
    console.log(error.code);
    console.log(error.suggestion);
    console.log(error.documentationUrl);
    console.log(error.requestId);
  }
}

Quando uma mutação pode ter sido aceita, mas a resposta final não é confiável, o SDK lança OutcomeUnknownError. A chave efetivamente enviada fica disponível no campo estruturado idempotencyKey e não aparece na mensagem do erro. Reutilize essa chave somente com o mesmo payload:

import { OutcomeUnknownError } from 'mupag-sdk';

try {
  await mupag.charges.create(payload, { idempotencyKey: 'order_123_attempt_1' });
} catch (error) {
  if (error instanceof OutcomeUnknownError) {
    await reconcileUsingTheSamePayload(error.idempotencyKey, payload);
  }
}

Runtime support

• Node.js 18+
• Bun
• Deno
• Cloudflare Workers
• Vercel Edge

O SDK usa fetch, AbortController, crypto.subtle e TextEncoder, sem axios ou got.

Como publicar no npm

O pacote e publico e sem escopo: mupag-sdk. Pacotes npm sem escopo sao publicados no registry publico pelo proprio nome, desde que o nome esteja disponivel.

Fluxo recomendado:

1. Crie/acesse uma conta em npmjs.com.
2. Garanta que a equipe MuPag tem permissao para publicar mupag-sdk.
3. Rode checks locais:

npm ci
npm run check
npm pack --dry-run

4. Publique manualmente:

npm publish

No fluxo atual, a publicação manual não usa provenance: o manifesto ainda não aponta para um repositório público correspondente e não existe uma execução de CI/OIDC compatível para assinar o artefato. Habilite npm publish --provenance somente depois que esses dois requisitos forem atendidos. O repositório não publica a SDK automaticamente pela pipeline do GitHub.

Segundo a documentacao do npm, pacotes sem escopo sao publicos por natureza; para pacotes com escopo seria necessario npm publish --access public.

Useful docs

• API errors
• Charges
• Subscriptions
• Refunds
• Webhooks