For AIs (LLMs)
This documentation was designed to be consumed by both humans and AI assistants. You can copy the content directly into a chat or point the AI to a fixed URL.
SKILL.md (recommended)
SKILL.md is the most compact and up-to-date way to guide an AI about the Conta Digital API. It contains inviolable rules, examples in Node.js + Python, enums, retry policy and common gotchas in ~7 KB.
Works with: Claude Code, Claude Desktop, Cursor, GitHub Copilot, Codeium, Continue, ChatGPT, Gemini, and any other tool that accepts markdown as instruction.
curl -o .claude/skills/payzu-conta-digital/SKILL.md https://docs.payzu.com.br/conta-digital/SKILL.mdYou are a senior engineer specialized in the PayZu PayZu Digital Account API. Your job is to design correct, idiomatic integrations for paying customers running in production.
Sources of truth (use only these, always):
- Full markdown: https://docs.payzu.com.br/conta-digital/llms-full.txt
- OpenAPI: https://docs.payzu.com.br/openapi/payzu-conta-digital-api.json
- Base URL: https://pix.payzu.io/v1
Scope: 13 endpoints across 3 groups. Banking-as-a-service via API: Pix in/out, TED, internal transfer, balance, profile, statement. Use cases: personal wallet, business account, ERP, BaaS.
Endpoint groups:
- Deposits: POST /pix (create charge), GET /pix/{id} (lookup), GET /proof/{id} (receipt), POST /pix/refund/{id} (refund)
- Withdrawals: POST /withdraw (Pix key), POST /withdraw/bank-data (bank/branch/account), POST /ted, POST /withdraw/qrcode (pay QR), POST /internal-transfer (PayZu to PayZu), GET /proof/{id}
- Account: GET /user/balance (available/blocked), GET /user (profile + limits + fees), GET /user/transactions (paged statement), GET /user/summary (volume and metrics)
Mandatory conventions (non-negotiable):
- Header: `Authorization: Bearer YOUR_TOKEN` on every call
- Header: `Content-Type: application/json` on every call with a body
- Amounts in **decimal BRL (Brazilian reais)**, never cents. R$ 10.90 is `"amount": 10.90`
- `clientReference` unique, deterministic, idempotent (use UUID v4 or `order-{id}`)
- `callbackUrl` must respond `2xx` within **5 seconds**. Heavy processing goes to a queue
- Webhook retries with exponential backoff up to **72 attempts**. Handle idempotency via `id + status`
- Dates in ISO 8601 UTC
Transaction status: `PENDING` → `COMPLETED` | `CANCELED` | `REFUNDED` | `EXPIRED`
Pix key type: `cpf`, `cnpj`, `phone` (5511…), `email`, `evp` (UUID)
Transaction type: `DEPOSIT` or `WITHDRAW`
Error handling:
- 4xx: client error. Don't retry, surface the message
- 5xx, 429, timeout: retry with exponential backoff + jitter, max 5 attempts
- Every error response includes `requestId`. **Always log `requestId`** and pass it to PayZu support when opening a ticket
When I ask questions, answer:
1. Straight to the point, with copy-paste-ready code
2. Curl first, then Node.js/Python/Go on request
3. Cite the endpoint and doc section when specific
4. If I ask for something outside the API scope, say so and propose an alternative
Don't invent endpoints, fields, or behaviors that aren't in the OpenAPI. If you don't know, say "not documented, contact support" and cite the `requestId` as the protocol.
I'm ready. What do you want to build?From there, any question about Pix deposit, withdrawal, TED, internal transfer, webhooks, authentication or error handling comes answered based on the real doc.
Endpoints for AIs
| URL | What it has |
|---|---|
/conta-digital/llms.txt | Markdown-formatted index with link and description of every page for Conta Digital only. |
/conta-digital/llms-full.txt | All of Conta Digital concatenated into one file. Fits in the context of most LLMs. |
/llms.txt | Global index (all PayZu products together). |
/llms-full.txt | Global dump (all PayZu products together). |
/openapi/payzu-conta-digital-api.json | OpenAPI 3 specification for Conta Digital. Source-of-truth for endpoints and schemas. |
/api-scalar-hub | Interactive Scalar rendering of the Conta Digital OpenAPI. |
/api-swagger-hub | Swagger UI rendering of the Conta Digital OpenAPI. |
Per page
Every doc page has the equivalent content in plain markdown. Replace /docs/... with /llms.mdx/docs/.../content.md:
| HTML page | Raw markdown |
|---|---|
/docs/conta-digital | /llms.mdx/docs/conta-digital/content.md |
/docs/conta-digital/webhooks | /llms.mdx/docs/conta-digital/webhooks/content.md |
/docs/conta-digital/depositos/createPixCharge | /llms.mdx/docs/conta-digital/depositos/createPixCharge/content.md |
And every doc page has a "Copy Markdown" button at the top, which copies straight to the clipboard.
Use cases
Quick question on ChatGPT/Claude
Paste the URL https://docs.payzu.com.br/conta-digital/llms-full.txt into the conversation and ask:
Here's the PayZu Conta Digital API doc: https://docs.payzu.com.br/conta-digital/llms-full.txt
Show me a Node.js example of creating a Pix charge for R$ 100
and handling the COMPLETED callback.Cursor / Copilot in the editor
Create a .cursorrules or .github/copilot-instructions.md file in your repo:
You are integrating with the PayZu Conta Digital API.
Inviolable rules:
- Every call uses Bearer token + Content-Type: application/json
- Base URL: https://pix.payzu.io/v1
- Values in reais (BRL), never cents
- Use a unique, deterministic clientReference for idempotência
- Respond to callbacks with 2xx within 5 seconds
- Dedupe callbacks by id + status, not just id
Full reference: https://docs.payzu.com.br/conta-digital/llms-full.txt
OpenAPI: https://docs.payzu.com.br/openapi/payzu-conta-digital-api.jsonRAG / vector store
The /llms-full.txt is the ideal input to index the doc in a vector store (Pinecone, Qdrant, Supabase pgvector). Chunk by ## section and each chunk lands at 500-2000 tokens, good granularity for retrieval.
Code generation
To generate an SDK or HTTP client, point the AI to /openapi/payzu-conta-digital-api.json:
Generate a typed TypeScript client for this API:
https://docs.payzu.com.br/openapi/payzu-conta-digital-api.json
Use Zod for runtime validation and native fetch.Updates
Every change published to the doc updates automatically:
/llms.txtand/llms-full.txton the next deploy/openapi/payzu-conta-digital-api.jsonwhenever the API gains new endpoints or schema changes- The "Copy Markdown" button always serves the rendered version of the current page
If your AI gives an answer that seems outdated, ask it to re-fetch https://docs.payzu.com.br/conta-digital/llms-full.txt. The publication timestamp is at the end of the file.