@setup-automatizado/sicredi-sdk

Production-grade TypeScript SDK for the Sicredi PIX and Boleto Hibrido APIs. Built for reliability and developer experience.

Features

Zero dependencies -- no external runtime dependencies, only dev tooling
mTLS authentication -- native mutual TLS support for Sicredi's certificate-based API
Auto-refresh tokens -- OAuth2 tokens are cached and refreshed automatically before expiry
Automatic retries -- configurable retry logic with exponential backoff for transient failures
Bun + Node.js -- first-class support for both runtimes (auto-detected)
Full TypeScript -- strict types for every request, response, and error
QR Code generation -- built-in SVG QR code generator for PIX "copia e cola" strings
Boleto Hibrido -- complete support for PIX charges with due dates, penalties, interest, and discounts
Webhook handling -- parse and validate Sicredi webhook callback payloads
Lazy initialization -- certificates and connections are set up on first use, not at construction

Requirements

Node.js >= 20.0.0 (LTS) or Bun >= 1.0
Node.js 20 (Maintenance LTS), 22 (Active LTS), and 24 (Active LTS) are supported
Node.js 18 reached End-of-Life in April 2025 and is not supported

Installation

# Bun (recommended)
bun add @setup-automatizado/sicredi-sdk

# npm
npm install @setup-automatizado/sicredi-sdk

# pnpm
pnpm add @setup-automatizado/sicredi-sdk

# yarn
yarn add @setup-automatizado/sicredi-sdk

Quick Start

import { Sicredi, generateTxId } from '@setup-automatizado/sicredi-sdk';

const sicredi = new Sicredi({
  clientId: process.env.SICREDI_CLIENT_ID!,
  clientSecret: process.env.SICREDI_CLIENT_SECRET!,
  certificate: {
    cert: './certs/certificado.pem',
    key: './certs/aplicacao.key',
    ca: './certs/CadeiaCompletaSicredi.pem',
  },
  environment: 'sandbox',
});

// Create a PIX charge
const txid = generateTxId();
const charge = await sicredi.cob.create(txid, {
  calendario: { expiracao: 3600 },
  devedor: { cpf: '12345678909', nome: 'Fulano de Tal' },
  valor: { original: '100.00' },
  chave: 'your-pix-key',
  solicitacaoPagador: 'Payment for order #123',
});

console.log(charge.pixCopiaECola); // PIX copy-and-paste string
console.log(charge.location);      // Payment URL

API Reference

Configuration

import { Sicredi } from '@setup-automatizado/sicredi-sdk';

const sicredi = new Sicredi({
  // Required
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  certificate: {
    cert: './path/to/cert.pem',   // or PEM string
    key: './path/to/key.pem',     // or PEM string
    ca: './path/to/ca.pem',       // optional, CA chain
    passphrase: 'optional',       // private key passphrase
  },

  // Optional
  environment: 'production',      // 'production' | 'sandbox' (default: 'production')
  baseUrl: 'https://custom.url',  // overrides environment URL
  timeout: 30000,                 // request timeout in ms (default: 30000)
  maxRetries: 3,                  // retry attempts (default: 3)
  debug: false,                   // enable debug logging (default: false)
});

The certificate fields accept either a file path or a PEM-encoded string directly. File paths are resolved relative to the current working directory.

PIX Imediato (`sicredi.cob`)

Immediate PIX charges without a due date.

Create a charge

const charge = await sicredi.cob.create(txid, {
  calendario: { expiracao: 3600 }, // expiration in seconds
  devedor: {
    cpf: '12345678909',            // or cnpj: '12345678000195'
    nome: 'Fulano de Tal',
  },
  valor: { original: '100.00' },
  chave: 'your-pix-key',
  solicitacaoPagador: 'Optional description',
  infoAdicionais: [
    { nome: 'Order', valor: '#12345' },
  ],
});

Create with auto-generated txid

