跳到主要内容

更新日志

本文档记录 CorpX API 的所有重要变更。

v1.30.3 (2026-04-30) - 移除重复 webhook（pix.refund.completed、pix.out.failed、qrcode.paid）​

修复​

  • 重复 webhook 已消除：在某些场景下，平台会为同一事件发送 两个 webhook——一个遵循文档定义的格式，另一个使用从未在文档中描述过的旧格式。该行为现已修复：每个事件 只生成一次 通知，始终采用文档化的格式。

    受影响的事件：

    • pix.refund.completed（PIX 退款完成时触发）
    • pix.out.failed（PIX 出款失败时触发）
    • qrcode.paid（二维码被支付时触发）

    旧格式 从未出现在 docs/webhooks 中——它是一个内部例程并行发送的、未列入文档的副本。仅依赖文档化字段的集成不会察觉到任何差异，除了不再收到重复通知。

  • pix.refund.completed 中的 data.status 现在总是返回 SUCCESS，与 官方状态枚举 一致。此前在某些情况下会错误地返回 REFUNDED（即原始 PIX 交易的状态）。

已下线的字段/格式（仅影响依赖未文档化旧格式的集成）​

旧字段 / 格式替换为（文档化格式）
id: refund_completed_{paymentId}_{ts}id 为 sha256 哈希字符串
id: pix_out_failed_{paymentId}_{ts}id 为 sha256 哈希字符串
id: qr_paid_{txid}_{ts}id 为 sha256 哈希字符串
data.status: COMPLETED（pix.refund.completed）data.status: SUCCESS
data.status: REFUNDED（pix.refund.completed）data.status: SUCCESS
data.refundId（pix.refund.completed）使用 data.transactionId（已在文档中）
data.failedAt（pix.out.failed）使用信封 occurredAt
data.paymentId（pix.out.failed）使用 data.transactionId（已在文档中）
payer.account / payee.accountpayer.accountNumber / payee.accountNumber

如果您的集成消费了上述任何旧格式专属字段，请在升级到本版本前切换到文档化字段。

推荐的去重键​

请始终使用 payload 中的强键在客户端进行 webhook 去重：

  • 对于 pix.refund.completed：data.refundEndToEnd（BACEN D-code，全局唯一）。
  • 对于 pix.out.failed：data.endToEnd（BACEN E-code）或 data.identifier。
  • 对于 qrcode.paid：data.endToEnd 或 data.qrcodeId。

这些字段每笔交易唯一，并在所有事件中均存在。

v1.30.2 (2026-04-30) - Webhook 时间戳统一为 UTC​

修复​

  • data 内部所有日期字段现已统一为 UTC 时区并带 Z 后缀，覆盖所有 webhook 事件。此前部分字段（receivedAt、completedAt、initiatedAt、chargedAt、openedAt）会以无时区标识的形式直接转发，导致严格遵循 ISO 8601 的解析器将其解释为本地时间 —— 在 BRT 环境下可能产生最长 3 小时的偏差。
  • 标准已统一并记录于 Webhooks → 日期与时间格式。
  • 文档示例此前已使用 Z（UTC）；现已确保所有实际发送的 payload 均符合该标准。

v1.30.1 (2026-04-29) - 保留 qrcode.paid webhook（不再标记为弃用）​

撤销弃用​

  • qrcode.paid 继续作为官方支持的事件。 Webhook 指南中（PT、EN 和 ZH 三个语言版本）出现的弃用提示已移除。该事件仍然有效且稳定；无需迁移。
  • 等效事件 pix.in.completed（带 method: QR_CODE_DYNAMIC 或 QR_CODE_STATIC）仍作为替代方案可用，并继续并行分发——可根据集成需要选择最合适的事件。

v1.30.0 (2026-04-23) - 内部转账：错误映射修复 + webhook 中的 identifier​

修复​

  • 银行合作方 account_disabled（TX00012）错误映射：当源账户在银行合作方被禁用时，API 现在返回 HTTP 422 及 errorCode: partner_account_disabled。此前该情况被映射为 HTTP 502（Bad Gateway），误导集成方将其视为基础设施故障而非业务规则。此变更适用于全部三个内部转账端点（/transfers/internal、/transfers/internal/by-document、/transfers/internal/by-bank-account）。
  • 统一银行合作方错误分类：核心银行服务（用于内部转账和账户查询）的 HTTP 错误现在经过与其他端点相同的分类器。insufficient_balance、daily_limit_exceeded、account_disabled 等特定代码现返回 422 而非 502。

