# For AIs (LLMs) (/en/docs/cartao/for-ai)
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 [#endpoints-for-ais]
| URL | What it has |
| ------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| [`/cartao/llms.txt`](https://docs.payzu.com.br/cartao/llms.txt) | Markdown index with link and description of every page **from Card only**. |
| [`/cartao/llms-full.txt`](https://docs.payzu.com.br/cartao/llms-full.txt) | **All** of the Card doc concatenated into one file. |
| [`/llms.txt`](https://docs.payzu.com.br/llms.txt) | Global index (all PayZu products together). |
| [`/llms-full.txt`](https://docs.payzu.com.br/llms-full.txt) | Global dump (all PayZu products together). |
| [`/cartao-openapi.json`](https://docs.payzu.com.br/cartao-openapi.json) | OpenAPI 3 specification of the Card API: endpoints, schemas and errors. |
| [`/api-scalar-cartao`](https://docs.payzu.com.br/api-scalar-cartao) | Interactive Scalar rendering of the OpenAPI. |
| [`/api-swagger-cartao`](https://docs.payzu.com.br/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 [#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 [#use-cases]
### Quick question in ChatGPT/Claude [#quick-question-in-chatgptclaude]
Paste the URL `https://docs.payzu.com.br/cartao/llms-full.txt` in the conversation and ask something concrete:
```text
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
".." 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 [#cursor--copilot-in-the-editor]
Create a `.cursorrules` file or `.github/copilot-instructions.md` in your repo:
```text
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
- 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.json
```
### RAG / vector store [#rag--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 [#code-generation]
To generate an HTTP client, point the AI to `/cartao-openapi.json`:
```text
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 [#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.