const charge = await sicredi.cob.createAuto({
  calendario: { expiracao: 3600 },
  valor: { original: '50.00' },
  chave: 'your-pix-key',
});
// charge.txid is generated by Sicredi

Get a charge

const charge = await sicredi.cob.get(txid);
// Optional: pass a revision number
const charge = await sicredi.cob.get(txid, 2);

Update a charge

const updated = await sicredi.cob.update(txid, {
  valor: { original: '150.00' },
  solicitacaoPagador: 'Updated description',
});

Cancel a charge

const cancelled = await sicredi.cob.cancel(txid);
// Sets status to REMOVIDA_PELO_USUARIO_RECEBEDOR

List charges

const list = await sicredi.cob.list({
  inicio: '2026-01-01T00:00:00Z',
  fim: '2026-01-31T23:59:59Z',
  cpf: '12345678909',           // optional filter
  status: 'ATIVA',              // optional: ATIVA | CONCLUIDA | REMOVIDA_PELO_USUARIO_RECEBEDOR | REMOVIDA_PELO_PSP
  paginacao: {
    paginaAtual: 0,
    itensPorPagina: 10,
  },
});

console.log(list.parametros.paginacao.quantidadeTotalDeItens);
for (const cob of list.cobs) {
  console.log(cob.txid, cob.status, cob.valor.original);
}

Boleto Hibrido (`sicredi.cobv`)

PIX charges with a due date, supporting penalties, interest, and discounts.

Create a Boleto Hibrido

const cobv = await sicredi.cobv.create(txid, {
  calendario: {
    dataDeVencimento: '2026-03-15',      // due date (YYYY-MM-DD)
    validadeAposVencimento: 30,           // days valid after due date
  },
  devedor: {
    cnpj: '12345678000195',
    nome: 'Empresa Exemplo LTDA',
  },
  valor: {
    original: '1500.00',
    multa: {
      modalidade: 2,                      // 1 = fixed value, 2 = percentage
      valorPerc: '2.00',                  // 2% penalty
    },
    juros: {
      modalidade: 2,                      // 2 = percentage per month
      valorPerc: '1.00',                  // 1% per month
    },
    desconto: {
      modalidade: 1,                      // 1 = fixed value by date
      descontoDataFixa: [
        { data: '2026-03-10', valorPerc: '50.00' },
      ],
    },
  },
  chave: 'your-pix-key',
  solicitacaoPagador: 'Monthly invoice',
});

Get, update, cancel, and list

// Get
const cobv = await sicredi.cobv.get(txid);

// Update
const updated = await sicredi.cobv.update(txid, {
  valor: { original: '1600.00' },
});

// Cancel
const cancelled = await sicredi.cobv.cancel(txid);

// List
const list = await sicredi.cobv.list({
  inicio: '2026-01-01T00:00:00Z',
  fim: '2026-01-31T23:59:59Z',
});

Webhooks (`sicredi.webhook`)

Configure webhook URLs to receive PIX payment notifications.

Configure a webhook

await sicredi.webhook.configure('your-pix-key', 'https://your-domain.com/webhook/pix');

Get webhook configuration

const webhook = await sicredi.webhook.get('your-pix-key');
console.log(webhook.webhookUrl);
console.log(webhook.chave);
console.log(webhook.criacao);

List webhooks

const list = await sicredi.webhook.list({
  inicio: '2026-01-01T00:00:00Z',
  fim: '2026-01-31T23:59:59Z',
});

for (const wh of list.webhooks) {
  console.log(wh.chave, wh.webhookUrl);
}

Delete a webhook

await sicredi.webhook.delete('your-pix-key');

PIX Recebidos (`sicredi.pix`)

Query received PIX payments and request refunds/returns.

Get a received PIX payment

const pix = await sicredi.pix.get('E01181521202301011234abcdef12345');
console.log(pix.endToEndId);
console.log(pix.valor);
console.log(pix.chave);
console.log(pix.horario.solicitacao);