改进​

  • identifier 和 description 现在返回在 transfer.internal.out webhook 中：原始 POST /transfers/internal* 请求中由集成方提供的 identifier 和 description 现在会传播到发送给付款方账户的 webhook，允许无需查询账单即可完成对账。
  • 自定义付款方描述 在请求中提供时，现会替换账单（GET /statement）中默认的 Transferência Interna 文本。
  • coreId 现在包含在每个账本流水 webhook 中：银行合作方核心账本行的 UUID（与账单 coreId 字段返回的值相同）现已在 pix.in.completed、pix.out.completed、pix.out.failed、pix.refund.*、qrcode.paid、transfer.internal.*、fee.charged 和 fee.refunded 中传播。允许通过单一稳定键在 webhook ↔ 账单 ↔ 合作方导出之间对账。
  • 每个账本流水 webhook 中标准化的 status：data.status 现在在所有 PIX、QR、内部转账、退款和手续费事件中保证存在。标准化词汇表：SUCCESS（操作完成）、FAILED（操作失败，附带 data.error）、REVERSED（之前已完成的流水被撤销）。MED 事件（pix.med.*）保持自己的词汇表（OPEN、PENDING_DECISION、ACCEPTED、REJECTED、CANCELED）。完整表格见 docs/webhooks。

新的 errorCode 值​

代码HTTP含义
partner_account_disabled422源账户在银行合作方被禁用（需要重新激活）

v1.29.0 (2026-04-18) - 通过证件查询内部转账收款人​

新功能​

  • 内部转账收款人预览：新端点 GET /v1/accounts/{accountId}/transfers/internal/lookup/{document} 允许在通过 CPF/CNPJ 执行内部转账之前预览持有人姓名。用于向最终用户显示确认步骤。
  • 返回的姓名带有隐私掩码：名字保留完整，姓氏仅显示首字母，后跟 ***。连接词（如 "de"、"da"、"dos"）保留原样。
    • 示例："JOAO DA SILVA PEREIRA" → "JOAO da S*** P***"
  • 端点还返回银行合作方的 accountStatus。

推荐流程​

  1. 用户输入收款人的 CPF/CNPJ
  2. 集成方调用 GET /transfers/internal/lookup/{document} 并显示 maskedName 供确认
  3. 用户确认
  4. 集成方调用 POST /transfers/internal/by-document 执行转账

v1.28.0 (2026-04-17) - 移除已弃用的 Webhook​

重大变更​

  • payment.sent 和 payment.refunded Webhook 已停用：这些事件在 v1.15.0 (2026-02-20) 中标记为弃用，现已永久停用。
    • payment.sent → 使用 pix.out.completed（包含 method 字段和 payment 对象）
    • payment.refunded → 使用 pix.refund.completed（包含 originalEndToEnd、refundEndToEnd 和参与方详情）
  • 如果您的集成仍订阅这些事件，请立即迁移到上述替代事件。

v1.27.0 (2026-04-14) - 银行账户 PIX 转账​

新功能​

  • 银行账户 PIX 转账：新增使用收款方银行信息（ISPB、支行、账号）发起 PIX 转账的端点（无需 PIX 密钥）：
    • POST /v1/accounts/{accountId}/pix/out/bank-account — 同步银行账户转账。
    • POST /v1/accounts/{accountId}/pix/out/bank-account/async — 异步（排队）转账。
    • POST /v1/accounts/{accountId}/pix/out/bank-account/bigpix — 大额转账，自动分块处理。
  • 必填字段：bankIspb（银行 ISPB 代码）、accountNumber、accountBranch、documentNumber（收款方 CPF/CNPJ）和 name。
  • accountType 字段接受 CHECKING_ACCOUNT、SAVINGS_ACCOUNT 或 PAYMENT（默认：CHECKING_ACCOUNT）。

备注​

  • Webhook、手续费和对账与 PIX 密钥转账相同 — 交易在对账单中显示为 PIX_OUT。
  • 异步端点使用与 PIX 密钥转账相同的 FIFO 队列 — 相同的排序和幂等性保证。
  • BigPix 功能相同：分为 R$ 15,000 的分块（可通过策略配置），每次操作收取一次手续费。

v1.26.1 (2026-04-13) - 稳定性修复​

错误修复​

  • 静态二维码：修复了某些场景下静态二维码中编码的金额与请求金额不同的问题。
  • Webhook pix.in.completed：修复了二维码支付的 webhook 负载中缺少 identifier 字段的场景，即使标识符已可用。

v1.26.0 (2026-04-09) - Boleto 付款​

新功能​

  • Boleto 付款：新增查询和支付银行票据、公共事业账单和税费的端点：
    • POST /v1/accounts/{accountId}/boleto/preview — 通过条码或"linha digitável"查询 boleto 数据。返回收款人、银行、原始金额、利息、罚款、折扣和更新后总金额。
    • POST /v1/accounts/{accountId}/boleto/pay — 提交 boleto 付款。返回 paymentId，状态为 PROCESSING。
    • GET /v1/accounts/{accountId}/boleto/payments/{paymentId} — 查询 boleto 付款状态。状态从 PROCESSING 进展到 COMPLETED 或 FAILED。
  • 新交易类型 BOLETO_PAYMENT：Boleto 付款在对账单中显示为支出交易（direction: OUT，transactionType: BOLETO_PAYMENT）。
  • 功能标志 boleto_payment：该功能由 tenant_configs 中的功能标志控制。需由管理员为每个需要使用的租户启用。

