SDK Node.js

SDK oficial para Node.js: cobranças, saldo e verificação de webhooks com zero dependências (Node 18+, TypeScript incluído).

Instalação

npm

npm install carecapay

Beta: enquanto o pacote não está publicado no npm, instale a partir do repositório carecapay-sdk-node (npm install <caminho/git-url>).

A chave secreta é obrigatória

O construtor exige a sua chave secreta (ccp_secret_...), gerada no painel em Chaves de API — ela aparece uma única vez. Injete por variável de ambiente; o SDK rejeita na hora chaves vazias ou de outro formato. O ambiente vem da própria chave: ccp_secret_sandbox_ fala com o sandbox, ccp_secret_live_ com produção.

JavaScript

import CarecaPay from "carecapay";

const carecapay = new CarecaPay(process.env.CARECAPAY_SECRET_KEY);

Criar e acompanhar cobranças

JavaScript

const charge = await carecapay.charges.create({
  amount_cents: 1990,             // obrigatório, em centavos
  description: "Assinatura",      // opcional
  method: "pix",                  // opcional — hoje é o único disponível (padrão)
  currency: "BRL",                // opcional — hoje é a única disponível (padrão)
  external_reference: "order_42", // opcional — seu id do pedido, só guardamos e devolvemos
});
console.log(charge.qr_code);        // copia e cola do Pix
console.log(charge.qr_code_base64); // PNG já renderizado (base64), pronto pra exibir

await carecapay.charges.get(charge.id);
await carecapay.charges.list({ status: "paid", limit: 10 });
await carecapay.balance.get();

// só no sandbox: baixa fake (dispara o webhook também)
await carecapay.charges.simulatePayment(charge.id);

Verificando webhooks

O SDK valida a assinatura X-CarecaPay-Signature por você — use o corpo CRU da requisição e o segredo ccp_whsec_ do painel de Webhooks.

Express

import CarecaPay, { CarecaPayWebhookError } from "carecapay";

// Express: use o corpo CRU (express.raw), não o JSON já parseado.
app.post("/webhooks/carecapay", express.raw({ type: "*/*" }), (req, res) => {
  try {
    const event = CarecaPay.webhooks.constructEvent({
      payload: req.body.toString(),
      header: req.get("X-CarecaPay-Signature"),
      secret: process.env.CARECAPAY_WEBHOOK_SECRET,
    });
    if (event.type === "charge.paid") liberarPedido(event.data.id);
    res.sendStatus(200);
  } catch (err) {
    if (err instanceof CarecaPayWebhookError) return res.sendStatus(400);
    throw err;
  }
});

Sem o SDK, dá pra comparar o header X-CarecaPay-Token com o segredo diretamente — mais simples, mas sem detecção de corpo adulterado. Veja em Webhooks.

Erros tipados

Falhas da API viram CarecaPayError com code estável (o mesmo de Erros e status), message em português e o status HTTP. Falha de rede vira code network_error com status 0.

JavaScript

import { CarecaPayError } from "carecapay";

try {
  await carecapay.charges.create({ amount_cents: 0 });
} catch (err) {
  if (err instanceof CarecaPayError) {
    err.code;   // "invalid_amount"
    err.status; // 400
  }
}

Os shapes que o SDK devolve são exatamente os da API REST (snake_case) — o que está nestes docs é o que o seu código recebe.

Outros SDKs

Também oficiais: SDK PHP e SDK Python (veja os artigos ao lado). Os demais estão a caminho — enquanto isso, a API é REST simples e os exemplos cURL/HTTP funcionam em qualquer stack.

Parâmetro	Tipo	Descrição
`PHP`	disponível	SDK oficial — artigo SDK PHP nesta seção.
`Python`	disponível	SDK oficial — artigo SDK Python nesta seção.
`Laravel`	em breve	Pacote oficial planejado, por cima do SDK PHP.
`Go`	em breve	SDK oficial planejado. Use os exemplos HTTP por enquanto.
`Ruby`	em breve	SDK oficial planejado. Use os exemplos HTTP por enquanto.
`Java`	em breve	SDK oficial planejado. Use os exemplos HTTP por enquanto.