面向 AI（LLMs）
银行卡文档以 ChatGPT、Claude、Cursor 等能理解的格式提供：让 AI 指向一个固定 URL 或加载整个文件，就能问关于收款、3DS、反欺诈、循环扣款或 webhooks 的问题。
银行卡文档也以纯文本形式提供给 AI 助手。你可以把固定 URL 粘贴到聊天里，或者把整个文件加载到上下文中。
本文档针对 Cartão（银行卡）API（https://api.payzu.io/v1，mTLS + 通过 POST /token 获取的 Bearer token，金额以分为单位）。Pix API 是另一套系统（https://api.payzu.processamento.com/v1，Bearer，金额以巴西雷亚尔为单位），有独立文档。切勿在同一集成中混用这两者。
面向 AI 的端点
| URL | 内容 |
|---|---|
/cartao/llms.txt | markdown 格式的索引，包含仅银行卡所有页面的链接和描述。 |
/cartao/llms-full.txt | 完整银行卡文档拼接为单一文件。 |
/llms.txt | 全局索引（所有 PayZu 产品合并）。 |
/llms-full.txt | 全局转储（所有 PayZu 产品合并）。 |
/cartao-openapi.json | 银行卡 API 的 OpenAPI 3 规范：端点、schemas 和错误。 |
/api-scalar-cartao | OpenAPI 的 Scalar 交互式渲染。 |
/api-swagger-cartao | OpenAPI 的 Swagger UI 渲染。 |
专用转储 /cartao/llms-full.txt 只包含银行卡。全局转储 /llms-full.txt 把银行卡和 Pix 放在同一文件里，二者的 base URL、认证方式（mTLS × Bearer）和金额单位（分 × 雷亚尔）都不同。
按页面
文档的每个页面都有对应的纯 markdown 内容。将 /zh/docs/... 替换为 /llms.mdx/docs/zh/.../content.md：
| HTML 页面 | 原始 markdown |
|---|---|
/zh/docs/cartao | /llms.mdx/docs/zh/cartao/content.md |
/zh/docs/cartao/webhooks | /llms.mdx/docs/zh/cartao/webhooks/content.md |
/zh/docs/cartao/three-d-secure | /llms.mdx/docs/zh/cartao/three-d-secure/content.md |
每个页面顶部都有 问 AI、复制给 LLM（复制页面的 markdown）和 查看 Markdown（打开页面的 markdown）按钮。
使用场景
在 ChatGPT/Claude 里快速提问
把 URL https://docs.payzu.com.br/cartao/llms-full.txt 贴入对话，然后提出具体问题：
PayZu 银行卡 API 文档：https://docs.payzu.com.br/cartao/llms-full.txt
Base URL：https://api.payzu.io/v1（sandbox：https://api.sandbox.payzu.io/v1）。
认证：每次调用都使用客户端证书（mTLS）+ Bearer token，token 通过 POST /token 获取，
使用 Basic Auth（client_id:client_secret）和 grant_type client_credentials。
金额以分为单位。
给我一个 Node.js 示例：
1. 使用 mTLS 证书通过 POST /token 获取 token。
2. 在 POST /charges 创建一笔 R$ 100,00 的收款（"amount": 10000），并带上 postbackUrl。
3. 接收 webhook，并在处理前校验签名：用 webhook secret 对
"<X-Webhook-Timestamp>.<X-Webhook-Nonce>.<原始请求体>" 计算 HMAC-SHA256，
与 X-Webhook-Signature 比对；时间戳（毫秒）超过 5 分钟则拒绝。
4. 按收款 id + 状态变化去重。编辑器中的 Cursor / Copilot
在你的仓库中创建 .cursorrules 或 .github/copilot-instructions.md 文件：
你正在对接 PayZu 银行卡 API。它是独立于 Pix API 的系统。
不可违反的规则：
- Base URL：https://api.payzu.io/v1（sandbox：https://api.sandbox.payzu.io/v1）
- 每次调用都使用 PayZu 提供的客户端证书（mTLS）
- Token：POST /token，使用 Basic Auth（client_id:client_secret）和 {"grant_type": "client_credentials"}；
其他路由携带 Authorization: Bearer <access_token>
- 金额（amount、unitPrice）以分为单位（R$ 10,90 = 1090）；汇率（rate.bid、rate.ask）为小数
- Webhook：POST 到收款的 postbackUrl。校验 X-Webhook-Signature（用 webhook secret 对
"timestamp.nonce.payload" 计算的十六进制 HMAC-SHA256），并拒绝超过 5 分钟的
X-Webhook-Timestamp（毫秒）
- 在 5 秒内以 2xx 响应 webhook；投递失败后最多重试 5 次
- 按收款 id + 状态变化对 webhook 去重，切勿使用 X-Webhook-Nonce
- POST /charges 不是幂等的：遇到超时时，先在 GET /charges（startDate 和 endDate）中查找您的 externalId
再决定是否重试，否则会重复扣款
- 退款（PUT /charges/{chargeId}/reverse）始终全额，每笔收款只能退一次；不要传 amount
- 切勿使用 api.payzu.processamento.com（那是 Pix API：Bearer，金额以雷亚尔为单位）
完整参考：https://docs.payzu.com.br/cartao/llms-full.txt
OpenAPI：https://docs.payzu.com.br/cartao-openapi.jsonRAG / 向量库
/cartao/llms-full.txt 是将银行卡文档索引到向量库（Pinecone、Qdrant、Supabase pgvector）的文件。每个 ## 章节 可作为一个 chunk。
代码生成
要生成 HTTP 客户端，让 AI 指向 /cartao-openapi.json：
为这个银行卡 API 生成一个带类型的 TypeScript 客户端：
https://docs.payzu.com.br/cartao-openapi.json
Base URL https://api.payzu.io/v1，mTLS + 通过 POST /token 获取的 Bearer token，金额以分为单位。
使用 Zod 做运行时校验，并用 undici 携带客户端证书。更新
文档中发布的每一次变更，都会在下一次部署时更新 /cartao/llms.txt、/cartao/llms-full.txt 以及每个页面的 markdown。API 新增端点或 schema 变更时，/cartao-openapi.json 也会随之更新。