术语表
交易状态 (status)
| Status | 说明 |
|---|---|
PENDING | 交易已创建，等待支付或处理 |
COMPLETED | 交易成功完成 |
CANCELED | 交易已取消（出错或手动请求） |
REFUNDED | 金额已退还给付款方 |
EXPIRED | 支付期限已过，交易未完成 |
交易类型 (type)
| 值 | 含义 |
|---|---|
DEPOSIT | 资金流入（Pix in、收到的退款） |
WITHDRAW | 资金流出（Pix、TED、QR、银行数据、内部转账） |
Pix 密钥类型 (pixType)
| 类型 | 说明 | 格式 |
|---|---|---|
cpf | 11 位纯数字，无格式化 | 12345678901 |
cnpj | 14 位纯数字，无格式化 | 12345678901234 |
phone | 含国际区号 (55) 的国际格式 | 5511987654321 |
email | 有效的电子邮箱地址 | usuario@dominio.com.br |
evp | 由 Bacen 生成的 UUID | 123e4567-e89b-12d3-a456-426655440000 |
违规处理 (MED)
infraction 对象字段
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 违规记录的唯一标识符 |
protocol | string | 违规登记协议号 |
type | InfractionType | 违规类型 |
status | InfractionStatus | 当前状态 |
reportedBy | ReportedType | 举报来源 |
reportDetails | string | 举报详情 |
analysisResult | AnalysisResult | 分析结果（待处理时为 null） |
analysisDetails | string | null | 分析详情 |
transactionEndToEndId | string | 相关 Pix 交易的 EndToEnd ID |
transactionId | string | 该交易在 PayZu 系统中的 ID |
creationDate | string | 记录创建时间 |
lastModificationDate | string | 最近更新时间 |
dueDate | string | null | 分析截止期限 |
InfractionType
| 值 | 说明 |
|---|---|
REFUND_REQUEST | 请求退还某笔 Pix 交易的金额 |
FRAUD | 与欺诈活动相关的交易 |
REFUND_CANCELLED | 取消已登记的退款请求 |
ReportedType
| 值 | 说明 |
|---|---|
DEBITED_PARTICIPANT | 发送资金的一方（付款方）登记了违规 |
CREDITED_PARTICIPANT | 接收资金的一方（收款方）登记了违规 |
AnalysisResult
| 值 | 说明 |
|---|---|
AGREED | 违规成立，将处理退款 |
DISAGREED | 违规不成立，不予退款 |
HTTP 状态码
| 代码 | 含义 |
|---|---|
200 | 成功 |
201 | 资源已创建 |
400 | payload 无效 |
401 | Bearer token 缺失、无效或已吊销 |
403 | Bearer token 有效但无权限 |
404 | 资源未找到 |
409 | 冲突（idempotência、资源处于无效状态） |
422 | 语义校验失败 |
429 | 达到速率限制 |
5xx | PayZu 服务器错误（请使用退避策略重试） |
通用字段
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 该交易在 PayZu 中的唯一标识符 |
clientReference | string | 你传入的外部标识符，将在每次 callback 中返回 |
amount | number | 金额单位为 雷亚尔 (BRL)，绝非分 |
callbackUrl | string | 用于接收状态变更 webhook 的 URL |
endToEndId | string | Pix 的 EndToEnd ID (Bacen)。格式为 E + 32 个字符 |
requestId | string | PayZu 调用的唯一 ID。出现在所有错误中，请提交给技术支持 |
Webhooks
A API Conta Digital envia notificações via POST para o callbackUrl informado na criação de cobrança ou saque, sempre que o status da transação muda. Inclui retry com backoff de até 72 tentativas.
Para IAs (LLMs)
Toda a documentação da Conta Digital PayZu disponível em formato consumível por modelos de linguagem. Copie o conteúdo direto, baixe o dump completo, ou use as URLs específicas por página. Funciona com ChatGPT, Claude, Gemini, Cursor, Copilot, etc.