VXVexa Pagamentos

Build with AI

Acelere a integração da Vexa Pagamentos usando agentes IA. Tudo aqui é otimizado pra consumo por Claude Desktop, Cursor, ChatGPT, n8n e qualquer cliente que fale OpenAPI ou MCP.

1. URLs machine-readable

Cole essas URLs em qualquer agente IA — ele já entende toda a Vexa sem treinar nada.

  • /llms.txt — índice (~50 linhas, padrão llmstxt.org)
  • /llms-full.txt — doc completa (~1k linhas com schemas, exemplos, fluxos)
  • /openapi.json — spec OpenAPI 3.0 pra geração automática de SDK

2. Prompt base

Cole esse prompt no início da conversa com o agente, junto com sua sk_test_... (sandbox). Em produção, troque por sk_live_....

Use a documentação da Vexa Pagamentos em https://vexapagamentos.com/llms-full.txt

Contexto:
- Base URL: https://api.vexapagamentos.com/v1
- Auth: Authorization: Bearer sk_test_...   (cole sua sk_test_ abaixo)
- Idempotency-Key obrigatório em todo POST de criação
- Webhooks: HMAC-SHA256, header X-Vexa-Signature: t=<unix>,v1=<hmac>
- Valores em centavos (amount_cents), bigint internamente

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.

3. MCP Server (Model Context Protocol)

Endpoint hospedado: https://mcp.vexapagamentos.com/mcp. Permite que agentes IA controlem a Vexa em linguagem natural, com 5 tools que mapeiam pros endpoints REST.

Tools

  • createPixCharge — gera PIX com QR Code + copia-e-cola
  • createBoletoCharge — boleto registrado com PDF, código de barras, linha digitável
  • getCharge, listCharges — consulta status
  • simulateChargePayment — força paid no sandbox (sk_test_* only)

Cartão fica fora da MCP enquanto o SDK Vexa.js (tokenização in-place) não chega — pra cartão, o agente AI deve usar a API REST POST /v1/charges com method=card e devolver o checkout_url do Hosted Checkout pro usuário humano finalizar.

Setup Claude Desktop / Cursor (stdio)

Edite claude_desktop_config.json (Linux: ~/.config/claude/; macOS: ~/Library/Application Support/Claude/):

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

Reinicie o Claude Desktop e a conexão "vexa" aparece com 5 tools.

Setup n8n / agente HTTP

Aponte o cliente MCP do agente pra https://mcp.vexapagamentos.com/mcp com header Authorization: Bearer sk_live_… em todo request. Aceita ambos application/json e text/event-stream no Accept.

O server não persiste a chave: mantém só Map<sessionId, apiKey> em RAM enquanto a sessão estiver viva (TTL 30min). Restart limpa tudo.

Segurança

  • Sem acesso direto ao DB — wrapper de fetch() na API REST v1.
  • Bearer fora do padrão sk_(test|live)_\w{16,128} é rejeitado em 401 antes de alocar sessão (anti-DoS).
  • Logs sanitizados: PAN, CVV e chaves sk_* são redactados em qualquer linha de erro.
  • Isolamento por sessão — cada conexão tem sua própria instância de servidor MCP, sem state compartilhado entre tenants.

Suporte

Dúvidas: contato@vexapagamentos.com. Status: /status.