SANDBOXAmbiente de testes — pagamentos em modo teste, servidores simulados. Nada aqui é real.

Para desenvolvedores

JPSIS Pay — API de micro-transações

A API de micro-transações permite que os sistemas da JPSIS (MikroSDN, MikroERP, RadioBox e os próximos) cobrem pequenos valores dos seus usuários dentro do próprio sistema: sem redirecionar para outro site, sem abrir nova aba e sem pedir o cartão de novo.

O dinheiro sai da carteira JPSIS do usuário — um saldo que ele adiciona na Minha área, em jpsis.com.br/app/carteira.

Como funciona

  1. O usuário entra no sistema com o login JPSIS (SSO, já existente). Logo depois, o backend do sistema troca o access_token do login por um pay_token válido por 12 horas.
  2. O usuário compra algo. O backend cria uma cobrança (charge) informando valor, descrição e uma reference única.
  3. Se o usuário já autorizou o pagamento rápido para aquele sistema e o valor cabe no limite, a cobrança volta paga na hora.
  4. Caso contrário, ela volta requires_confirmation e o sistema mostra a janela de confirmação (jpsis-pay-sheet.js) na própria tela. O usuário clica em Pagar e o backend confirma.
  5. O valor sai da carteira e o resultado chega na mesma requisição. Não existe callback nem webhook para esperar.
 navegador            backend do sistema                  jpsis.com.br
     │   compra  ─────────►  pay.charge()  ───────────────►  /api/pay/v1/charges
     │                         ◄── requires_confirmation ──
     │ ◄── janela "Pagar" ──
     │   clica  ──────────►  pay.confirm() ───────────────►  /api/pay/v1/charges/confirm
     │ ◄── aprovado ────────   ◄── succeeded ───────────────  (débito na carteira)

O navegador nunca fala com o hub: toda chamada passa pelo backend do sistema, que se autentica com o certificado da licença.

Autenticação

São duas provas em cada chamada:

Quem Como prova Onde está
O sistema (quem cobra) client_assertion JWT RS256 assinada com a chave da licença (RFC 7523), igual a /api/license/activate /etc/jpsis/license.key + license.json (instalados pelo cloud-init)
O usuário (quem paga) pay_token (12 h) ou o access_token do SSO (15 min) Sessão do usuário no backend do sistema

Não existe chave de API para guardar. Um sistema só consegue cobrar usuários que fazem parte da licença daquele servidor, e um token emitido para um servidor não funciona em outro.

Todo corpo de requisição leva estes campos de autenticação do sistema, que o SDK preenche sozinho:

{
  "client_id": "<instanceId do license.json>",
  "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
  "client_assertion": "<JWT RS256, aud = URL completa do endpoint, exp ≤ 2 min, jti único>"
}

SDK

Copie para o sistema os dois arquivos da pasta sdk/ do monorepo:

  • sdk/jpsis-pay.ts — backend (Node 20+). Depende só de jose.
  • sdk/jpsis-pay-sheet.js — navegador. Sem dependências, com estilos isolados em Shadow DOM.

1. Depois do login SSO

import { JpsisPay } from "./jpsis-pay";
const pay = new JpsisPay(); // lê /etc/jpsis/license.json

const login = await jpsis.finishLogin(req.query, cookie);            // jpsis-client.ts, como hoje
const { payToken } = await pay.openSession(login.accessToken);
req.session.payToken = payToken;                                      // guarde no servidor, nunca no navegador

2. Criar a cobrança

app.post("/api/compras", async (req, res) => {
  const charge = await pay.charge({
    payToken: req.session.payToken,
    amount: 150,                                   // centavos: R$ 1,50
    description: "Relatório avançado",
    reference: `relatorio-${req.body.id}-${req.session.userId}`,
    metadata: { relatorio: String(req.body.id) },
  });
  if (charge.status === "succeeded") liberarRelatorio(req.body.id);
  res.json(charge);
});

3. Confirmar quando o usuário clicar em Pagar

app.post("/api/compras/:id/confirmar", async (req, res) => {
  try {
    const charge = await pay.confirm({
      payToken: req.session.payToken,
      chargeId: req.params.id,
      quickPay: req.body.quickPay, // opcional: { limit: 2000, maxPerCharge: 500 }
    });
    liberarRelatorio(charge.metadata.relatorio);
    res.json(charge);
  } catch (e) {
    res.status(e.status ?? 500).json({ error: e.code, message: e.message });
  }
});

app.get("/api/carteira", async (req, res) => res.json(await pay.wallet(req.session.payToken)));

4. Janela de pagamento no navegador

<script src="/static/jpsis-pay-sheet.js"></script>
<script>
  async function comprar(id) {
    const charge = await fetch("/api/compras", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ id }),
    }).then((r) => r.json());

    if (charge.status === "succeeded") return mostrarRelatorio(id);

    const r = await JpsisPaySheet.open({
      charge,
      appName: "MikroSDN",
      walletUrl: "/api/carteira",
      confirmUrl: `/api/compras/${charge.id}/confirmar`,
      quickPayOffer: { limit: 2000, maxPerCharge: 500 },
      theme: "auto", // "auto" segue o tema do sistema operacional; use "light" ou "dark" para combinar com o seu sistema
    });
    if (r.status === "succeeded") mostrarRelatorio(id);
  }