List received PIX payments

const list = await sicredi.pix.list({
  inicio: '2026-01-01T00:00:00Z',
  fim: '2026-01-31T23:59:59Z',
  txIdPresente: true,           // optional: filter by txid presence
  devolucaoPresente: false,     // optional: filter by refund presence
  paginacao: { paginaAtual: 0, itensPorPagina: 50 },
});

for (const pix of list.pix) {
  console.log(pix.endToEndId, pix.valor, pix.horario.solicitacao);
}

Request a refund (devolucao)

const refund = await sicredi.pix.requestReturn(
  'E01181521202301011234abcdef12345', // endToEndId
  'refund-001',                        // devolucao ID
  {
    valor: '50.00',
    natureza: 'ORIGINAL',              // optional: 'ORIGINAL' | 'RETIRADA'
    descricao: 'Refund for order #123',
  },
);

console.log(refund.rtrId);    // Return Transaction Reference ID
console.log(refund.status);   // 'EM_PROCESSAMENTO' | 'DEVOLVIDO' | 'NAO_REALIZADO'

Get refund status

const refund = await sicredi.pix.getReturn(
  'E01181521202301011234abcdef12345',
  'refund-001',
);
console.log(refund.status);

Lote CobV (`sicredi.lotecobv`)

Create and manage batches of Boleto Hibrido charges.

Create a batch

await sicredi.lotecobv.create(1, {
  descricao: 'January invoices',
  cobsv: [
    {
      txid: generateTxId(),
      calendario: { dataDeVencimento: '2026-02-15' },
      devedor: { cpf: '12345678909', nome: 'Cliente A' },
      valor: { original: '200.00' },
      chave: 'your-pix-key',
    },
    {
      txid: generateTxId(),
      calendario: { dataDeVencimento: '2026-02-15' },
      devedor: { cnpj: '12345678000195', nome: 'Empresa B' },
      valor: { original: '500.00' },
      chave: 'your-pix-key',
    },
  ],
});

Update specific charges in a batch

await sicredi.lotecobv.update(1, {
  cobsv: [
    { txid: 'existing-txid-here-12345678', valor: { original: '250.00' } },
  ],
});

Get batch status

const batch = await sicredi.lotecobv.get(1);
for (const item of batch.cobsv) {
  console.log(item.txid, item.status); // 'EM_PROCESSAMENTO' | 'CRIADA'
  if (item.problema) {
    console.error(item.problema.title, item.problema.detail);
  }
}

List batches

const list = await sicredi.lotecobv.list({
  inicio: '2026-01-01T00:00:00Z',
  fim: '2026-01-31T23:59:59Z',
});

Payload Locations (`sicredi.loc`)

Manage payload locations for QR codes.

Create a location

const loc = await sicredi.loc.create({ tipoCob: 'cob' }); // or 'cobv'
console.log(loc.id);
console.log(loc.location);

Get a location

const loc = await sicredi.loc.get(42);

List locations

const list = await sicredi.loc.list({
  inicio: '2026-01-01T00:00:00Z',
  fim: '2026-01-31T23:59:59Z',
  tipoCob: 'cobv', // optional filter
});

Unlink a txid from a location

await sicredi.loc.unlink(42);

Handle webhook callbacks

import { parseWebhookPayload } from '@setup-automatizado/sicredi-sdk';

// Works with Express, Koa, Bun, or any framework
const result = parseWebhookPayload(requestBody);

if (result.valid) {
  for (const pix of result.payload!.pix) {
    console.log(pix.endToEndId);
    console.log(pix.txid);
    console.log(pix.valor);
    console.log(pix.chave);
    console.log(pix.horario);
  }
}

Utilities

Transaction ID

import { generateTxId, isValidTxId } from '@setup-automatizado/sicredi-sdk';

const txid = generateTxId();        // 35-char alphanumeric string
const txid = generateTxId(26);      // custom length (26-35)
isValidTxId('abc123...');           // true/false

