For AIs (LLMs)
The Card documentation in a format that ChatGPT, Claude, Cursor and the like understand: point the AI to a fixed URL or load the whole file and ask about charges, 3DS, antifraud, recurrence or webhooks.
The Card documentation is also served as plain text for AI assistants. You can paste a fixed URL into the chat or load the whole file into the context.
This doc is for the Card API (https://api.payzu.io/v1, mTLS + Bearer token obtained from POST /token, values in cents). The Pix API is a different system (https://api.payzu.processamento.com/v1, Bearer, values in reais) and has its own doc. Never mix the two in the same integration.
Endpoints for AIs
| URL | What it has |
|---|---|
/cartao/llms.txt | Markdown index with link and description of every page from Card only. |
/cartao/llms-full.txt | All of the Card doc concatenated into one file. |
/llms.txt | Global index (all PayZu products together). |
/llms-full.txt | Global dump (all PayZu products together). |
/cartao-openapi.json | OpenAPI 3 specification of the Card API: endpoints, schemas and errors. |
/api-scalar-cartao | Interactive Scalar rendering of the OpenAPI. |
/api-swagger-cartao | Swagger UI rendering of the OpenAPI. |
The specific dump /cartao/llms-full.txt holds only Card. The global dump /llms-full.txt puts Card and Pix in the same file, with different base URL, authentication (mTLS × Bearer) and value unit (cents × reais).
Per page
Every doc page has equivalent content in plain markdown. Replace /en/docs/... with /llms.mdx/docs/en/.../content.md:
| HTML page | Raw markdown |
|---|---|
/en/docs/cartao | /llms.mdx/docs/en/cartao/content.md |
/en/docs/cartao/webhooks | /llms.mdx/docs/en/cartao/webhooks/content.md |
/en/docs/cartao/three-d-secure | /llms.mdx/docs/en/cartao/three-d-secure/content.md |
At the top of every page are the Ask AI, Copy for LLM (copies the page's markdown) and View as Markdown (opens the page's markdown) buttons.
Use cases
Quick question in ChatGPT/Claude
Paste the URL https://docs.payzu.com.br/cartao/llms-full.txt in the conversation and ask something concrete:
PayZu Card API doc: https://docs.payzu.com.br/cartao/llms-full.txt
Base URL: https://api.payzu.io/v1 (sandbox: https://api.sandbox.payzu.io/v1).
Authentication: client certificate (mTLS) on every call + Bearer token obtained from
POST /token with Basic Auth (client_id:client_secret) and grant_type client_credentials.
Values in cents.
Show me a Node.js example that:
1. Gets the token from POST /token using the mTLS certificate.
2. Creates a R$ 100.00 charge ("amount": 10000) on POST /charges with postbackUrl.
3. Receives the webhook and validates the signature before processing: HMAC-SHA256 over
"<X-Webhook-Timestamp>.<X-Webhook-Nonce>.<raw body>" with the webhook secret,
compared with X-Webhook-Signature; rejects a timestamp (in milliseconds) older
than 5 minutes.
4. Deduplicates by charge id + status transition.Cursor / Copilot in the editor
Create a .cursorrules file or .github/copilot-instructions.md in your repo:
You are integrating with the PayZu Card API. It is a system independent from the Pix API.
Inviolable rules:
- Base URL: https://api.payzu.io/v1 (sandbox: https://api.sandbox.payzu.io/v1)
- Every call uses the client certificate (mTLS) provided by PayZu
- Token: POST /token with Basic Auth (client_id:client_secret) and {"grant_type": "client_credentials"};
the other routes receive Authorization: Bearer <access_token>
- Values (amount, unitPrice) in cents (R$ 10.90 = 1090); exchange rates (rate.bid, rate.ask) are decimals
- Webhook: POST to the charge's postbackUrl. Validate X-Webhook-Signature (hex HMAC-SHA256 over
"timestamp.nonce.payload" with the webhook secret) and reject an X-Webhook-Timestamp (milliseconds)
older than 5 minutes
- Respond to the webhook with 2xx within 5 s; a failed delivery gets up to 5 retries
- Deduplicate webhooks by charge id + status transition, never by X-Webhook-Nonce
- POST /charges is not idempotent: on a timeout, look for your externalId in GET /charges
(startDate and endDate) before retrying, or the charge is made twice
- Refund (PUT /charges/{chargeId}/reverse) is always for the full amount, once per charge; do not send amount
- NEVER use api.payzu.processamento.com (that is the Pix API: Bearer, values in reais)
Full reference: https://docs.payzu.com.br/cartao/llms-full.txt
OpenAPI: https://docs.payzu.com.br/cartao-openapi.jsonRAG / vector store
/cartao/llms-full.txt is the file to index the Card doc in a vector store (Pinecone, Qdrant, Supabase pgvector). Each ## section works as a chunk.
Code generation
To generate an HTTP client, point the AI to /cartao-openapi.json:
Generate a typed TypeScript client for this Card API:
https://docs.payzu.com.br/cartao-openapi.json
Base URL https://api.payzu.io/v1, mTLS + Bearer token from POST /token, values in cents.
Use Zod for runtime validation and undici with the client certificate.Updates
Every change published in the doc updates /cartao/llms.txt, /cartao/llms-full.txt and the markdown of each page on the next deploy. /cartao-openapi.json changes when the API gains new endpoints or schema changes.