# Vexa Pagamentos

> Software de checkout brasileiro single-merchant operado pelo CNPJ
> 51.848.548/0001-27. Suporta PIX, cartão de crédito (até 12x sem juros)
> e boleto bancário. API REST com idempotência obrigatória, webhooks
> HMAC-SHA256 e chaves par `pk_*` (pública) + `sk_*` (secreta).

Esta página é otimizada para consumo por agentes IA. Cole a URL no
Claude Code, Cursor ou ChatGPT e o agente já entende toda a integração
sem precisar treinar nada.

## Documentação

- [Doc completa](https://vexapagamentos.com/llms-full.txt): Toda a referência da API,
  schemas, exemplos cURL/Node/PHP/Python, fluxo de webhooks. ~2k linhas.
- [OpenAPI 3.0 (JSON)](https://vexapagamentos.com/openapi.json): Spec machine-readable
  pra geração automática de SDK.
- [OpenAPI 3.0 (YAML)](https://vexapagamentos.com/api/openapi.yaml): Mesma spec em YAML.

## Endpoints principais

- `GET /v1/me` — identifica a chave (smoke-test, não move dinheiro)
- `POST /v1/charges` — cria cobrança (PIX, cartão ou boleto)
- `GET /v1/charges` — lista cobranças do operador (paginado, com filtros)
- `GET /v1/charges/{id}` — consulta status
- `POST /v1/charges/{id}/capture` — captura cartão pré-autorizado
- `POST /v1/charges/{id}/simulate` — força status em sandbox (`sk_test_*` only)
- `POST /v1/subscriptions/{id}/cancel` — cancela assinatura

Base URL: `https://api.vexapagamentos.com/v1`. Auth: `Authorization: Bearer sk_live_...`.

## Conceitos

- **Chaves**: `pk_live_*` (pública, vai no front), `sk_live_*` (secreta, server-only).
- **Idempotência**: header `Idempotency-Key` obrigatório em criação.
- **Webhooks**: HMAC-SHA256, assinatura no header `X-Vexa-Signature: t=<unix>,v1=<hmac>`. Janela anti-replay 5min.
- **Saques**: NUNCA via API. Painel + 2FA. Decisão de produto.
- **Valores**: sempre em centavos (`amount_cents`), bigint internamente. Na response da API, `amount_cents` vem como **string** (preservação de precisão BigInt → JSON) — converta com `BigInt(s)` ou `Number(s)` no caller.
- **Status canônicos**: `pending`, `authorized`, `paid`, `failed`, `expired`, `refunded`, `partially_refunded`, `chargeback`.

## Métodos de pagamento

### PIX
`method: "pix"` → resposta inclui `qr_code` (EMV copia-e-cola),
`copy_paste_code`, `qr_code_image_url` (data URL PNG) e `expires_at`
(fixo em 30 minutos a partir da criação).

### Cartão
`method: "card"` + `productId` → API devolve `object: "checkout_session"` com
`checkout_url` pro Hosted Checkout da Vexa. Redirecione o comprador; ele paga
lá (3DS acontece dentro, transparente). Status final via webhook `charge.paid`
ou `charge.failed`. Suporta `installments` 1–12 e `returnUrl` opcional.
Cartão Gateway API puro (sem `productId`) retorna `422 unsupported_method_in_gateway_api`
enquanto o SDK Vexa.js (tokenização in-place) não fica pronto.

### Boleto
`method: "boleto"` → resposta inclui `boleto.digitable_line`, `boleto.barcode`,
`boleto.pdf_url`. Vencimento default D+3 (override via `boleto_due_date`).
Compensação 1–2 dias úteis após pagamento.

## Lifecycle e regras operacionais

A doc completa cobre — e a IA precisa ler antes de gerar código:

- **State machine** por método (`pending → paid / expired / failed / refunded`).
- **Fluxo end-to-end** com diagrama (Client → POST → Webhook → Merchant).
- **Implementação completa** Next.js: schema DB, server action, webhook handler, página.
- **Modelo de dados recomendado** (`orders`, `webhook_events`, dedupe por `evt_id`).
- **Production best practices** (✅/❌ — webhook vs polling, idempotency, HMAC timing-safe, etc.).
- **Common mistakes** (12 anti-patterns que quebram integração — confiar em redirect, `==` em HMAC, polling, etc.).
- **Erros estruturados** (`{error, message, details}` por código HTTP).
- **Regras operacionais por método** (PIX expira, cartão 3DS aguarda webhook, boleto compensa em 1-2 dias úteis e exige reconciliação).

## Como integrar com IA

```
Use a documentação em https://vexapagamentos.com/llms-full.txt
Implemente checkout PIX no meu projeto Next.js usando minha sk_test_…
Webhook em /api/webhooks/vexa com validação HMAC-SHA256 e dedupe por evt_id.
```

Cenários prontos disponíveis em https://vexapagamentos.com/integrations/ai.

## MCP Server (Model Context Protocol)

Endpoint MCP hospedado: `https://mcp.vexapagamentos.com/mcp`
(StreamableHTTP). Permite que agentes IA (Claude Desktop, Cursor, n8n,
agentes em cloud) controlem a Vexa em linguagem natural via 5 tools.

Tools: `createPixCharge`, `createBoletoCharge`, `getCharge`,
`listCharges`, `simulateChargePayment` (sandbox, `sk_test_*` only).
Cartão via tool MCP fica fora enquanto o SDK Vexa.js não chega — pra
cartão, redirecione o comprador pro Hosted Checkout (`https://checkout.vexapagamentos.com/{slug}`).

Setup Claude Desktop (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "vexa": {
      "command": "npx",
      "args": ["-y", "@vexagroup/mcp"],
      "env": {
        "VEXA_API_KEY": "sk_live_xxxxxxxxxxxxxxxx",
        "VEXA_API_BASE_URL": "https://api.vexapagamentos.com/v1"
      }
    }
  }
}
```

Setup n8n / agente HTTP: aponte pra `https://mcp.vexapagamentos.com/mcp`
com header `Authorization: Bearer sk_live_…`. Server não persiste a chave
(Map em RAM por sessão).