# PhanterPay

> Infraestrutura de pagamentos Pix no Brasil. API REST em JSON snake_case para cash-in
> (cobranças Pix) e cash-out (saques Pix), com webhooks assinados.

## Base URL

https://api.phanterpay.com.br/v1

## Documentação

- Referência da API: https://phanterpay.com.br/docs/api
- Prompts prontos para IAs: https://phanterpay.com.br/docs/ai
- OpenAPI 3.1: https://api.phanterpay.com.br/openapi.json
- Collection do Postman: https://phanterpay.com.br/phanterpay.postman_collection.json

## Autenticação

- Header `Authorization: Bearer <chave>` (alternativa: `x-api-key: <chave>`).
- Formato real da chave: `bp_<8 hex>_<48 hex>`. Não existem chaves públicas (`pk_`).
- Guarde a credencial na variável de ambiente `PHANTERPAY_API_KEY`. Nunca no código-fonte,
  no front-end ou em repositório.
- Escopos: charges:read, charges:write, payouts:read, payouts:write, balance:read,
  med:read, med:write. Escopo ausente devolve 403 FORBIDDEN.

## Regras básicas

- Não existe sandbox. Há um único ambiente e ele é produção: toda chamada pode movimentar
  dinheiro real na rede Pix. Valor mínimo por operação: R$ 2,00.
- `Idempotency-Key` (8 a 255 caracteres) é obrigatório em POST /charges e POST /payouts.
  Replay devolve a resposta original; corpo diferente devolve 409.
- Rate limit: 600 requisições por minuto por chave (headers x-ratelimit-*, retry-after em 429).
- Paginação por cursor: `limit` (1–200, padrão 50) e `starting_after`; resposta com
  `data`, `has_more` e `next_starting_after`. Não existe offset nem page.
- Erros usam sempre o envelope
  `{ "success": false, "error": { "code", "message", "retryable" }, "request_id" }`.
  Retente somente quando `retryable` for true.
- Split de pagamentos não é suportado.

## Endpoints

- POST /charges — cria cobrança Pix (retorna `pix.copy_paste` e `pix.qr_code_image`)
- GET /charges — lista cobranças (cursor)
- GET /charges/{id} — aceita `chg_...`, o txid do adquirente ou `ext:<external_id>`
- POST /payouts — cria saque Pix (amount é o valor líquido; resposta traz fee e gross_amount)
  A criação pode devolver processing, completed ou failed conforme o resultado da sincronização inicial.
- GET /payouts — lista saques (cursor)
- GET /payouts/{id} — consulta saque
- GET /balance — available_balance, pending_balance, blocked_balance, total_balance, currency
- GET /med, GET /med/{id}, POST /med/{id} — infrações Pix e envio de defesa
- /boletos e /card/charges — reservados: respondem HTTP 501 FEATURE_NOT_AVAILABLE

## Webhooks

- Webhooks são opcionais: dá para integrar só com a API REST (POST para criar, GET para consultar status).
  Para atualizações em tempo real e menos polling, recomendamos usar webhooks.
- Eventos entregues hoje: charge.created, charge.paid, payout.created, payout.completed,
  payout.failed.
- Assinatura: `x-phanterpay-signature: t=<unix>,v1=<hex>`, HMAC-SHA256 de `<t>.<corpo cru>`.
  Valide o corpo cru, rejeite timestamps com mais de 5 minutos e compare em tempo constante.