备注​

  • 银行票据（47位）、公共事业账单（48位）和税费按类型自动分类（boleto、utility、tax）。
  • 付款是异步的 — 在 POST /boleto/pay 后，集成方应轮询 GET /boleto/payments/{paymentId} 以跟踪状态。
  • Boleto 取消和预约付款将在未来版本中实现。

v1.25.1 (2026-04-02) - fee.charged 中的原始交易引用及退款改进​

改进​

  • fee.charged Webhook 丰富化：Payload 现在包含 originTransactionType（触发手续费的交易类型，例如 PIX_IN、PIX_OUT）和 originTransactionRef（原始交易的 E2E ID）。同时包含完整的 description 及计算详情。
  • 动态 QR 码的 pix.in.completed Webhook 含 identifier：修复了在支付确认先于收费通知到达时，QR 码 identifier 未包含在 Webhook 中的问题。
  • 更稳健的退款：修复了银行合作方成功处理退款但 API 返回临时错误的场景。API 现在通过 Webhook 检测确认并正确返回 D-code。

v1.25.0 (2026-03-26) - payerDescription 字段、手续费 Webhook 及退款修复​

新功能​

  • 账单和 Webhook 中的 payerDescription 字段：GET /v1/accounts/{accountId}/statement 端点及 pix.in.completed、pix.out.completed、qrcode.paid、transfer.internal.* Webhook 现在返回可选字段 payerDescription。该字段包含付款人发起 PIX 时输入的消息（如有）。description 字段继续保持标准化描述格式（"PIX 已收 - 付款人姓名"）。
  • fee.charged 和 fee.refunded Webhook：银行手续费现在会生成 fee.charged（收取时）和 fee.refunded（退回时）Webhook。如需接收，请将这些事件类型添加到您的 Webhook 订阅中。

改进​

  • 更丰富的 PIX IN Webhook：pix.in.completed Webhook 现在始终包含完整数据：reconciliationId、payerDescription、付款人详情和 PIX 密钥信息。此前在某些场景下 Webhook 可能仅包含部分数据。

缺陷修复​

  • 退款 Webhook（PIX 退款）：修复了在退款确认紧随创建到达时，pix.refund.completed Webhook 未发送给集成商的问题。
  • 内部转账的 PIX Webhook（CORPX-CORPX）：修复了 CORPX 账户间转账中事件类型错误的问题。此前，收款方可能收到 pix.out.completed 而非 pix.in.completed。
  • 静态 QR 码中的 reconciliationId：修复了静态 QR 码支付中 pix.in.completed Webhook 未包含 reconciliationId 的问题。
  • 账单状态筛选：修复了账单端点中 status 筛选器在某些场景下未正确返回结果的问题。

v1.24.1 (2026-03-18) - 错误语义改进（减少通用 502）​

改进​

  • 在以下端点中，将合作方来源错误统一为语义化 HTTP 状态码：pix/keys、pix/key/{pixKey}（DICT）、pix/limits、pix/out/qr-code、pix/out/qr-code/decode、pix/med、transfers/internal、accreditations、accounts/{accountId}/balance。
  • 错误响应格式保持不变：{ "errorCode": "...", "message": "..." }。
  • OpenAPI 与 Postman 已同步更新为新的错误格式与状态码。

错误映射变更（从 -> 到）​

错误 / 场景之前现在
同步 Pix Out 超时（POST /pix/out）504 Gateway Timeout207 Multi-Status（partner_timeout）
同步 Pix Out 中的 pix_key_not_found（POST /pix/out）502 Bad Gateway422 Unprocessable Entity
业务/校验类通用 partner_error（PIX/Transfers/MED/Accreditations）502 Bad Gateway422 Unprocessable Entity
pix_key_lookup_failed（已分类的 DICT/合作方失败）502 Bad Gateway422 Unprocessable Entity
partner_auth_failed / partner_signature_rejected502 Bad Gateway503 Service Unavailable
partner_internal_error / partner_recipient_unavailable502 Bad Gateway503 Service Unavailable
partner_timeout（上游超时场景）502 Bad Gateway504 Gateway Timeout
合作方集成流程中的 account_not_found502 Bad Gateway404 Not Found
DICT 查询中的 pix_key_not_found（GET /pix/key/{pixKey}）502 Bad Gateway404 Not Found
未分类兜底502 Bad Gateway502 Bad Gateway（保留为兜底）

v1.24.0 (2026-03-18) - 同步 Pix Out：按账户限流与超时 207​

