Instalação

pnpm add @bob-payments/sdk
# npm install @bob-payments/sdk · yarn add @bob-payments/sdk

Server-side only — a API key sk_live_/sk_test_ é secreta e nunca deve ir para o browser.

Comece em 30 segundos

import { BobPayments } from '@bob-payments/sdk';

const bob = new BobPayments({ apiKey: process.env.BOB_API_KEY! });

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' }, // R$ 100,00 — sempre centavos
  originDomain: 'loja.example.com',
});

console.log(tx.pixCode); // PIX copia-e-cola, pronto para o comprador

Recebendo a confirmação de pagamento (webhook):

import { constructWebhookEvent } from '@bob-payments/sdk';

// ⚠️ use o corpo BRUTO da request (ex.: express.raw()) — nunca o JSON re-serializado
const event = constructWebhookEvent(rawBody, req.headers['x-webhook-signature'], webhookSecret);

if (event.event === 'transaction.paid') {
  liberarPedido(event.data.transactionId); // v2: event.data.amountCents
}

Por que este SDK

| | | |---|---| | 🪶 Zero dependências | fetch nativo + node:crypto. Nada para conflitar com o seu lockfile. | | 🔁 Idempotência automática | Todo create envia Idempotency-Key e faz retry seguro em timeout/rede/5xx — sem risco de PIX duplicado. | | 🔐 Webhooks verificados | Assinatura HMAC em tempo constante, com proteção anti-replay (payload v2). | | 🧪 Sandbox de verdade | sk_test_ + gateway Bob Sandbox: pague, expire ou deixe pendente controlando os centavos do valor. | | 🇹 TypeScript first | Tipos completos do contrato da API, ESM + CJS. | | ⚠️ Erros úteis | BobPaymentsApiError com os campos RFC 7807 da API (status, code, detail, retryAfterSeconds). |

Documentação

A referência completa vive em docs.payments.bob.company:

| Guia | O que você encontra | |---|---| | Primeiros passos | API keys, ambientes live/sandbox, primeira cobrança | | Transações | create / get / list, filtros, idempotência, HTTP 202 | | Checkout hospedado | Sessões de checkout, redirect, polling de status | | Webhooks | Eventos, verificação de assinatura, payload v1 vs v2 | | Sandbox | Valores mágicos e fluxo de teste ponta a ponta | | Erros | Catálogo de códigos e como tratar cada um |

Desenvolvimento

pnpm install && pnpm test   # vitest · pnpm typecheck · pnpm build

Releases são automatizadas por semantic-release — commits Conventional Commits na main geram versão, CHANGELOG e GitHub Release. Publish no npm ativa com o secret NPM_TOKEN + npmPublish: true no .releaserc.json.