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

# Introdução

> Documentação da API Paybridge para integração de pagamentos PIX

## Bem-vindo

A API Paybridge permite integrar pagamentos PIX em suas aplicações de forma simples e segura.

## URL Base

```
https://api.paybridge.dev/v1
```

## Autenticação

Todas as requisições devem incluir o header `X-API-Key` com uma API Key válida.

```bash theme={null}
curl -X POST https://api.paybridge.dev/v1/payments \
  -H "X-API-Key: pk_test_sua_api_key" \
  -H "Content-Type: application/json"
```

### Tipos de API Key

| Tipo     | Prefixo     | Descrição                                   |
| -------- | ----------- | ------------------------------------------- |
| Teste    | `pk_test_*` | Pagamentos em sandbox, sem transações reais |
| Produção | `pk_live_*` | Pagamentos reais processados no PSP         |

## Rate Limiting

As requisições são limitadas a **100 por minuto** por API Key.

## Recursos Disponíveis

<CardGroup cols={2}>
  <Card title="Criar Pagamento" icon="qrcode" href="/api-reference/payments/create">
    Crie cobranças PIX com QR Code
  </Card>

  <Card title="Consultar Pagamento" icon="magnifying-glass" href="/api-reference/payments/get">
    Consulte o status de um pagamento
  </Card>

  <Card title="Webhooks" icon="bell" href="/api-reference/webhooks">
    Receba notificações de eventos
  </Card>
</CardGroup>

## Fluxo de Integração

```mermaid theme={null}
sequenceDiagram
    participant App as Sua Aplicação
    participant PB as Paybridge API
    participant PSP as Provedor PIX
    participant User as Usuário

    App->>PB: POST /payments
    PB->>PSP: Cria cobrança
    PSP-->>PB: QR Code PIX
    PB-->>App: Payment + QR Code
    App->>User: Exibe QR Code
    User->>PSP: Paga via PIX
    PSP->>PB: Webhook confirmação
    PB->>App: Webhook payment_completed
```

## Exemplo Rápido

```bash theme={null}
curl -X POST https://api.paybridge.dev/v1/payments \
  -H "X-API-Key: pk_test_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10.00,
    "description": "Pedido #123",
    "externalId": "pedido-123",
    "payer": {
      "name": "João Silva",
      "document": "12345678900",
      "email": "joao@email.com"
    }
  }'
```

**Resposta:**

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "amount": 10.00,
  "currency": "BRL",
  "status": "pending",
  "pixCopyPaste": "00020126580014br.gov.bcb.pix...",
  "pixQrCodeBase64": "data:image/png;base64,...",
  "expiresAt": "2026-01-28T15:30:00.000Z",
  "createdAt": "2026-01-28T15:00:00.000Z",
  "isTest": true
}
```