Quickstart — SaaS em 5 minutos

Fluxo mínimo: token de teste → cobrança PIX → aprovar no sandbox → liberar feature no webhook.

1. Criar token de teste

No painel API e Webhooks, ou via API (com um token já autenticado):

curl -X POST https://nucleopay.com.br/api/auth/token/create \
  -H "Authorization: Bearer SEU_TOKEN_ATUAL" \
  -H "Content-Type: application/json" \
  -d '{"label":"dev-saas","mode":"test"}'

Resposta inclui token começando com np_test_ e livemode: false.

2. Criar cobrança (com Idempotency-Key)

curl -X POST https://nucleopay.com.br/api/pix/charge/create \
  -H "Authorization: Bearer np_test_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-42" \
  -d '{"value":49.90,"title":"Plano Pro"}'

Resposta:

• brCode / qrCodeImage — mostre ao comprador
• status — rótulo PT (Pendente)
• statusCode — enum estável (pending)
• livemode: false no sandbox

3. Aprovar no sandbox

curl -X POST https://nucleopay.com.br/api/pix/charge/simulate-pay \
  -H "Authorization: Bearer np_test_…" \
  -H "Content-Type: application/json" \
  -d '{"charge_id":"NCP-…"}'

Dispara charge.approved nos webhooks cadastrados.

4. Webhook libera o plano

// Node — valide X-NucleoPay-Signature e leia data.statusCode
if (event === "charge.approved" && data.statusCode === "approved") {
  await unlockPlan(data.external_id || data.chargeId);
}

Guia completo: Webhooks.

5. Opção SDK TypeScript

npm i @nucleopay/sdk

import { NucleoPayClient } from "@nucleopay/sdk";

const np = new NucleoPayClient({ token: process.env.NUCLEOPAY_TEST_TOKEN });
const charge = await np.createPixCharge({
  value: 49.9,
  title: "Plano Pro",
  idempotencyKey: "order-42",
});
await np.simulatePay(charge.chargeId);

6. UI no frontend (sem token)

Crie a cobrança no seu backend. No browser, use o embed:

<script src="https://nucleopay.com.br/js/nucleopay-embed.js"></script>
<div id="pix"></div>
<script>
  NucleoPayEmbed.mount("#pix", {
    brCode: charge.brCode,
    qrCodeImage: charge.qrCodeImage,
    chargeId: charge.chargeId,
    statusUrl: "/api/meu-app/pix-status?id=" + charge.chargeId,
    onApproved: () => location.href = "/app"
  });
</script>

---

Próximos passos