Node.js SDK

npm install @garuhq/node

import { Garu } from "@garuhq/node";

const garu = new Garu({
  apiKey: process.env.GARU_API_KEY,
});

const charge = await garu.charges.create({
  amount: 4990, // R$ 49,90 em centavos
  method: "pix",
  customer: {
    name: "João Silva",
    email: "joao@email.com",
    document: "12345678900",
  },
});

console.log(charge.id); // ID da cobrança
console.log(charge.pixCode); // Código PIX copia-e-cola
console.log(charge.qrCodeUrl); // URL do QR Code

const charge = await garu.charges.create({
  amount: 29700, // R$ 297,00 em centavos
  method: "credit_card",
  installments: 3,
  customer: {
    name: "Maria Silva",
    email: "maria@email.com",
    document: "98765432100",
  },
});

const charges = await garu.charges.list({
  status: "paid",
  limit: 10,
});

for (const charge of charges.data) {
  console.log(`${charge.id}: R$ ${charge.amount / 100} — ${charge.status}`);
}

const charge = await garu.charges.get("charge_12345");
console.log(charge.status); // "paid", "pending", "refunded", etc.

const refund = await garu.charges.refund("charge_12345");
console.log(refund.status); // "refunded"

const customer = await garu.customers.create({
  name: "João Silva",
  email: "joao@email.com",
  document: "12345678900",
  phone: "11999999999",
});

const customers = await garu.customers.list({ limit: 20 });

const customer = await garu.customers.get("cust_abc123");

const customer = await garu.customers.update("cust_abc123", {
  phone: "11988888888",
});

await garu.customers.delete("cust_abc123");

const overdue = await garu.customers.list({ status: "overdue" });
// retorna apenas clientes com pelo menos uma cobrança agendada em atraso

const charge = await garu.scheduledCharges.create({
  customerId: 42,
  amount: 297.5, // BRL decimal, NÃO centavos
  type: "one_time",
  dueDate: "2026-06-15", // YYYY-MM-DD, fuso de São Paulo
  methods: ["pix", "boleto"],
  description: "Mensalidade Junho",
});
console.log(charge.id); // sch_abc123

// Múltiplos status como array
const upcoming = await garu.scheduledCharges.list({
  status: ["scheduled", "due_today"],
  limit: 50,
});

// Em atraso de um cliente específico
const overdueForCustomer = await garu.scheduledCharges.list({
  status: "overdue",
  customerId: 42,
});

// Janela de vencimento + busca pelo cliente
const this_month = await garu.scheduledCharges.list({
  dueFrom: "2026-06-01",
  dueTo: "2026-06-30",
  search: "maria",
});

const { charge, events, transactions } =
  await garu.scheduledCharges.get("sch_abc123");

// charge.amount é BRL decimal; transactions[].value é centavos.

// Adiar
await garu.scheduledCharges.postpone("sch_abc123", {
  newDueDate: "2026-07-01",
  reason: "cliente pediu mais prazo",
});

// Pausar (sem lembretes até retomar)
await garu.scheduledCharges.pause("sch_abc123", { reason: "em negociação" });

// Retomar
await garu.scheduledCharges.resume("sch_abc123");

// Marcar como paga (pagamento off-Garu)
await garu.scheduledCharges.markPaid("sch_abc123", {
  paymentDate: "2026-06-20",
  externalReference: "TED 4472881",
});

// Cobrar agora (dispara na hora, sem esperar o vencimento; idempotente por ciclo)
const result = await garu.scheduledCharges.chargeNow("sch_abc123");
result.outcome; // 'dispatched' | 'already_sent' | 'not_sent' | 'failed'
result.message; // texto pt-BR pronto para exibir

const charge = await garu.charges.create(
  {
    amount: 4990,
    method: "pix",
    customer: { email: "joao@email.com" },
  },
  {
    idempotencyKey: "order_12345",
  },
);

import { Garu, GaruError } from "@garuhq/node";

try {
  const charge = await garu.charges.create({
    amount: 100, // valor muito baixo
    method: "pix",
    customer: { email: "joao@email.com" },
  });
} catch (error) {
  if (error instanceof GaruError) {
    console.error(`Erro ${error.status}: ${error.message}`);
    console.error("Detalhes:", error.errors);
  } else {
    throw error;
  }
}