Skip to main content

​
Visão Geral

A SDK Node.js da Garu permite integrar pagamentos PIX, Cartão de Crédito e Boleto no seu projeto com poucas linhas de código. A SDK abstrai a API REST, usando valores em centavos e status simplificados para facilitar a integração.
Pré-requisito: Você precisa de uma chave de API. Veja como obter em Autenticação.

​
Instalação

npm install @garuhq/node

​
Inicialização

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

const garu = new Garu({
  apiKey: process.env.GARU_API_KEY,
});
Nunca coloque sua chave de API diretamente no código. Use variáveis de ambiente.

​
Cobranças

​
Criar uma cobrança PIX

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

​
Criar uma cobrança com cartão de crédito

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",
  },
});

​
Listar cobranças

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}`);
}

​
Consultar uma cobrança

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

​
Reembolsar uma cobrança

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

​
Clientes

​
Criar um cliente

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

​
Listar clientes

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

​
Consultar um cliente

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

​
Atualizar um cliente

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

​
Remover um cliente

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

​
Chaves de Idempotência

Use chaves de idempotência para garantir que uma operação não seja executada duas vezes, mesmo em caso de retry: 
const charge = await garu.charges.create(
  {
    amount: 4990,
    method: "pix",
    customer: { email: "joao@email.com" },
  },
  {
    idempotencyKey: "order_12345",
  },
);
Use o ID do pedido no seu sistema como chave de idempotência. Assim, mesmo que a requisição seja enviada duas vezes, apenas uma cobrança será criada.

​
Tratamento de Erros

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;
  }
}
Códigos de erro comuns:
Verifique os campos enviados. A resposta inclui detalhes sobre quais campos estão incorretos.
Confira se a variável GARU_API_KEY está definida e se a chave é válida.
O ID informado não corresponde a nenhum recurso existente.
A chave de idempotência já foi usada com dados diferentes. Use uma chave única por operação.
A requisição é válida mas viola uma regra de negócio (ex: valor mínimo, status incompatível).
Aguarde alguns segundos e tente novamente. Implemente backoff exponencial em automações.

​
Recursos

Repositório GitHub

Código-fonte e documentação técnica

Pacote npm

@garuhq/node no npm

​
Próximos Passos

MCP Server

Conecte agentes de IA à API

Webhooks

Receba notificações de pagamento