Quickstart: PIX em minutos

Do zero a um QR Code Pix pago em sandbox.

Vamos do zero a um QR Code Pix funcional pago em sandbox. Sem enrolação.

Pré-requisitos

Node 18+ instalado, conta no Dashboard Stone e suas credenciais de sandbox em mãos.

1. Instale o SDK

Node.js

npm install @stone/node

Python

pip install stone-payments

2. Autentique e crie a cobrança

Node.js

import Stone from '@stone/node';
import crypto from 'crypto';

const client = new Stone({
  clientId: process.env.STONE_CLIENT_ID,
  clientSecret: process.env.STONE_CLIENT_SECRET,
  environment: 'sandbox'
});

const charge = await client.charges.create({
  amount: 1990,
  currency: 'BRL',
  payment_method: 'pix',
  customer: {
    name: 'Maria da Silva',
    tax_id: '11144477735'
  },
  expires_in: 3600,
  reference_id: 'pedido-1042'
}, { idempotencyKey: crypto.randomUUID() });

console.log(charge.pix.qr_code);
console.log(charge.pix.qr_code_image);

Python

from stone import Stone
import os, uuid

client = Stone(
    client_id=os.environ["STONE_CLIENT_ID"],
    client_secret=os.environ["STONE_CLIENT_SECRET"],
    environment="sandbox",
)

charge = client.charges.create(
    amount=1990,
    currency="BRL",
    payment_method="pix",
    customer={"name": "Maria da Silva", "tax_id": "11144477735"},
    expires_in=3600,
    reference_id="pedido-1042",
    idempotency_key=str(uuid.uuid4()),
)

print(charge.pix.qr_code)

3. Receba o webhook de pagamento

Configure um endpoint público (use ngrok em dev) e cadastre-o em Dashboard → Webhooks. Você vai receber:

{
  "id": "evt_1Q9k...",
  "type": "charge.paid",
  "created_at": "2026-04-28T14:32:11Z",
  "data": {
    "id": "ch_2M8x...",
    "status": "paid",
    "amount": 1990,
    "paid_at": "2026-04-28T14:32:08Z",
    "reference_id": "pedido-1042",
    "pix": { "end_to_end_id": "E60746948202604281432..." }
  }
}

4. Confirme o pagamento

Em sandbox, o webhook chega em ~3 segundos automaticamente. Em produção, é instantâneo após o pagador concluir o Pix no banco.

Pronto

Você fez sua primeira transação. Próximos passos:

Webhooks na prática