破坏性变更​

  • 同步 Pix Out 超时状态码变更： POST /v1/accounts/{accountId}/pix/out 在合作方超时时现在返回 HTTP 207（partner_timeout），不再返回 HTTP 504。
  • 处理原则不变：该笔转账可能已成功，请在重试前先查询对账单/支付状态。

改进​

  • 同步 Pix Out 按账户限流： 新增按账户限流（当前默认 100 req/min，可通过策略自定义）。
  • 未来几天： 同步请求的默认限流将调整为 10 req/min。
  • 超限时 API 返回 429 rate_limit_exceeded，并包含上下文字段（currentRateLimit、scope）及异步流程建议。
  • 新增异步 cashout 端点： POST /v1/accounts/{accountId}/pix/out/async 用于调度付款处理，立即返回 202，并带 paymentId 供追踪。
  • BigPix 现为仅异步： POST /v1/accounts/{accountId}/pix/out/bigpix 现在通过异步流程调度处理（与 /async 一致），不再执行同步处理。

v1.23.0 (2026-03-17) - PIX 二维码解码​

新功能​

  • PIX 二维码解码/查询： 新端点 POST /v1/accounts/{accountId}/pix/out/qr-code/decode 可解码 PIX 二维码 EMV 字符串并返回收款方详细信息，无需执行付款。返回：姓名、证件号、金额、PIX 密钥、银行和收款方账户类型。适用于在付款前向用户显示确认界面。

v1.22.0 (2026-03-07) - 按证件号和按银行账户进行内部转账​

新功能​

  • 按证件号（CPF/CNPJ）进行内部转账： 新端点 POST /v1/accounts/{accountId}/transfers/internal/by-document 允许通过目标持有人的 CPF 或 CNPJ 创建内部转账。适用于银行生态系统中的任何账户，不仅限于在 API 中注册的账户。必填字段：document、value、description。

  • 按银行账户进行内部转账： 新端点 POST /v1/accounts/{accountId}/transfers/internal/by-bank-account 允许通过目标账户的支行号（branch）和账号（accountNumber）创建内部转账。仅适用于在 API 中注册的账户（同一租户）。如需向外部账户转账，请使用 /by-document 端点。

v1.20.0 (2026-03-01) - 账户所有权验证​

改进​

  • 加强账户所有权验证： API 现在会验证请求中的 accountId 是否属于已认证的租户。仅访问自己账户的集成商不受影响。此改进增强了防止跨账户未授权访问的安全性。

v1.19.1 (2026-02-26) - BigPix 改进​

改进​

  • BigPix（POST /v1/accounts/{accountId}/pix/out/bigpix）： 优化了分片处理的稳健性，在高并发/高量场景下的一致性更好。

v1.19.0 (2026-02-26) - 交易时间线​

新功能​

  • 交易时间线： 新端点 GET /v1/accounts/{accountId}/transactions/timeline 按 endToEndId 或 identifier 返回单笔交易的事件时间线。包含：BACEN 确认（简短摘要）、发送给客户的 webhook（含完整 payload 供“查看完整 payload”）、费用、退款及 QR Code 生命周期（如适用）。查询参数二选一必填：endToEndId 或 identifier。现有端点与响应格式无变更。

v1.18.0 (2026-02-24) - 性能优化与独立费用交易​

改进​

  • 费用作为独立交易： API收取的费用现在在账单中显示为独立行，并链接到原始交易。QR Code和支付查询现在包含费用详情（fees、totalFees）。
  • 性能优化： 对账处理采用并行批量查询，支持更高的交易量。
  • 自动费用重试： 自修复流程现在包括对初次收费失败的费用进行重试。

修复​

  • 修复了MED争议率计算重复计数交易和争议的问题。
  • 修复了高并发场景下费用收取可能静默失败的问题。

v1.18.0 (2026-02-24) - 性能优化与独立费用交易​

改进​

  • 费用作为独立交易： API收取的费用现在在账单中显示为独立行，并链接到原始交易。QR Code和支付查询现在包含费用详情（fees、totalFees）。
  • 性能优化： 对账处理采用并行批量查询，支持更高的交易量。
  • 自动费用重试： 自修复流程现在包括对初次收费失败的费用进行重试。

修复​

  • 修复了MED争议率计算重复计数交易和争议的问题。
  • 修复了高并发场景下费用收取可能静默失败的问题。

v1.17.0 (2026-02-22) - 自动对账与交易状态修复​

改进​

  • 自动对账：过期 QR Code 自动标记，待处理支付定期对账。
  • 交易状态保护：终态（SUCCESS、FAILED、REVERSED）不再被延迟 webhook 覆盖。

v1.16.2 (2026-02-21) - 增强版 QR Code 与 Payment 查询​

