PayZuPayZu Docs

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 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.md
Copy and paste into your AI
Ready-made prompt: points ChatGPT, Claude, Gemini, or Cursor to this doc.
You 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

URLWhat it has
/conta-digital/llms.txtMarkdown-formatted index with link and description of every page for Conta Digital only.
/conta-digital/llms-full.txtAll of Conta Digital concatenated into one file. Fits in the context of most LLMs.
/llms.txtGlobal index (all PayZu products together).
/llms-full.txtGlobal dump (all PayZu products together).
/openapi/payzu-conta-digital-api.jsonOpenAPI 3 specification for Conta Digital. Source-of-truth for endpoints and schemas.
/api-scalar-hubInteractive Scalar rendering of the Conta Digital OpenAPI.
/api-swagger-hubSwagger 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 pageRaw 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.json

RAG / 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.txt and /llms-full.txt on the next deploy
  • /openapi/payzu-conta-digital-api.json whenever 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.

On this page