# For AIs (LLMs) (/en/docs/pix-processamento/for-ai)
This documentation was designed to be consumed by both humans and AI assistants. You can copy the content straight into the chat or point the AI to a fixed URL.
From there, any question about Pix charges, webhooks, MED, authentication or error handling comes answered based on the actual doc.
This doc is for the **Pix Processamento** API (`https://api.payzu.processamento.com/v1`, Bearer, values in **reais**). The **Card** API is a different system (`https://api.payzu.io/v1`, mTLS + `client_credentials`, values in **cents**) and has its own doc. Never mix the two in the same integration, and there is no `pix.payzu.io`.
## Endpoints for AIs [#endpoints-for-ais]
| URL | What it has |
| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| [`/pix-processamento/llms.txt`](https://docs.payzu.com.br/pix-processamento/llms.txt) | Markdown-formatted index with link and description of every page **from Pix Processamento only**. |
| [`/pix-processamento/llms-full.txt`](https://docs.payzu.com.br/pix-processamento/llms-full.txt) | **All** of Pix Processamento concatenated into one file. Fits in the context of most LLMs. |
| [`/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). |
| [`/openapi.json`](https://docs.payzu.com.br/openapi.json) | OpenAPI 3 specification of the V1 API. Source-of-truth for endpoints, schemas, errors. |
| [`/api-scalar`](https://docs.payzu.com.br/api-scalar) | Interactive Scalar rendering of the OpenAPI. |
| [`/api-swagger`](https://docs.payzu.com.br/api-swagger) | Swagger UI rendering of the OpenAPI. |
| [`/payzu-pix.postman_collection.json`](https://docs.payzu.com.br/payzu-pix.postman_collection.json) | Postman collection ready to import. |
For a **Pix-only** integration, prefer the specific dump `/pix-processamento/llms-full.txt`. The global dump `/llms-full.txt` mixes Pix and Card in the same file and may lead the AI to confuse base URL, authentication (Bearer × mTLS) and value unit (reais × cents).
## 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/pix-processamento` | `/llms.mdx/docs/en/pix-processamento/content.md` |
| `/en/docs/pix-processamento/webhooks` | `/llms.mdx/docs/en/pix-processamento/webhooks/content.md` |
| `/en/docs/pix-processamento/best-practices/idempotency` | `/llms.mdx/docs/en/pix-processamento/best-practices/idempotency/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/pix-processamento/llms-full.txt` in the conversation and ask something concrete:
```text
PayZu Pix API doc (Processamento): https://docs.payzu.com.br/pix-processamento/llms-full.txt
Base URL: https://api.payzu.processamento.com/v1, auth Bearer token, values in reais.
Show me a Node.js example that:
1. Creates a Pix charge of R$ 100 (POST /pix) with idempotent clientReference.
2. Receives the webhook and validates the signature before processing:
the X-Callback-Signature header comes as "t=, v1=" and the HMAC-SHA256 is
over ".". Delivery to the callbackUrl is signed with the account
callback secret, when the account has one; a registered webhook uses the webhook
secret. Without a callback secret the delivery is not signed: create the secret
or protect the endpoint by source IP. There is no nonce.
3. Only marks the order as paid when the status is COMPLETED, deduplicating by id + event.
```
### 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 Pix Processamento API. It is a system independent from the Card API.
Inviolable rules:
- Base URL: https://api.payzu.processamento.com/v1
- Every call uses Authorization: Bearer + Content-Type: application/json
- Values in reais (BRL) as decimals, never cents (R$ 10.90 = "amount": 10.90)
- Unique and deterministic clientReference guarantees request idempotency
- Listings (GET) paginate with page + limit (max 100 in most; /user/transactions accepts up to 1000); the response envelope changes per route
- Webhook: validate the X-Callback-Signature header, which comes as "t=, v1=";
the HMAC-SHA256 is over "." with the webhook secret, and there is no nonce.
A registered webhook is signed with the webhook secret; delivery to the transaction's callbackUrl is signed with the account's callback secret, when it exists.
Respond 2xx within 5s. Each delivery gets up to 12 attempts; X-Callback-Attempt starts at 1
- Deduplicate callbacks by id + event (X-Callback-Event header): three events do not change the status
- Refund: POST /refund/{transactionId} is asynchronous; the response carries refundStatus and refunds[], one item per refund, newest first
- Resend: the /user/callbacks/resend* routes share a limit of 5 requests per minute per account; POST /user/callbacks/resend/webhook resends by filters
- Official SDK: npm install payzu-pix, pip install payzu-pix, composer require payzu/pix, gem install payzu-pix,
Maven br.com.payzu:payzu-pix, go get github.com/PayZuAI/payzu-sdks/go/v3
- NEVER use api.payzu.io (that is the Card API: mTLS, client_credentials, cents)
nor pix.payzu.io (does not exist)
Full reference: https://docs.payzu.com.br/pix-processamento/llms-full.txt
OpenAPI: https://docs.payzu.com.br/openapi.json
```
### RAG / vector store [#rag--vector-store]
The `/pix-processamento/llms-full.txt` is the ideal input to index the Pix doc in a vector store (Pinecone, Qdrant, Supabase pgvector). Chunk by `## section` and each chunk lands at 500-2000 tokens, a good granularity for retrieval. Index the Pix dump separately from the Card one so the retriever never crosses conventions between the two systems.
### Code generation [#code-generation]
Node.js, Python, PHP, Ruby, Java and Go have an [official SDK](/docs/pix-processamento/sdks). For another language or your own HTTP client, point the AI to `/openapi.json`:
```text
Generate a typed TypeScript client for this Pix API:
https://docs.payzu.com.br/openapi.json
Base URL https://api.payzu.processamento.com/v1, Bearer auth, values in reais.
Use Zod for runtime validation and native fetch.
```
## Updates [#updates]
Every change published in the doc updates automatically:
* `/llms.txt` and `/llms-full.txt` on the next deploy.
* `/openapi.json` when the API gains new endpoints or schema changes.
* The **Copy for LLM** button always copies the current version of the page.
If your AI gives an answer that seems outdated, ask it to re-fetch `https://docs.payzu.com.br/pix-processamento/llms-full.txt`.