改进​

  • QR Code 与 Payment 查询现在返回增强版 transaction 对象，包含完整细节（状态、付款方/收款方、费用、争议、退款、错误）。

v1.16.1 (2026-02-21) - 合作方响应修复​

缺陷修复​

  • 修复删除 PIX key 或发起退款时返回 HTTP 502 的问题。操作虽成功但 API 误返回错误。
  • 改进合作方响应处理逻辑。

v1.16.0 (2026-02-20) - Lookup 端点与 Payment 分页​

新功能​

  • Lookup 端点：/pix/qr-code/lookup 与 /pix/payments/lookup，用于单条数据查询
  • Payment 列表分页：?page=0&size=50，返回 totalElements、totalPages、hasNext、hasPrevious
  • QR Code 列表分页：?page=0&size=50，返回 totalElements、totalPages、hasNext、hasPrevious
  • 路由标准化：推荐使用带连字符的 qr-code
  • 已弃用：/payments → /pix/payments，/pix/out/qrcode → /pix/out/qr-code

v1.15.0 (2026-02-20) - Webhook method 字段与退款对账​

新功能​

  • PIX webhook 新增 method 字段（PIX_KEY、QR_CODE_STATIC、QR_CODE_DYNAMIC、PAYMENT、REFUND_*）
  • 上下文对象：PIX IN 中包含 qrCode，PIX OUT 中包含 payment
  • QR Code 退款对账（在 QR code 查询中返回 refunds[]）

已弃用​

  • qrcode.paid、payment.sent、payment.refunded —— 请改用带 method 的 pix.in.completed / pix.out.completed。

v1.14.0 (2026-01-16) - BigPix：大额转账​

新功能​

BigPix 端点（POST /v1/accounts/{accountId}/pix/out/bigpix）​

  • 新增用于超过单笔上限的 PIX 转账端点（默认 R$15,000）。
  • 自动拆分为多笔小额转账并并行执行。
  • 返回聚合结果，状态为 FULL、PARTIAL 或 FAILED。
  • 可通过 pixOut.chunkSize 策略按租户配置分片大小。

v1.13.2 (2026-01-16) - Webhook 投递改进​

改进​

  • 新建 webhook 订阅在投递前会移除冗余请求头后再发送给接收方。

v1.13.1 (2026-02-19) - 移除 qrCodeFormat，新增 Payment 审批流程​

破坏性变更​

  • QR Code 端点移除 qrCodeFormat。API 现始终返回 EMV 格式。

新功能​

  • Payment 审批流程：超过阈值的 PIX Out 会创建 PENDING_APPROVAL 意图，管理员可批准/拒绝。

v1.13.0 (2026-02-18) - Disputes（MED）、策略执行与申诉​

新功能​

争议管理（MED）​

  • 新增 MED 争议管理系统，可通过 E2E ID 自动对账。
  • MED 数据已与对账单中的交易关联。
  • 支持按租户进行每日 MED 比率监控。
  • 新增端点：MED 统计、带证据上传的申诉流程。

PIX In 策略执行​

  • PIX In 规则现支持实时执行，并支持 AUTO_REFUND。
  • 策略违规可在对账单中查看。

新策略规则​

  • PIX In：银行代码黑名单、同主体限制。
  • PIX Out：白名单优先（可覆盖其他规则）。
  • MED：自动阻断、限速与可配置动作。

改进​

  • 新增文档指南：Policies and Rules、Disputes（MED）。

v1.12.1 (2026-02-18) - Refund Reason 必填与分页修复​

新功能​

  • 新增端点 GET /v1/accounts/{accountId}/pix/key/{pixKey}，用于 DICT key 查询，带 24 小时缓存与可配置限流。

破坏性变更​

退款端点现在要求 reason 字段​

  • POST /v1/accounts/{accountId}/pix/out/refund 现在必须携带 reason 字段，且值必须为：USER_REQUESTED、FRAUD、BANK_ERROR、CASHIER_ERROR、CUSTOMER_REQUEST 之一。
  • 缺少 reason 或值不合法将返回 HTTP 400。

改进​

  • 所有 API 响应均新增 X-API-Version 请求头，便于版本排查。

修复​

  • 修复：对账单分页在第 10 页之后（超过 1000 条交易）返回空白页的问题。

v1.12.0 (2026-02-18) - 策略引擎​

新功能​

策略引擎​

  • 新增按租户与账户可配置的策略系统，具备层级（default -> tenant -> account）。
  • 可用规则：PIX Out 限额、PIX In 隔离、QR Code 权限、PIX Key 限制、退款控制、营业时间。

v1.11.1 (2026-02-15) - 对账单修复​

修复​

  • 修复：对账单分页（GET /v1/accounts/{accountId}/statement）异常。page 与 size 现在可正确返回目标页。
  • 修复：统一对账单描述（例如 “Transferência Pix”、“Devolução Pix”、“Tarifa Bancária”、“Pagamento de QR Code”）。
  • 修复：费用与交易在同一时刻发生时的对账单排序问题。

