Skip to main content
SDK oficial da ClickPay para JavaScript e TypeScript. Integre pagamentos PIX, gestão de clientes, produtos, webhooks e saques em qualquer ambiente JS — Node.js, NestJS, Next.js, browser e mais.

​
Instalação

npm install @clickpay/sdk

​
Início Rápido e Simples

import { ClickPay, WebhookEvent } from '@clickpay/sdk';

const clickpay = new ClickPay({
  apiKey: 'cpk_sandbox_sua_chave_aqui',
});

​
Cobranças

const charge = await clickpay.charges.createPaymentLink({
  total: 5000, // R$ 50,00 (em centavos)
  customer: {
    taxId: '12345678900',
    name: 'João Silva',
    email: 'joao@email.com',
    phone: '11999999999',
  },
  successUrl: 'https://meusite.com/sucesso',
  failedUrl: 'https://meusite.com/falha',
  items: [
    { productId: 'prod_abc123', quantity: 2 },
  ],
});

console.log(charge.data?.url); // URL da página de pagamento

​
Criar Cobrança PIX Direta

const pix = await clickpay.charges.createPixCharge({
  amount: 1500, // R$ 15,00
  customer: {
    taxId: '12345678900',
    name: 'Maria Santos',
    email: 'maria@email.com',
    phone: '11988888888',
  },
  expiresIn: 900, // 15 minutos em segundos
});

console.log(pix.data?.brCode);       // PIX copia-e-cola
console.log(pix.data?.brCodeBase64); // QR Code em base64

​
Consultar Cobrança

const charge = await clickpay.charges.getById('charge_id_aqui');

console.log(charge.data?.status);        // OPEN | COMPLETED | EXPIRED
console.log(charge.data?.paymentStatus); // PENDING | PROCESSING | PAID | EXPIRED

const pixPayment = await clickpay.charges.generatePixForCharge('charge_id', {
  customer: {
    taxId: '12345678900',
    name: 'João Silva',
    email: 'joao@email.com',
    phone: '11999999999',
  },
});

​
Simular Pagamento (Sandbox)

Funciona apenas com cobranças criadas com devMode: true.
await clickpay.charges.simulatePayment('charge_id');

​
Idempotência

As operações de criação de cobrança suportam chave de idempotência (UUID v4, TTL 24h): 
const charge = await clickpay.charges.createPixCharge(
  {
    amount: 5000,
    customer: {
      taxId: '12345678900',
      name: 'João Silva',
      email: 'joao@email.com',
      phone: '11999999999',
    },
  },
  { idempotencyKey: 'f47ac10b-58cc-4372-a567-0e02b2c3d479' },
);

​
Clientes

import { DefaultStatus } from '@clickpay/sdk';

// Listar todos
const customers = await clickpay.customers.list();

// Buscar por ID
const customer = await clickpay.customers.getById('cust_abc123');

// Criar cliente
const newCustomer = await clickpay.customers.create({
  name: 'João Silva',
  taxId: '12345678900',
  email: 'joao@email.com',
  phone: '11999999999',
  status: DefaultStatus.ACTIVE,
  postalCode: '01001000',
  address: 'Praça da Sé',
  number: '1',
  district: 'Sé',
});

// Atualizar cliente
await clickpay.customers.update({
  id: 'cust_abc123',
  phone: '11977777777',
  status: DefaultStatus.INACTIVE,
});

​
Produtos

import { DefaultStatus } from '@clickpay/sdk';

// Listar produtos
const products = await clickpay.products.list({ status: DefaultStatus.ACTIVE });

// Buscar por ID
const product = await clickpay.products.getById('prod_abc123');

// Buscar por SKU
const productBySku = await clickpay.products.getBySku('PLAN-MONTHLY');

// Criar produto
const newProduct = await clickpay.products.create({
  name: 'Plano Mensal',
  description: 'Assinatura mensal do serviço',
  price: 4990, // R$ 49,90 (em centavos)
  sku: 'PLAN-MONTHLY',
});

// Atualizar produto
await clickpay.products.update({
  id: 'prod_abc123',
  price: 5990,
});

​
Webhooks

import { WebhookEvent } from '@clickpay/sdk';

// Listar webhooks
const webhooks = await clickpay.webhooks.list();

// Criar webhook
const webhook = await clickpay.webhooks.create({
  name: 'Meu Webhook',
  url: 'https://meusite.com/webhooks/clickpay',
  events: [WebhookEvent.CHARGE_PAID, WebhookEvent.CHARGE_EXPIRED],
});

// Atualizar webhook
await clickpay.webhooks.update({
  id: 'wh_abc123',
  events: [WebhookEvent.CHARGE_PAID],
});

// Deletar webhook
await clickpay.webhooks.delete('wh_abc123');

// Listar eventos disponíveis
const events = await clickpay.webhooks.listEvents();