Validators

import {
  isValidCpf,
  isValidCnpj,
  isValidPixKey,
  detectPixKeyType,
  isValidMonetaryValue,
} from '@setup-automatizado/sicredi-sdk';

isValidCpf('12345678909');                                   // true/false (with check digits)
isValidCnpj('12345678000195');                               // true/false (with check digits)
isValidPixKey('+5511999999999');                              // true/false
detectPixKeyType('user@example.com');                         // 'email'
detectPixKeyType('12345678909');                              // 'cpf'
detectPixKeyType('a1b2c3d4-e5f6-7890-abcd-ef1234567890');    // 'evp'
isValidMonetaryValue('100.00');                               // true
isValidMonetaryValue('100.0');                                // false (must be 2 decimal places)

QR Code

import { generateQrCodeSvg, generateQrCodeDataUrl } from '@setup-automatizado/sicredi-sdk';

// Generate SVG string from PIX "copia e cola"
const svg = generateQrCodeSvg(charge.pixCopiaECola!, {
  size: 256,
  margin: 4,
  darkColor: '#000000',
  lightColor: '#FFFFFF',
});

// Generate data URL for embedding in HTML <img> tags
const dataUrl = generateQrCodeDataUrl(charge.pixCopiaECola!);
// <img src={dataUrl} alt="PIX QR Code" />

Date helpers

import {
  toISOString,
  createDateRange,
  parseDate,
  formatDateOnly,
} from '@setup-automatizado/sicredi-sdk';

const { inicio, fim } = createDateRange(30);   // last 30 days as ISO strings
const dateStr = formatDateOnly(new Date());     // '2026-02-08'
const date = parseDate('2026-02-08T00:00:00Z'); // Date object

Constants

import { SICREDI_URLS, SICREDI_ISPB } from '@setup-automatizado/sicredi-sdk';

SICREDI_URLS.production; // 'https://api-pix.sicredi.com.br'
SICREDI_URLS.sandbox;    // 'https://api-pix-h.sicredi.com.br'
SICREDI_ISPB;            // '01181521'

Error Handling

The SDK provides typed error classes for different failure scenarios:

import {
  SicrediApiError,
  SicrediAuthError,
  SicrediValidationError,
  SicrediConnectionError,
  SicrediCertificateError,
} from '@setup-automatizado/sicredi-sdk';

try {
  const charge = await sicredi.cob.create(txid, data);
} catch (error) {
  if (error instanceof SicrediApiError) {
    // API returned an error response (4xx/5xx)
    console.error('API Error:', error.statusCode);
    console.error('Title:', error.title);
    console.error('Detail:', error.detail);
    console.error('Violations:', error.violacoes);
  } else if (error instanceof SicrediAuthError) {
    // Authentication failed (invalid credentials, expired token)
    console.error('Auth Error:', error.message);
  } else if (error instanceof SicrediValidationError) {
    // Local validation failed (invalid txid, etc.)
    console.error('Validation Error:', error.message);
  } else if (error instanceof SicrediConnectionError) {
    // Network error (timeout, DNS, etc.)
    console.error('Connection Error:', error.message);
  } else if (error instanceof SicrediCertificateError) {
    // Certificate loading/validation failed
    console.error('Certificate Error:', error.message);
  }
}

All errors extend the base SicrediError class, which includes:

message -- human-readable error description
code -- machine-readable error code (e.g., 'API_ERROR', 'AUTH_ERROR')
hint -- optional suggestion for fixing the issue

Environments

Environment	Base URL	Description
`production`	`https://api-pix.sicredi.com.br`	Live Sicredi PIX API
`sandbox`	`https://api-pix-h.sicredi.com.br`	Homologation/testing environment

// Production (default)
const sicredi = new Sicredi({ environment: 'production', ... });

// Sandbox
const sicredi = new Sicredi({ environment: 'sandbox', ... });