v1.11.0 (2026-02-15) - 对账单银行费用与 fee.charged Webhook​

新功能​

对账单中的费用​

  • 每笔交易产生的银行费用现在会在对账单（GET /v1/accounts/{accountId}/statement）中以 FEE 类型显示。
  • 每条费用记录均包含 feeServiceType 字段，用于标识触发收费的操作（如 PIX_OUT、PIX_IN）。

fee.charged Webhook 事件​

  • 新增可订阅事件类型：fee.charged。
  • 当账户被收取银行费用时实时发送。
  • Payload 包含：amount、currency、feeServiceType、description、chargedAt。

v1.10.0 (2026-02-13) - Reconciliation ID 与 PIX 冲正支持​

新功能​

Reconciliation ID​

  • 发送给集成方的所有 webhook（qrcode.paid、pix.in.completed、pix.out.completed、pix.out.failed、pix.refund.completed、pix.refund.failed）在可用时都会包含 reconciliationId 字段。
  • 对账单端点（GET /v1/accounts/{accountId}/statement）也会返回 reconciliationId，便于与银行流水交叉核对。

PIX 冲正支持​

  • API 现支持处理由收款方发起的 PIX 冲正。当 PIX Out 收款方退回资金时，系统会自动在对账单中记录并关联原始支付。
  • 当全额退回时，原始支付状态将更新为 REFUNDED。

修复​

  • 修复：qrcode.paid webhook 现包含完整 payer 与 payee 数据（姓名、证件、银行、支行、账户），与 pix.in.completed 一致。
  • 修复：同步到对账单的金额值错误（重复除法）问题。

v1.9.0 (2026-02-13) - Payment 生命周期、QR Code 与 Webhook 修复​

新功能​

完整 Payment 生命周期（PIX Out）​

  • Payments（PIX Out）现具备完整生命周期与对账跟踪。
  • GET /v1/accounts/{accountId}/payments 响应现包含：
    • reconciled：支付是否已被银行合作方确认。
    • reconciledAt：确认时间戳。
    • transactionId：将支付关联到对账单中已确认的交易。
  • Payment 状态流：CREATED → PENDING → COMPLETED（或 FAILED）。

Webhook 中完整付款方/收款方数据​

  • pix.in.completed 与 qrcode.paid webhook 现包含完整付款方与收款方详情（姓名、证件、银行、支行、账户、PIX key）。

事件类型校验​

  • 创建或更新 webhook 订阅时，事件类型会按官方列表校验。无效或旧版事件类型将返回 HTTP 400。

缺陷修复​

  • 修复：PIX Out 响应缺少 endToEndId 与 currency 字段。
  • 修复：因合作方 API 格式变更导致静态 QR Code 创建失败的问题。
  • 修复：静态 QR Code 请求中移除未使用的 clientId 字段。

v1.8.0 (2026-02-11) - 增强对账单与 Webhook 签名修复​

新功能​

包含完整交易明细的对账单​

  • 对账单端点（GET /v1/accounts/{accountId}/statement）现返回完整交易信息：
    • transactionType：交易类型（PIX_IN、PIX_OUT、QR_CODE_PAYMENT、PIX_REFUND）。
    • method：支付方式（KEY、STATIC_QR_CODE、DYNAMIC_QR_CODE、MANUAL）。
    • status：当前状态（SUCCESS、FAILED、PENDING、REFUNDED）。
    • direction：方向（IN 或 OUT）。
    • identifier：集成方提供的标识符。
    • payer / payee：完整的付款方与收款方详情（姓名、证件、银行、支行、账户、PIX key）。
    • originalEndToEnd / refundEndToEndIds：退款与原始交易之间的关联。
    • qrcodeId / qrcodeIdentifier：QR Code 对账数据。

缺陷修复​

  • 修复：某些订阅更新场景下 webhook HMAC 签名未正确应用的问题。

v1.7.0 (2026-02-11) - Webhook 格式、可配置认证与 HMAC 签名​

破坏性变更​

Webhook Payload 格式​

  • webhook body 现在直接遵循文档中的信封格式：{ id, type, occurredAt, schemaVersion, environment, accountId, data }。
  • 已移除冗余字段，payload 仅保留文档定义的数据。
  • 在根级新增 tenantId 与 eventType，便于路由。

Webhook 签名​

  • 签名现在通过 X-Signature 请求头发送，格式为 base64(HMAC_SHA256(secret, raw_body))。
  • 旧格式（在 X-Timestamp 头配合 hex(HMAC_SHA256(secret, timestamp + "." + body))）已弃用。
  • X-Timestamp、X-Webhook-Event、X-Webhook-ID 头不再发送。

新功能​

