# VaultPay | API para integracoes

> Documentacao publica da API VaultPay. Nao contem chaves, segredos nem detalhes internos de roteamento.

- Site principal: https://vaultpay.lat/
- Painel: https://vaultpay.lat/dashboard
- Documentacao: https://vaultpay.lat/docs
- API: https://api.vaultpay.lat/
- Especificacao para leitura por modelos: https://vaultpay.lat/llms.txt

## Autenticacao

API de clientes: cabecalho `Authorization: Bearer SUA_CHAVE_VAULTPAY`.
Operacoes de escrita: `Idempotency-Key` exclusiva e persistida pelo cliente.
As credenciais sao geradas por uma conta autorizada no painel e nunca devem ir para o frontend publico.

## Endpoints publicos

- `GET /v1/balance` | saldo da carteira em centavos.
- `POST /v1/pix` | cria cobranca Pix; body: `amountCents` e `description` opcional. Para contas da rota alternativa, `client` (nome, CPF, e-mail e telefone) e obrigatorio.
- `POST /v1/payments` | solicita transferencia Pix, quando permitida; body: `amountCents`, `pixKey`. Operacoes sao restritas por conta e rota.
- As configuracoes de webhooks e subcontas estao descritas na documentacao interativa.

## Tarifas publicas padrao

- Rota White: deposito R$ 0,40 por Pix, saque R$ 2,00.
- Rota Black: deposito R$ 1,50 + 3% do valor bruto de cada Pix, arredondado para centavo, sem faixas por valor. Saque previsto de R$ 5,00, atualmente indisponivel nesta rota.
- Tarifas individuais podem substituir a parcela fixa. Valores e disponibilidade devem ser consultados na conta antes de confirmar a operacao.
- Tarifas de deposito sao deduzidas do valor bruto recebido; nao sao cobradas duas vezes.

## Segurança e liquidação

Uma resposta HTTP 201 indica criacao da cobranca, nao pagamento confirmado. Confirmacao financeira ocorre por conciliacao e verificacao de status; eventos webhook podem ser repetidos e exigem idempotencia. Nao armazene tokens em codigo cliente. Em MED/contestacoes, operacoes podem ser bloqueadas para analise.

## Observacoes

Apenas endpoints implementados sao listados. Rota Black para saques permanece indisponivel ate homologacao. Documentacao nao substitui os termos comerciais da conta.