pagamentos.dev

SDK unificado para pagamentos no Brasil. Uma API, múltiplos provedores.
Conheça a documentação »

Introdução · Provedores · Integrações · Exemplos · Contribuindo

Introdução

O pagamentos.dev é um SDK unificado e open-source para processar pagamentos no Brasil. Em vez de aprender APIs diferentes para cada provedor, você usa uma única interface para criar cobranças, gerenciar clientes e receber webhooks — independentemente de estar integrado com Mercado Pago, AbacatePay, Woovi ou qualquer outro provedor suportado.

Por que usar?

• Uma API só — Troque de provedor sem reescrever código
• Webhooks unificados — Receba eventos de qualquer provedor com o mesmo formato
• TypeScript nativo — Tipagem completa e inferência automática
• Framework-agnostic — Funciona com Hono, Express, Fastify, Elysia, Next.js, Convex, Astro e mais
• Effect.ts suportado — Integração opcional com programação funcional

Provedores

O SDK suporta os principais provedores de pagamento do Brasil:

Provedor	Pix	Boleto	Cartão de Crédito
Mercado Pago	✅	✅	✅
AbacatePay	✅	—	—
Woovi	✅	✅	—
Pagar.me	✅	✅	✅
PagBank	✅	—	—
Asaas	✅	✅	—
Efí	✅	—	—
Rede	✅	—	—
Cielo	—	—	✅¹
PagHiper	✅	✅	—
Iugu	✅	✅	✅
Getnet	✅	—	✅
Stripe	✅	—	✅
Mock (testes)	✅	✅	✅

¹ Na Cielo, o fluxo unificado usa CardToken sem CVV e exige que o estabelecimento tenha autorização para essa modalidade.

Integrações

Conecte webhooks e checkout às suas ferramentas favoritas. O SDK possui adaptadores oficiais para os principais frameworks do ecossistema JavaScript:

Backend: Hono · Express · Fastify · Elysia · Convex

Fullstack: Next.js · Astro · TanStack Start

Instalação

bun i pagamentos

Também disponível via npm, Yarn e pnpm.

Começando

Configure o SDK com seu provedor preferido:

import { Pagamentos, mercadopago, onWebhookEvent } from 'pagamentos'

const pg = new Pagamentos({
  providers: [
    mercadopago({
      accessToken: process.env.MERCADOPAGO_ACCESS_TOKEN,
      signingSecret: process.env.MERCADOPAGO_WEBHOOK_SECRET
    })
  ],
  hooks: [
    onWebhookEvent('pagamento.realizado', (event) => {
      console.log('Pagamento recebido:', event.data.cobranca)
    })
  ]
})

Crie uma cobrança:

const cobranca = await pg.cobrancas.create({
  valor: 1000, // R$ 10,00
  metodoPagamento: 'pix',
  cliente: {
    nome: 'João Silva',
    documento: '123.456.789-00'
  }
})

console.log(cobranca.qrcode)

Receba webhooks com segurança:

import { Hono } from 'hono'
import { toHono } from 'pagamentos/hono'

const app = new Hono()
app.post('/webhook', toHono(pg.webhooks.handler))

Configuração dos novos provedores

Factory	Credenciais mínimas	Observação de produção
rede()	clientId (PV), clientSecret	OAuth2; o sandbox Pix conclui a cobrança e envia webhook automaticamente.
cielo()	merchantId, merchantKey, brand	O CardToken sem CVV só é habilitado com allowCardWithoutSecurityCode: true após autorização da Cielo.
paghiper()	apiKey, token	Não há sandbox isolado documentado; o webhook é confirmado por consulta autenticada à API.
iugu()	apiToken	O próprio token seleciona teste ou produção; suporta clientes, faturas, checkout e cartão tokenizado.
getnet()	clientId, clientSecret, sellerId	Usa a Regional API atual e OAuth2; não usa os endpoints brasileiros legados.
stripe()	secretKey, successUrl, cancelUrl	Use sk_test_… no sandbox e whsec_… para validar webhooks assinados.

Os valores são sempre passados em centavos inteiros. Segredos de webhook são opcionais apenas quando você não recebe callbacks; nunca coloque credenciais no bundle do navegador.

Handlers de webhook devem ser idempotentes e persistir o evento antes de executar efeitos irreversíveis. O SDK executa todos os handlers correspondentes, mas responde 500 se qualquer um falhar para permitir a retentativa do provedor.

Exemplos

Repositórios prontos para você copiar e colar:

• with-hono — API com Hono
• with-express — API com Express
• with-fastify — API com Fastify
• with-elysia — API com Elysia
• with-nextjs — API Route com Next.js
• with-astro — API Route com Astro
• with-tanstack-start — API Route com TanStack Start
• with-convex — HTTP Action com Convex

Stack

• TypeScript — linguagem
• Effect — programação funcional (opcional)
• Bun — runtime e gerenciador de pacotes
• tsup — bundler
• Vitest — testes
• Biome — lint e formatação

Contribuindo

Adoramos contribuições! Veja como você pode ajudar:

• Abra uma issue se encontrar um bug ou tiver uma ideia.
• Siga o guia de desenvolvimento para configurar seu ambiente.
• Faça um pull request com melhorias, correções ou novos provedores.

Desenvolvimento local

# Clone o repositório
git clone https://github.com/pagamentosdev/pagamentos.git
cd pagamentos

# Instale as dependências (inclui workspaces dos exemplos)
bun install

# Rode os testes
bun run test

# Verifique lint
bun run check

# Corrija problemas auto-fixáveis
bun run fix

# Build
bun run build

Requisitos

Pacote	Versão
bun	1.3.7+
node	18+

Licença

Lançado sob a licença MIT.

---

Feito com ❤️ no Brasil