每个订阅可配置认证方式​

  • 集成方现在可为每个 webhook 订阅选择认证方式：
    • HMAC（推荐）：在 X-Signature 请求头中使用 HMAC-SHA256 签名。
    • API_KEY：在可配置的请求头中发送静态密钥（默认：X-API-Key）。
    • BASIC：HTTP Basic 认证（Authorization: Basic ...）。
    • BEARER：Bearer 令牌（Authorization: Bearer ...）。
    • NONE：无认证（不建议在生产环境使用）。
  • 可在 Integrator Portal 的 Webhooks > Edit Subscription 中配置。

改进​

  • Webhook 文档已重写，提供 Node.js、Python、Go 的签名校验示例。
  • 葡萄牙语文档已完成完整翻译。

缺陷修复​

  • 修复：部分场景下 webhook 认证配置未正确应用到投递的问题。

v1.6.0 (2026-02-06) - 货币标准化、对账单同步与金额校验​

新功能​

改进​

货币标准化​

  • API 中所有金额字段现明确为 BRL（REAIS），最多保留 2 位小数（centavos 精度）。
  • 示例：150.75 表示 R$150,75。
  • 超过 2 位小数的值将被拒绝并返回 HTTP 400，同时提供清晰错误信息。
  • 已按 BRL 标准更新所有 OpenAPI 字段描述。
  • 修复静态 QR Code 创建逻辑：现接受 REAIS 单位（此前要求 centavos）。

增强交易明细​

  • 交易响应新增 transactionType 字段（PIX_IN、PIX_OUT、QR_CODE_PAYMENT、PIX_REFUND）。
  • 付款方/收款方详情新增 pixKey 字段。
  • 修复对账单中静态/动态 QR Code 分类问题。

v1.5.0 (2026-02-05) - URL 标准化、Payments API 与 QR Code 修复​

破坏性变更​

URL 标准化​

此前将 accountId 作为 query 参数的所有端点，现统一改为在 /v1/accounts/{accountId}/... 中作为路径参数。这使整个 API 的 URL 模式更加一致、符合 REST 风格。

迁移指南：

旧 URL新 URL
GET /v1/pix/transactions?accountId=XGET /v1/accounts/{accountId}/pix/transactions
GET /v1/payments?accountId=XGET /v1/accounts/{accountId}/payments
GET /v1/payments/{id}?accountId=XGET /v1/accounts/{accountId}/payments/{id}
GET /v1/pix/qr-codes?accountId=XGET /v1/accounts/{accountId}/pix/qr-codes
GET /v1/pix/qr-codes/stats?accountId=XGET /v1/accounts/{accountId}/pix/qr-codes/stats
POST /v1/pix/qr-code/accounts/{id}/dynamicPOST /v1/accounts/{accountId}/pix/qr-code/dynamic
POST /v1/pix/qr-code/accounts/{id}/staticPOST /v1/accounts/{accountId}/pix/qr-code/static
GET /v1/pix/qr-code/accounts/{id}GET /v1/accounts/{accountId}/pix/qr-code
DELETE /v1/pix/qr-code/accounts/{id}DELETE /v1/accounts/{accountId}/pix/qr-code
GET /v1/pix/keys/accounts/{id}GET /v1/accounts/{accountId}/pix/keys
POST /v1/pix/keys/accounts/{id}POST /v1/accounts/{accountId}/pix/keys
DELETE /v1/pix/keys/{key}/accounts/{id}DELETE /v1/accounts/{accountId}/pix/keys/{key}
GET /v1/pix/medGET /v1/accounts/{accountId}/pix/med
POST /v1/pix/med/{id}/responsePOST /v1/accounts/{accountId}/pix/med/{id}/response

注意： 旧 URL 为保证向后兼容仍可使用，但已弃用，未来版本将移除。

新功能​

Payments API​

  • GET /v1/accounts/{accountId}/payments：查询所有 PIX Out 支付意图。
  • GET /v1/accounts/{accountId}/payments/{paymentId}：查询支付详情。

缺陷修复​

QR Code 对账​

  • 修复竞态问题：当 charge webhook 先于 PIX webhook 到达时，QR code 支付未能关联到对应交易。

v1.4.0 (2026-01-16) - Webhook 事件类型标准化与文档更新​

新功能​

Webhook 事件类型改进​

  • 新事件 pix.med.updated：当 MED/违规状态更新时通知。
  • 改进 PIX IN/OUT 区分：更清晰地区分入账与出账 PIX 事件。

标准化事件类型​

以下事件类型现已在所有系统中保持一致：

  • pix.in.completed - 入账 PIX 已完成
  • pix.out.completed - 出账 PIX 已完成
  • pix.out.failed - 出账 PIX 失败
  • qrcode.paid - QR Code 已支付
  • pix.refund.completed - 退款已完成
  • pix.refund.failed - 退款失败
  • pix.med.opened - MED/违规已发起
  • pix.med.updated - MED/违规已更新

