Para IAs (LLMs)
A documentação do Cartão num formato que o ChatGPT, o Claude, o Cursor e afins entendem: aponte a IA para uma URL fixa ou carregue o arquivo inteiro e pergunte sobre cobrança, 3DS, antifraude, recorrência ou webhooks.
A documentação do Cartão também é servida em texto puro para assistentes de IA. Você pode colar uma URL fixa no chat ou carregar o arquivo inteiro no contexto.
Esta doc é da API Cartão (https://api.payzu.io/v1, mTLS + token Bearer obtido em POST /token, valores em centavos). A API Pix é outro sistema (https://api.payzu.processamento.com/v1, Bearer, valores em reais) e tem doc própria. Nunca misture as duas na mesma integração.
Endpoints para IAs
| URL | O que tem |
|---|---|
/cartao/llms.txt | Índice em markdown com link e descrição de toda página só do Cartão. |
/cartao/llms-full.txt | Toda a doc do Cartão concatenada em um arquivo. |
/llms.txt | Índice global (todos os produtos PayZu juntos). |
/llms-full.txt | Dump global (todos os produtos PayZu juntos). |
/cartao-openapi.json | Especificação OpenAPI 3 da API Cartão: endpoints, schemas e erros. |
/api-scalar-cartao | Renderização Scalar interativa do OpenAPI. |
/api-swagger-cartao | Renderização Swagger UI do OpenAPI. |
O dump específico /cartao/llms-full.txt traz só o Cartão. O dump global /llms-full.txt reúne Cartão e Pix no mesmo arquivo, com base URL, autenticação (mTLS × Bearer) e unidade de valor (centavos × reais) diferentes.
Por página
Toda página da doc tem o conteúdo equivalente em markdown puro. Substitua /docs/... por /llms.mdx/docs/.../content.md:
| Página HTML | Markdown bruto |
|---|---|
/docs/cartao | /llms.mdx/docs/cartao/content.md |
/docs/cartao/webhooks | /llms.mdx/docs/cartao/webhooks/content.md |
/docs/cartao/three-d-secure | /llms.mdx/docs/cartao/three-d-secure/content.md |
No topo de cada página ficam os botões Perguntar à IA, Copiar para LLM (copia o markdown da página) e Ver como Markdown (abre o markdown da página).
Casos de uso
Pergunta rápida no ChatGPT/Claude
Cole a URL https://docs.payzu.com.br/cartao/llms-full.txt na conversa e peça algo concreto:
Doc da API Cartão PayZu: https://docs.payzu.com.br/cartao/llms-full.txt
Base URL: https://api.payzu.io/v1 (sandbox: https://api.sandbox.payzu.io/v1).
Autenticação: certificado de cliente (mTLS) em toda chamada + token Bearer obtido em
POST /token com Basic Auth (client_id:client_secret) e grant_type client_credentials.
Valores em centavos.
Me mostre um exemplo em Node.js que:
1. Obtém o token em POST /token usando o certificado mTLS.
2. Cria uma cobrança de R$ 100,00 ("amount": 10000) em POST /charges com postbackUrl.
3. Recebe o webhook e valida a assinatura antes de processar: HMAC-SHA256 sobre
"<X-Webhook-Timestamp>.<X-Webhook-Nonce>.<corpo cru>" com o webhook secret,
comparado com X-Webhook-Signature; recusa timestamp (em milissegundos) com mais
de 5 minutos.
4. Deduplica pelo id da cobrança + transição de status.Cursor / Copilot no editor
Crie um arquivo .cursorrules ou .github/copilot-instructions.md no seu repo:
Você está integrando com a API Cartão da PayZu. É um sistema independente da API Pix.
Regras invioláveis:
- Base URL: https://api.payzu.io/v1 (sandbox: https://api.sandbox.payzu.io/v1)
- Toda chamada usa o certificado de cliente (mTLS) fornecido pela PayZu
- Token: POST /token com Basic Auth (client_id:client_secret) e {"grant_type": "client_credentials"};
as demais rotas recebem Authorization: Bearer <access_token>
- Valores (amount, unitPrice) em centavos (R$ 10,90 = 1090); cotações de câmbio (rate.bid, rate.ask) são decimais
- Webhook: POST na postbackUrl da cobrança. Valide X-Webhook-Signature (HMAC-SHA256 em hex sobre
"timestamp.nonce.payload" com o webhook secret) e recuse X-Webhook-Timestamp (milissegundos)
com mais de 5 minutos
- Responda o webhook com 2xx em até 5 s; uma entrega que falha tem até 5 retentativas
- Deduplique webhooks pelo id da cobrança + transição de status, nunca pelo X-Webhook-Nonce
- POST /charges não é idempotente: num timeout, procure o seu externalId em GET /charges
(startDate e endDate) antes de repetir, senão a cobrança sai em dobro
- Estorno (PUT /charges/{chargeId}/reverse) é sempre do valor total, uma vez por cobrança; não envie amount
- NUNCA use api.payzu.processamento.com (essa é a API Pix: Bearer, valores em reais)
Referência completa: https://docs.payzu.com.br/cartao/llms-full.txt
OpenAPI: https://docs.payzu.com.br/cartao-openapi.jsonRAG / vector store
O /cartao/llms-full.txt é o arquivo para indexar a doc do Cartão em um vector store (Pinecone, Qdrant, Supabase pgvector). Cada ## seção funciona como um chunk.
Geração de código
Para gerar um cliente HTTP, aponte a IA para o /cartao-openapi.json:
Gere um cliente TypeScript tipado para esta API de Cartão:
https://docs.payzu.com.br/cartao-openapi.json
Base URL https://api.payzu.io/v1, mTLS + token Bearer de POST /token, valores em centavos.
Use Zod para validação de runtime e undici com o certificado de cliente.Atualização
Toda mudança publicada na doc atualiza /cartao/llms.txt, /cartao/llms-full.txt e o markdown de cada página no próximo deploy. O /cartao-openapi.json muda quando a API ganha endpoints novos ou mudanças de schema.