Instalação

Para começar o desenvolvimento, instale a biblioteca com seu gerenciador de pacotes favorito:

npm i pagamentos

yarn add pagamentos

pnpm add pagamentos

bun i pagamentos

Escolha um provedor de pagamento e conecte-o à sua aplicação. Neste exemplo, usaremos o mockProvider, mas você pode substituir por qualquer outro provedor disponível.

pagamentos.ts

import { Pagamentos, mockProvider } from 'pagamentos'

export const pg = new Pagamentos({
  providers: [mockProvider()]
})

Agora você pode usar a instância pg para acessar os métodos de pagamento.

Criando uma cobrança

Para criar uma cobrança com Pix, por exemplo:

async function criarCobranca() {
  const pagamento = await pg.cobrancas.create({
    idempotencyKey: crypto.randomUUID(),
    valor: 1000, // R$10,00 - valor em centavos 
    metodoPagamento: 'pix', // ou 'boleto', 'cartaoCredito', etc.
    cliente: {
      nome: 'João Silva', 
      documento: '123.456.789-00' // CPF ou CNPJ
    }
  })

  await salvarNoBanco(pagamento) // Salve os dados da cobrança no seu banco de dados
}

Consultando o status do pagamento

Para consultar o status de um pagamento, use o ID da cobrança:

async function consultarStatus(idCobranca: string) {
  const pagamento = await pg.cobrancas.get(idCobranca)

  console.log(pagamento.status) // 'pendente', 'pago', 'cancelado', etc.
}

Webhooks

Utilizando Hono como exemplo, você pode criar uma rota para processar webhooks do provedor:

main.ts

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

import { pg } from './pagamentos'

const app = new Hono()

app.post('/webhook', toHono(pg.webhooks.handler))

export default app

Confira todas as integrações com bibliotecas e frameworks disponíveis na seção de integrações.

Desenvolvimento local

Com o mockProvider, você pode simular pagamentos utilizando scripts de teste:

import { pg } from './pagamentos'

async function simularPagamento() {
  const cobrancas = await pg.cobrancas.list()
  const cobranca = cobrancas[0]

  await pg.providers.mock.simulateCobranca(cobranca.id) // Acessível apenas para o mockProvider
}

Isso é útil para testar o fluxo de pagamento e os webhooks sem precisar de um provedor real. Para mais informações sobre o mockProvider, acesse a documentação do provedor de teste. Para receber notificações de pagamento localmente de outros provedores, você pode utilizar as seguintes ferramentas:

Fundamentos

Métodos de Pagamento

Funcionalidades

Criando uma cobrança

Consultando o status do pagamento

Webhooks

Desenvolvimento local

​Criando uma cobrança

​Consultando o status do pagamento

​Webhooks

​Desenvolvimento local

Criando uma cobrança

Consultando o status do pagamento

Webhooks

Desenvolvimento local