# Virtual Pay API v2

> API REST de pagamentos PIX para lojistas: cobranças (QR Code / Copia e Cola), saques por chave PIX ou BR Code, saldo, taxas e webhooks. Autenticação por credenciais de cliente nos headers `x-client-id` e `x-client-secret`. Este arquivo é o ponto de partida para integrar com ajuda de IA; a referência completa, com todos os campos e exemplos, está em `llms-full.txt`.

## Para o assistente de IA que está integrando

- Use **apenas** os endpoints, campos, enums e exemplos descritos aqui e em `llms-full.txt`. Não invente campos nem endpoints: se algo não está documentado, não existe.
- Os exemplos de requisição e resposta são a fonte da verdade para o formato do JSON. Copie a estrutura deles.
- URL base de produção: `https://api.virtualpay.online/v2`. Não há ambiente de sandbox público: valide com valores pequenos.
- Toda requisição autenticada leva os headers `x-client-id` e `x-client-secret` (credenciais geradas no painel do lojista em *Configurações → Credenciais API*). Nunca coloque o `client_secret` em código de frontend ou em repositório.
- Na criação de transação, envie `idempotency_key` (UUID por operação): repetir a mesma chave devolve a mesma transação em vez de criar outra — é o que torna seguro fazer retry após timeout.
- Trate a resposta de forma assíncrona: um depósito nasce `pending` e vira `paid` depois; um saque nasce `pending` e termina em `paid`, `canceled`, `denied` ou `refund`. Prefira o webhook `transaction.updated` a consultar em laço; se consultar, use `GET /transactions/{uuid}` com intervalo de segundos, não milissegundos.
- Erros voltam como JSON com `message` (e `errors` por campo no 422). Mostre a mensagem, mas ramifique pelo código HTTP.
- Respeite o rate limit descrito abaixo; 429 significa esperar, não repetir imediatamente.

## Fluxo mínimo (o que um integrador faz na primeira hora)

1. Gerar as credenciais no painel e guardar o `client_secret` (aparece uma vez).
2. Consultar `POST https://api.virtualpay.online/v2/balance` para confirmar que a autenticação funciona.
3. Criar um depósito: `POST https://api.virtualpay.online/v2/transactions` com `type: "deposit"`, `amount`, `description`, `payment_method: "pix"` e um `idempotency_key`. A resposta traz o `copy_paste` (payload PIX) para renderizar como QR Code.
4. Cadastrar a URL de webhook no painel e tratar `transaction.updated` (status `paid`).
5. Consultar `GET https://api.virtualpay.online/v2/transactions/{uuid}` quando precisar do estado atual.
6. Para saque, `POST https://api.virtualpay.online/v2/transactions` com `type: "withdraw"`, `key_type` e `pix_key` — ou `br_code` para pagar um QR Code.

## Exemplo de chamada

```bash
curl -X POST https://api.virtualpay.online/v2/transactions \
  -H "x-client-id: $CLIENT_ID" \
  -H "x-client-secret: $CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"type":"deposit","amount":150.00,"description":"Pedido 1042","payment_method":"pix","idempotency_key":"$(uuidgen)","name":"Cliente Exemplo","document":"12345678909"}'
```

## Endpoints

- `POST /balance` — Consultar saldo e carteiras do merchant
- `POST /taxes` — Consultar taxas configuradas
- `POST /pix/dict` — Consultar chave PIX no DICT
- `POST /pix/parser` — Ler e Decodificar código EMV (Copia e Cola)
- `POST /transactions` — Criar uma nova transação
- `GET /transactions/{uuid}` — Consultar uma transação

## Webhooks (a API chama você)

- `transaction.updated` — Atualização de Status da Transação

## Referências