// Custom URL (overrides environment)
const sicredi = new Sicredi({ baseUrl: 'https://custom-proxy.example.com', ... });

Certificate Setup

Sicredi requires mTLS (mutual TLS) for API authentication. You will need:

Client certificate (cert) -- your application's certificate in PEM format
Private key (key) -- the private key corresponding to the certificate in PEM format
CA chain (ca) -- Sicredi's complete certificate chain in PEM format (optional but recommended)

These are typically provided by Sicredi during the API onboarding process. If your certificates are in PKCS#12 (.p12 / .pfx) format, convert them to PEM:

# Extract certificate
openssl pkcs12 -in certificado.p12 -clcerts -nokeys -out certificado.pem

# Extract private key
openssl pkcs12 -in certificado.p12 -nocerts -nodes -out aplicacao.key

You can provide the certificate as file paths or directly as PEM strings:

// File paths (resolved from cwd)
certificate: {
  cert: './certs/certificado.pem',
  key: './certs/aplicacao.key',
  ca: './certs/CadeiaCompletaSicredi.pem',
}

// PEM strings (e.g., from environment variables)
certificate: {
  cert: process.env.SICREDI_CERT!,
  key: process.env.SICREDI_KEY!,
  ca: process.env.SICREDI_CA!,
}

Examples

See the examples/ directory for complete working examples:

basic-pix-charge.ts -- Create, query, and list PIX immediate charges
boleto-hibrido.ts -- Create Boleto Hibrido with penalties, interest, and discounts
webhook-setup.ts -- Configure, list, and delete webhooks
express-webhook-handler.ts -- Handle PIX webhook callbacks with Express

Contributing

Contributions are welcome! Please follow these steps:

Fork the repository
Create a feature branch (git checkout -b feat/my-feature)
Make your changes

Run checks:

bun run typecheck
bun run lint
bun run test

Commit using Conventional Commits format
Open a Pull Request

Development

# Install dependencies
bun install

# Type checking
bun run typecheck

# Linting
bun run lint

# Run tests
bun run test

# Run tests with coverage
bun run test:coverage

# Build
bun run build

Name		Name	Last commit message	Last commit date
Latest commit History 19 Commits
.github/workflows		.github/workflows
.husky		.husky
examples		examples
src		src
tests/unit		tests/unit
.gitignore		.gitignore
.npmrc		.npmrc
.releaserc.json		.releaserc.json
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
biome.json		biome.json
bun.lock		bun.lock
commitlint.config.js		commitlint.config.js
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

@setup-automatizado/sicredi-sdk

Features

Requirements

Installation

Quick Start

API Reference

Configuration

PIX Imediato (sicredi.cob)

Create a charge

Create with auto-generated txid

Get a charge

Update a charge

Cancel a charge

List charges

Boleto Hibrido (sicredi.cobv)

Create a Boleto Hibrido

Get, update, cancel, and list

Webhooks (sicredi.webhook)

Configure a webhook

Get webhook configuration

List webhooks

Delete a webhook

PIX Recebidos (sicredi.pix)

Get a received PIX payment

List received PIX payments

Request a refund (devolucao)

Get refund status

Lote CobV (sicredi.lotecobv)

Create a batch

Update specific charges in a batch

Get batch status

List batches

Payload Locations (sicredi.loc)

Create a location

Get a location

List locations

Unlink a txid from a location

Handle webhook callbacks

Utilities

Transaction ID

Validators

QR Code

Date helpers

Constants

Error Handling

Environments

Certificate Setup

Examples

Contributing

Development

License

About

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

PIX Imediato (`sicredi.cob`)

Boleto Hibrido (`sicredi.cobv`)

Webhooks (`sicredi.webhook`)

PIX Recebidos (`sicredi.pix`)

Lote CobV (`sicredi.lotecobv`)

Payload Locations (`sicredi.loc`)

Packages