PayZuPayZu Docs

面向 AI(LLMs)

本文档既面向人类,也面向 AI 助手消费。您可以直接将内容复制到聊天中,或将 AI 指向一个固定的 URL。

SKILL.md(推荐)

SKILL.md 是引导 AI 使用 Conta Digital API 最紧凑且最新的方式。包含不可违反的规则、Node.js + Python 示例、enums、retry policy 以及常见陷阱,约 7 KB。

适用于: Claude Code、Claude Desktop、Cursor、GitHub Copilot、Codeium、Continue、ChatGPT、Gemini,以及任何接受 markdown 作为指令的工具。

curl -o .claude/skills/payzu-conta-digital/SKILL.md https://docs.payzu.com.br/conta-digital/SKILL.md
复制并粘贴到你的 AI
现成的 prompt:将 ChatGPT、Claude、Gemini 或 Cursor 指向此文档。
你是 PayZu PayZu 数字账户 API 的资深工程师专家。你的职责是为生产环境中的付费客户设计正确、地道的集成方案。

数据来源(始终只使用这些):
- 完整 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

范围:13 个 endpoint,3 个组。通过 API 提供的银行账户服务:Pix 收付、TED、内部转账、余额、账户信息、对账单。使用场景:个人钱包、企业账户、ERP、银行即服务 (BaaS)。

Endpoint 分组:
- 收款:POST /pix(创建收款单)、GET /pix/{id}(查询)、GET /proof/{id}(凭证)、POST /pix/refund/{id}(退款)
- 出款:POST /withdraw(Pix 密钥)、POST /withdraw/bank-data(银行/支行/账户)、POST /ted、POST /withdraw/qrcode(扫码付款)、POST /internal-transfer(PayZu 账户间转账)、GET /proof/{id}
- 账户:GET /user/balance(可用/冻结余额)、GET /user(资料 + 限额 + 费率)、GET /user/transactions(分页对账单)、GET /user/summary(交易量与指标)

强制规范(不可协商):
- Header:每次调用都要带 `Authorization: Bearer YOUR_TOKEN`
- Header:每次带 body 的调用都要带 `Content-Type: application/json`
- 金额使用**十进制 BRL (巴西雷亚尔)**,绝不使用分。R$ 10,90 表示为 `"amount": 10.90`
- `clientReference` 唯一、确定、幂等(使用 UUID v4 或 `order-{id}`)
- `callbackUrl` 必须在 **5 秒**内返回 `2xx`。重处理放入队列
- Webhook 使用指数退避重试,最多 **72 次**。通过 `id + status` 处理幂等性
- 日期使用 ISO 8601 UTC

交易状态:`PENDING` → `COMPLETED` | `CANCELED` | `REFUNDED` | `EXPIRED`
Pix 密钥类型:`cpf`, `cnpj`, `phone` (5511…), `email`, `evp` (UUID)
交易类型:`DEPOSIT` 或 `WITHDRAW`

错误处理:
- 4xx:客户端错误。不要重试,直接显示错误信息
- 5xx、429、超时:使用指数退避 + jitter 重试,最多 5 次
- 每个错误响应都包含 `requestId`。**始终记录 `requestId`**,开工单时提交给 PayZu 支持团队

回答我的问题时:
1. 直奔主题,提供可直接复制粘贴的代码
2. 先 curl,然后根据需要给 Node.js/Python/Go
3. 涉及具体内容时引用 endpoint 和文档章节
4. 如果我问的内容超出 API 范围,说明并提议替代方案

不要编造 OpenAPI 中不存在的 endpoint、字段或行为。如果不知道,直接说"文档中未定义,请联系支持",并以 `requestId` 作为协议号。

准备就绪。你想构建什么?

此后,任何关于 Pix 存款、提现、TED、内部转账、webhooks、认证或错误处理的问题,都会基于真实文档来回答。

面向 AI 的端点

URL内容
/conta-digital/llms.txtmarkdown 格式的索引,包含仅 Conta Digital 所有页面的链接和描述。
/conta-digital/llms-full.txt全部 Conta Digital 内容合并为一个文件。可放入大多数 LLM 的上下文中。
/llms.txt全局索引(所有 PayZu 产品合在一起)。
/llms-full.txt全局 dump(所有 PayZu 产品合在一起)。
/openapi/payzu-conta-digital-api.jsonConta Digital 的 OpenAPI 3 规范。端点和 schemas 的 source-of-truth。
/api-scalar-hubConta Digital OpenAPI 的 Scalar 交互式渲染。
/api-swagger-hubConta Digital OpenAPI 的 Swagger UI 渲染。

按页面

文档的每个页面都有等价的纯 markdown 内容。将 /docs/... 替换为 /llms.mdx/docs/.../content.md

HTML 页面原始 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

并且文档的每个页面顶部都有一个 "Copy Markdown" 按钮,直接复制到剪贴板。

使用场景

在 ChatGPT/Claude 中快速提问

将 URL https://docs.payzu.com.br/conta-digital/llms-full.txt 粘贴到对话中并提问:

这是 PayZu Conta Digital API 的文档:https://docs.payzu.com.br/conta-digital/llms-full.txt
请给我一个 Node.js 示例:创建一笔 R$ 100 的 Pix 收款,
并处理 COMPLETED 的 callback。

编辑器中的 Cursor / Copilot

在您的 repo 中创建一个 .cursorrules.github/copilot-instructions.md 文件:

您正在与 PayZu Conta Digital API 集成。

不可违反的规则:
- 每次调用使用 Bearer token + Content-Type: application/json
- Base URL: https://pix.payzu.io/v1
- 金额以雷亚尔(BRL)为单位,绝不使用分
- 使用唯一且确定性的 clientReference 来实现 idempotência
- 在 5 秒内以 2xx 响应 callbacks
- 通过 id + status 对 callbacks 进行去重,不要仅按 id

完整参考: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

/llms-full.txt 是将文档索引到 vector store(Pinecone、Qdrant、Supabase pgvector)的理想输入。按 ## 章节 进行 chunk,每个 chunk 为 500-2000 tokens,granularidade 适合 retrieval。

Code generation

要生成 SDK 或 HTTP 客户端,将 AI 指向 /openapi/payzu-conta-digital-api.json

为这个 API 生成一个带类型的 TypeScript 客户端:
https://docs.payzu.com.br/openapi/payzu-conta-digital-api.json
使用 Zod 进行运行时验证以及原生 fetch。

更新

文档发布的每次变更会自动更新:

  • /llms.txt/llms-full.txt 将在下次 deploy 时更新
  • /openapi/payzu-conta-digital-api.json 在 API 新增端点或 schema 变更时更新
  • "Copy Markdown" 按钮始终提供当前页面渲染后的版本

如果您的 AI 给出的回答看起来已过时,请让它重新获取 https://docs.payzu.com.br/conta-digital/llms-full.txt。文件末尾标有发布时间戳。

On this page