</script>

A janela mostra o valor, o saldo e, se faltar dinheiro, um botão para adicionar saldo na carteira, que abre em outra aba. Ela é responsiva: no celular aparece de baixo para cima e no computador no centro da tela. Também tem tema claro e escuro (opção theme).

Pagamento rápido

Na primeira confirmação, o usuário pode marcar Pagamento rápido. A partir daí, cobranças daquele sistema que respeitem os dois limites abaixo são aprovadas sem a janela de confirmação:

  • maxPerCharge: valor máximo de cada compra;
  • limit: total por período (day, week ou month; o padrão é month).

O usuário vê e desliga as permissões em Minha área → Carteira. Para saber se o sistema pode cobrar direto, consulte pay.wallet(payToken).quick_pay.

Endpoints

Base: https://jpsis.com.br/api/pay/v1. Todos usam POST com corpo JSON (ou form-urlencoded) e respondem JSON.

Endpoint Campos Retorno
/session access_token { pay_token, expires_in, user_id }
/wallet pay_token { balance, quick_pay, topup_url }
/charges pay_token, amount, description, reference, metadata? charge (201)
/charges/confirm pay_token, charge_id, quick_pay_limit?, quick_pay_max_per_charge?, quick_pay_period? charge
/charges/cancel charge_id charge
/charges/refund charge_id, amount? (sem amount = estorno total) charge
/charges/retrieve charge_id ou reference charge

Objeto charge

{
  "id": "chg_mhz4k2a1b3c4d5e6f7g8h9j0",
  "object": "charge",
  "status": "succeeded",
  "amount": 150,
  "amount_refunded": 0,
  "currency": "brl",
  "description": "Relatório avançado",
  "reference": "relatorio-8812-usr_123",
  "user_id": "mhz3…",
  "license_id": "mhz1…",
  "capture_method": "confirmation",
  "metadata": { "relatorio": "8812" },
  "expires_at": "2026-11-15T14:15:00.000Z",
  "succeeded_at": "2026-11-15T14:01:12.000Z",
  "created_at": "2026-11-15T14:00:58.000Z"
}
status Significado
requires_confirmation Aguardando o usuário clicar em Pagar. Expira em 15 minutos.
succeeded Pago. capture_method diz se foi por confirmation ou allowance (pagamento rápido).
canceled Cancelada pelo sistema antes da confirmação.
expired O usuário não confirmou a tempo.
refunded / partially_refunded Estornada; o valor voltou para a carteira do usuário.

Idempotência

A reference identifica a compra dentro do sistema e é única por servidor. Repetir pay.charge() com a mesma reference devolve a mesma cobrança e nunca cobra duas vezes. Usar a mesma reference com outro valor ou outro usuário retorna 409 reference_conflict.

Erros

O formato é o mesmo do SSO: { "error": "<código>", "error_description": "<mensagem em português>" }. No SDK, cada erro vira um JpsisPayError com code, status e message.

HTTP error Quando acontece
400 invalid_amount, invalid_request, invalid_reference, invalid_allowance Parâmetro inválido
401 invalid_client client_assertion ausente, inválida ou repetida
401 invalid_token pay_token expirado, de outro servidor ou de conta inativa
402 insufficient_funds Falta saldo. A carteira não é alterada.
403 access_denied O usuário não faz parte da licença deste servidor
403 license_inactive Licença suspensa, revogada ou vencida
404 charge_not_found A cobrança não existe ou é de outro servidor
409 charge_not_confirmable, charge_expired, charge_not_cancelable, charge_not_refundable, reference_conflict O estado atual não permite a operação

Limites

Item Padrão Variável no hub
Valor por cobrança de R$ 0,01 a R$ 200,00 PAY_MAX_CHARGE_CENTS
Prazo para confirmar 15 minutos —
Validade do pay_token 12 horas —
Recarga da carteira de R$ 5,00 a R$ 5.000,00, por cartão via Stripe —

Segurança

  • O saldo só muda dentro de uma transação no Postgres com SELECT … FOR UPDATE, e cada movimento gera um lançamento no extrato (wallet_entries).
  • O banco recusa saldo negativo (CHECK balance_cents >= 0) e estorno maior que o valor pago.
  • O pay_token não serve como access_token em /api/sso/userinfo, e o access_token não serve em outro servidor.
  • Confirmação, estorno e início de recarga ficam registrados na auditoria do painel.
  • Cobranças não confirmadas expiram sozinhas (cron /api/cron/sync).

Testando

Com o hub rodando localmente e um banco de testes:

pnpm tsx --env-file=.env scripts/test-pay-api.mts

O script cria uma licença de teste com certificado real e verifica, contra a API de verdade:

  • sessão, saldo, criação e idempotência;
  • confirmação, pagamento rápido e seus limites;
  • saldo insuficiente, cancelamento, estornos e busca;
  • usuário de fora da licença, token de outro servidor e assinatura forjada.

Não rode o script contra produção.