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
- O usuário entra no sistema com o login JPSIS (SSO, já existente). Logo depois, o backend do sistema troca o
access_tokendo login por umpay_tokenválido por 12 horas. - O usuário compra algo. O backend cria uma cobrança (
charge) informando valor, descrição e umareferenceúnica. - 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.
- Caso contrário, ela volta
requires_confirmatione 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. - 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ó dejose.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,weekoumonth; 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_tokennão serve comoaccess_tokenem/api/sso/userinfo, e oaccess_tokennã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.