文档​

  • 完整英文翻译：OpenAPI 规范与 Postman 集合现已完全英文版。
  • 事件类型文档更新：所有 webhook 文档均已更新为标准化事件类型。
  • 一致性改进：事件类型在前端、API handler 与文档中保持一致。

破坏性变更​

  • 旧事件类型（pix.received、pix.cash_in、pix.cash_out）已弃用，建议迁移到新标准类型。
  • 已使用旧事件类型的 webhook 订阅仍可工作，但建议尽快迁移。

v1.3.0 (2026-01-29) - QR Code 统计与 Charge Webhook​

新功能​

QR Code 统计​

  • 新增端点 GET /v1/pix/qr-codes/stats：返回最近 24 小时聚合后的 QR Code 统计数据。
    • 已生成、已支付、已退款的 QR Code 数量
    • 金额汇总（生成、支付、退款）
    • 转化率（paid/generated）
    • 按小时聚合数据用于趋势分析

Charge Webhook（COB）​

  • QR Code 支付通知：动态 QR Code 被支付后，系统会自动将状态更新为 PAID 并发送 webhook。
  • qrcode.paid 事件：当 QR Code 被 BACEN 确认支付时发送 webhook。
  • 自动 webhook 注册：创建 PIX key 时会自动注册 charge webhook 以接收支付通知。

缺陷修复​

  • 修复余额显示值问题。
  • 修复对账单交易金额问题。

文档​

  • OpenAPI 规范新增 QR Code 统计端点。
  • Postman 集合更新为包含新的统计端点。

v1.2.0 (2026-01-27) - Integrator Portal 与 Webhook​

新功能​

  • Integrator Portal：新增文档，包含门户链接与能力说明。

变更​

  • 通过 Portal 管理 Webhook：Webhook 配置现仅通过 Integrator Portal 进行。
  • 文档调整：移除公开 webhook 管理端点引用；仅保留 POST /webhooks/replay 与 GET /v1/webhooks/events。

v1.1.0 (2026-01-27) - 通过 API 管理 Webhook​

新功能​

自助式 Webhook​

  • 通过 API 执行 Webhook CRUD：现在可以直接通过 API 创建、查询、更新、删除 webhook 配置，无需联系支持团队。
  • 多种认证类型：支持 HMAC、API_KEY、BASIC、BEARER、IP_WHITELIST。
  • 事件类型过滤：可配置每个 webhook 应接收的事件类型。
  • 可用事件端点：新增 GET /v1/webhooks/events 端点，用于列出所有支持的事件类型。

新增 Webhook 事件​

  • pix.pending：当 Pix 处于待确认状态时发送（适用于实时支付跟踪）。
  • pix.qrcode.cash_in：用于 charge 场景下 QR Code 支付的专用事件。

安全​

  • Webhook IP 限制：Webhook 端点现支持来源 IP 限制。

缺陷修复​

  • 改进 webhook 文档，提供更详细示例。
  • 修复 webhook 事件中的 payload 示例。

v1.0.0 (2025-12-29) - 首次发布（CorpX API）​

这是 CorpX API 面向外部集成方与银行合作伙伴的统一公开文档首个正式版本。

主要功能​

Pix 与 Payments​

  • Pix Out：使用 Pix key 一步完成即时转账。
  • QR Codes：支持动态与静态 QR Code 生成，并支持收款、状态查询与取消。
  • Refunds：支持已收 Pix 的退款流程。
  • Pix MED：完整支持用于违规与争议管理的特别退回机制。

账户管理​

  • 余额查询：可查看总余额、可用余额与冻结余额明细。
  • 对账单：分页展示交易与账户资金变动历史。
  • 内部转账：同平台账户之间的 P2P 资金划转。

Webhook 与通知​

  • 出站通知：自动接收事件（Pix 入账、Pix 出账、MED 更新）。
  • 安全性：所有通知均使用 HMAC-SHA256 签名，保证来源可信。
  • 重试机制：支持指数退避的自动重试系统。
  • 重放自助：可通过 API 请求重发通知（单条或批量）。

安全与幂等​

  • 认证：通过 Identity Provider 使用 OAuth2（client_credentials 与 authorization_code 流程）。
  • 幂等性：通过 Idempotency-Key 请求头保证可变操作仅执行一次。
  • 交易签名：所有 Pix 转账操作使用 RSA-SHA512 签名保护。

多语言支持​

  • 文档提供 葡萄牙语、英语 与 简体中文 版本。

开发者体验​

  • OpenAPI 3.0：提供可下载的完整规范与交互式 Swagger UI。
  • Postman Collection：提供可直接在 Sandbox 环境测试的集合。
  • Integrator Guide：提供请求头、错误处理与最佳实践的详细说明。