Node.js SDK

pnpm add @bobpayments/sdk
# npm install @bobpayments/sdk · yarn add @bobpayments/sdk

import { BobPayments } from '@bobpayments/sdk';

const bob = new BobPayments({
  apiKey: process.env.BOB_API_KEY!, // sk_live_... or sk_test_...
  // timeoutMs: 35_000,             // timeout per attempt
  // maxRetries: 2,                 // automatic retries; 0 disables
});

bob.environment; // 'live' | 'sandbox' — detected from the key prefix

const session = await bob.checkoutSessions.create({
  amountCents: 25_000,
  items: [{ name: 'Assinatura Pro', quantity: 1, unitAmountCents: 25_000 }],
  paymentMethods: ['pix'],
  successUrl: 'https://loja.example.com/pedido/sucesso',
  webhookUrl: 'https://loja.example.com/webhooks/bob',
});

// Redirect the buyer; store session.webhookSecret if it exists.
redirect(session.checkoutUrl);

const tx = await bob.transactions.create({
  customer: {
    name: 'João Silva',
    document: '12345678901',
    documentType: 'CPF',
    email: '[email protected]',
    address: {
      street: 'Rua das Flores',
      streetNumber: '123',
      neighborhood: 'Centro',
      zipCode: '01310-100',
      city: 'São Paulo',
      state: 'SP',
    },
  },
  payment: { amountCents: 10_000, product: 'Assinatura Pro' }, // always in cents
  originDomain: 'loja.example.com',
});

tx.pixCode;        // PIX copy-and-paste (EMV)
tx.expirationDate; // when the PIX expires
tx.persisted;      // false = HTTP 202 (reconciliation pending; PIX valid)
tx.replayed;       // true = response replayed via idempotency

const detail = await bob.transactions.get('clx1abc123');

const page = await bob.transactions.list({
  status: 'paid',
  dateFrom: new Date('2026-07-01'),
  limit: 50,
}); // { data, meta: { total, page, limit, totalPages } }

const customers = await bob.customers.list({ email: '[email protected]' });
const customer = await bob.customers.get(customers.data[0].id);

import { constructWebhookEvent, BobPaymentsWebhookVerificationError } from '@bobpayments/sdk';

app.post('/webhooks/bob', express.raw({ type: 'application/json' }), (req, res) => {
  try {
    const event = constructWebhookEvent(
      req.body, // RAW body (Buffer)
      req.headers['x-webhook-signature'],
      process.env.BOB_WEBHOOK_SECRET!,
    );

    if (event.event === 'transaction.paid') {
      // v2: event.data.amountCents · v1: event.data.amount
    }
    res.status(200).send('ok');
  } catch (error) {
    if (error instanceof BobPaymentsWebhookVerificationError) {
      return res.status(401).send('invalid signature');
    }
    throw error;
  }
});

import { BobPaymentsApiError, BobPaymentsTimeoutError } from '@bobpayments/sdk';

try {
  await bob.transactions.create(params);
} catch (error) {
  if (error instanceof BobPaymentsApiError) {
    error.status;            // 400, 401, 422, 429, 503...
    error.code;              // 'ERR_INTEGRATION_006', ...
    error.detail;            // descriptive message
    error.retryAfterSeconds; // on 429/503 when the API sends Retry-After
  } else if (error instanceof BobPaymentsTimeoutError) {
    // exceeded the client timeout
  }
}

await bob.transactions.create({ payment: { amountCents: 10_001, ... }, ... }); // expires in ~5s