> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pagamentos.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Instalação

> Como integrar **pagamentos.dev** na sua aplicação

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

<CodeGroup>
  ```bash npm theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  npm i pagamentos
  ```

  ```bash Yarn theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  yarn add pagamentos
  ```

  ```bash pnpm theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  pnpm add pagamentos
  ```

  ```bash Bun theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  bun i pagamentos
  ```
</CodeGroup>

Escolha um [provedor de pagamento](/provedores) e conecte-o à sua aplicação.

Neste exemplo, usaremos o `mockProvider`, mas você pode substituir por qualquer
outro provedor disponível.

```ts pagamentos.ts theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:

```ts theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:

```ts theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
async function consultarStatus(idCobranca: string) {
  const pagamento = await pg.cobrancas.get(idCobranca)

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

## Webhooks

Utilizando [Hono](https://hono.dev/) como exemplo, você pode criar uma rota para
processar webhooks do provedor:

```ts main.ts theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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](/integracoes).

## Desenvolvimento local

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

```ts theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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](/provedores/mock).

Para receber notificações de pagamento localmente de outros provedores, você
pode utilizar as seguintes ferramentas:

* [ngrok](https://ngrok.com/docs/guides/share-localhost/overview)
* [localtunnel](https://localtunnel.github.io/www/)
* [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/)