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

# Referência da API

> Base URL, autenticação, idempotência, paginação e modelo de erros.

Esta referência é gerada a partir da especificação **OpenAPI 3.1** da PlugToPay. Cada endpoint abaixo inclui um playground interativo — preencha os parâmetros e envie a requisição direto da documentação.

## Base URL

Todos os endpoints são relativos a:

```
https://dev.plugtopay.com/api/v1
```

## Autenticação

| Esquema          | Headers                         | Quem usa                              |
| ---------------- | ------------------------------- | ------------------------------------- |
| Sem autenticação | —                               | Cadastro, login, callbacks de gateway |
| API Key          | `X-Client-ID` + `X-API-Key`     | Integrações servidor-a-servidor       |
| Bearer JWT       | `Authorization: Bearer <token>` | Painel administrativo                 |

As rotas de integração (`/payments`, `/payments/pix`, `/sub-accounts`, `GET /payments`) exigem **ambos** os headers de API Key. As rotas de painel (`/user/...`) usam o JWT emitido no login. Veja [Autenticação](/authentication) para obter e gerenciar credenciais.

## Idempotência

Os endpoints de criação de pagamento aceitam o header `Idempotency-Key`. Reenviar a mesma requisição com a mesma chave nunca gera cobranças duplicadas — veja [Idempotência](/idempotency).

## Paginação

Endpoints de listagem retornam um envelope com `data` e `meta`:

```json theme={null}
{
  "data": [],
  "meta": { "current_page": 1, "per_page": 15, "total": 142, "last_page": 10 }
}
```

Controle a página com os parâmetros `page` e `per_page`.

## Status das transações

O campo `status` de um pagamento pode ser `pending`, `approved`, `failed` ou `refunded` (mais o estado transitório `processing` em respostas `202`). Veja [Status das transações](/status-codes) para a ação recomendada em cada estado.