// Estatísticas da fila
const stats = await clickpay.webhooks.getQueueStats();

​
Conta

// Consultar saldo
const balance = await clickpay.account.getBalance();

// Criar saque (transferência PIX)
const withdraw = await clickpay.account.withdraw({
  value: 10000, // R$ 100,00
});

// Listar histórico de saques
const withdrawals = await clickpay.account.listWithdrawals();

​
Configuração Avançada

​
Opções do Cliente

const clickpay = new ClickPay({
  // Autenticação (obrigatório)
  apiKey: 'cpk_sandbox_sua_chave_aqui',

  // URL customizada (padrão: https://api.clickpay.app.br)
  baseUrl: 'https://minha-api.com',

  // Ambiente sandbox
  sandbox: true,

  // Timeout em ms (padrão: 30000)
  timeout: 15000,

  // Retentativas automáticas em 429/5xx (padrão: 2)
  maxRetries: 3,

  // Headers extras
  headers: {
    'X-Custom-Header': 'valor',
  },

  // fetch customizado (Node.js < 18)
  fetch: customFetchImplementation,
});
OpçãoTipoPadrãoDescrição
apiKeystring—Chave de API para autenticação (obrigatório)
baseUrlstringhttps://api.clickpay.app.brURL base da API
sandboxbooleanfalseHabilita ambiente sandbox
timeoutnumber30000Timeout das requisições em milissegundos
maxRetriesnumber2Número máximo de retentativas em erros 429/5xx
headersobject{}Headers HTTP adicionais
fetchfunctionglobalThis.fetchImplementação customizada de fetch

​
Tratamento de Erros

import {
  ClickPay,
  ClickPayApiError,
  ClickPayRateLimitError,
  ClickPayIdempotencyError,
  ClickPayTimeoutError,
  ClickPayNetworkError,
} from '@clickpay/sdk';

try {
  await clickpay.charges.createPixCharge({ /* ... */ });
} catch (error) {
  if (error instanceof ClickPayRateLimitError) {
    console.log(`Rate limited. Tente novamente em ${error.retryAfter}s`);
  } else if (error instanceof ClickPayIdempotencyError) {
    console.log('Conflito de chave de idempotência');
  } else if (error instanceof ClickPayTimeoutError) {
    console.log('Timeout na requisição');
  } else if (error instanceof ClickPayNetworkError) {
    console.log('Erro de rede:', error.message);
  } else if (error instanceof ClickPayApiError) {
    console.log(`Erro da API ${error.statusCode}: ${error.message}`);
    console.log('Corpo da resposta:', error.body);
  }
}
Classe de ErroDescrição
ClickPayApiErrorErro genérico da API (classe base)
ClickPayRateLimitErrorLimite de requisições excedido (429)
ClickPayIdempotencyErrorConflito de chave de idempotência
ClickPayTimeoutErrorTimeout na requisição
ClickPayNetworkErrorErro de conexão/rede

​
Valores Monetários

Todos os valores monetários na SDK são representados em centavos (inteiros):
Valor RealValor na SDK
R$ 5,00500
R$ 49,904990
R$ 100,0010000
O valor mínimo para cobranças é 500 (R$ 5,00).

​
Tipos e Enums

Todos os tipos TypeScript são exportados para uso direto: 
import type {
  Customer,
  CreateCustomerInput,
  ChargeDetail,
  CreatePixChargeInput,
  Product,
  Webhook,
  ClickPayResponse,
} from '@clickpay/sdk';

import {
  DefaultStatus,    // ACTIVE | INACTIVE
  ChargeStatus,     // OPEN | COMPLETED | EXPIRED
  PaymentStatus,    // PENDING | PROCESSING | PAID | EXPIRED
  WebhookEvent,     // CHARGE_PAID | CHARGE_EXPIRED | ...
  WithdrawStatus,   // Status de saques
} from '@clickpay/sdk';

​
Uso com NestJS

import { Module, Injectable } from '@nestjs/common';
import { ClickPay } from '@clickpay/sdk';

@Module({
  providers: [
    {
      provide: ClickPay,
      useFactory: () =>
        new ClickPay({ apiKey: process.env.CLICKPAY_API_KEY }),
    },
  ],
  exports: [ClickPay],
})
export class ClickPayModule {}

// No service:
@Injectable()
export class PaymentService {
  constructor(private readonly clickpay: ClickPay) {}

  async createCharge(amount: number) {
    return this.clickpay.charges.createPixCharge({
      amount,
      customer: { /* ... */ },
    });
  }
}

​
Compatibilidade

AmbienteSuportado
Node.js >= 18✅
Bun✅
Deno✅
Browser (ESM)✅
NestJS✅
Next.js✅
React Native✅
Para Node.js < 18, passe uma implementação de fetch via a opção fetch (ex: node-fetch ou undici).