- [Referência completa para IA (todos os campos, enums, exemplos e webhooks)](https://mail.virtualpay.online/llms-full.txt)
- [OpenAPI 3.1 em YAML](https://mail.virtualpay.online/docs/openapi.yaml)
- [OpenAPI 3.1 em JSON](https://mail.virtualpay.online/docs/openapi.json)
- [Documentação interativa (Swagger UI)](https://mail.virtualpay.online/docs)

## Autenticação, erros e limites

## Autenticação

A API utiliza autenticação baseada em credenciais de cliente (Client Credentials). Todas as requisições autenticadas devem incluir suas credenciais nos headers HTTP.

### Headers Obrigatórios

Para cada requisição autenticada, você deve enviar os seguintes headers:

- **`x-client-id`**: Seu Client ID único (identificador do merchant)
- **`x-client-secret`**: Seu Client Secret (chave secreta para autenticação)

### Como Obter suas Credenciais

1. Acesse o painel administrativo do merchant
2. Navegue até a seção **Configurações → Credenciais API**
3. Suas credenciais serão exibidas na tela
4. O `client_secret` é exibido apenas uma vez após a criação/reset - guarde-o com segurança!

Se você perdeu seu `client_secret`, pode resetá-lo no painel. O secret anterior será invalidado imediatamente.

### Respostas de Erro de Autenticação

Se suas credenciais estiverem incorretas ou ausentes, você receberá uma das seguintes respostas:

#### 401 - Missing authentication credentials

```json
{
  "message": "Missing authentication credentials",
  "error": "x-client-id and x-client-secret headers are required, or provide a valid Bearer token"
}
```

**Causa**: Um ou ambos os headers de autenticação estão ausentes.

**Solução**: Verifique se você está enviando ambos os headers `x-client-id` e `x-client-secret` na requisição.

#### 401 - Invalid client credentials (Client ID não encontrado)

```json
{
  "message": "Invalid client credentials",
  "error": "Client ID not found or merchant is inactive"
}
```

**Causa**: O `client_id` informado não existe no sistema ou o merchant está inativo.

**Solução**: 
- Verifique se o `client_id` está correto
- Confirme se o merchant está ativo no painel administrativo
- Solicite novas credenciais se necessário

#### 401 - Invalid client credentials (Client Secret incorreto)

```json
{
  "message": "Invalid client credentials",
  "error": "Client secret mismatch"
}
```

**Causa**: O `client_secret` informado não corresponde ao `client_id` fornecido.

**Solução**:
- Verifique se o `client_secret` está correto (atenção a espaços em branco ou caracteres especiais)
- Se necessário, resete o `client_secret` no painel administrativo
- Lembre-se: após resetar, você precisará atualizar todas as aplicações que utilizam essa credencial

### Boas Práticas de Segurança

🔒 **Nunca exponha suas credenciais:**
- Não commite credenciais em repositórios Git públicos
- Use variáveis de ambiente para armazenar credenciais
- Não compartilhe credenciais via email, chat ou outras plataformas não seguras

🔐 **Proteja seu Client Secret:**
- O `client_secret` é equivalente a uma senha - trate-o com o mesmo nível de segurança
- Guarde-o em um gerenciador de senhas ou serviço de secrets (ex: AWS Secrets Manager, HashiCorp Vault)
- Implemente rotação regular de credenciais (resete periodicamente)

📊 **Monitoramento:**
- Monitore o uso das suas credenciais
- Se suspeitar de comprometimento, resete imediatamente o `client_secret`
- Utilize diferentes credenciais para ambientes diferentes (produção, staging, desenvolvimento)

🔄 **Gerenciamento:**
- Cada merchant possui um único par de credenciais
- Não é possível ter múltiplos pares de credenciais ativas simultaneamente
- Ao resetar o `client_secret`, o anterior é invalidado imediatamente

## Rate Limiting

A API possui limites de requisições por minuto para proteger os recursos do servidor.
Os limites atuais são:
- **100 requisições por minuto** por Client ID

Caso exceda o limite, receberá uma resposta `429 Too Many Requests`.