跳到主要内容

更新日志

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

v2.20.1 (2026-06-15) - 外部手续费的 fee.charged 与 fee.refunded​

当手续费由 API 之外发起（计费服务或清算方）时，现在也会发送手续费 Webhook。此前这些场景会以 transfer.internal.out（收取）或 transfer.internal.in（退还）的形式投递，这与合约不一致 — 现已遵循 官方类型：

  • fee.charged — 当手续费从客户账户借记到手续费对手方（如 Corp X Brasil LTDA 或 MT Instituição de Pagamento SA）时触发。 包含 feeServiceType（PIX / TED / BOLETO / INTERNAL_TRANSFER / MONTHLY / OTHER）以及引用触发交易的 originalRef / transactionRef。
  • fee.refunded — 当清算方退回先前收取的手续费时触发。

通过 API 发起的手续费（目前较少）仍不会生成这些事件；它们专用于 外部发起的资金动向。

数据结构遵循 Webhooks → 9. fee.charged / 9.1. fee.refunded 文档中 的契约。

v2.20.0 (2026-06-12) - DICT 查询速率限制与 24 小时缓存​

DICT 查询（GET /v1/accounts/{accountId}/pix/key/{pixKey}）现在会遵守 租户或账户策略中配置的限制：

  • maxLookupsPerDay — 每日（巴西利亚时间）查询的绝对上限。0 或 未设置 = 无限制。
  • maxLookupRatio — 相对上限：ratio × pix_outs_24h。示例： ratio 3.0 且最近 24 小时内有 100 笔 PIX out 时，同一窗口内允许 300 次查询。

当两者都配置时，以更严格的为准。任一限制被突破将返回 429 dict_lookup_limit_exceeded，message 中包含当前计数。

此外，24 小时缓存现已真正生效：在 24 小时内重复查询同一密钥会立即返回 cached: true，且不计入限额 — 策略的目的是防止滥用 DICT，而不是惩罚 重复查询。如需强制重新查询，请在查询参数中传 noCache=true。

限制可在后台管理（Policies → DICT Lookup）中配置。未配置策略的租户保持 无限制（行为不变）。

v2.19.1 (2026-06-11) - 修复：发起退款时误发 pix.refund.received Webhook​

修复：发起退款（POST /v1/accounts/{accountId}/pix/out/refund）时， 您的 Webhook 端点可能会收到一个错误的 pix.refund.received 事件 — 仿佛您收到了第三方的退款，而实际上退款是您自己发起的。

修正后的行为：

  • 通过 API 发起的退款：您只会收到正常退款流程的确认 （pix.refund.completed / pix.refund.failed），不会再生成 pix.refund.received。
  • 在 API 之外发起的退款（如清算方渠道）：您会收到带有 external: true 的 pix.refund.completed / pix.refund.failed。
  • 收到第三方退款（交易对手退回您发送的 PIX）：pix.refund.received 仍会正常发送。

v2.19.0 (2026-06-10) - 移除单笔 PIX 交易 R$ 15,000 限额；BigPix 已弃用​

单笔 PIX 交易 R$ 15,000 的限额已被清算方移除。 POST /v1/accounts/{accountId}/pix/out（以及 /async、/bank-account、 /qr-code 变体）现在单笔交易可接受任意金额 — 无需再拆分为多笔 PIX 转账。

因此，BigPix 已弃用：

  • POST /v1/accounts/{accountId}/pix/out/bigpix
  • POST /v1/accounts/{accountId}/pix/out/bank-account/bigpix
  • GET /v1/accounts/{accountId}/pix/out/bigpix/{batchId}

为保持向后兼容，这些端点仍然可用，但响应中现在包含 Deprecation: true 头。建议迁移到 POST /pix/out（或 /pix/out/bank-account），请求结构相同 — 只需在 amount 字段中发送总金额。最终移除日期将提前在本更新日志中公布。

您账户的运营限额（每日、夜间、按交易对手）仍然有效 — 请参阅 GET /v1/accounts/{accountId}/limits。

v2.18.3 (2026-06-09) - 外部内部转账的 Webhook 支持​

同一银行（MT Bank）账户间的内部转账，若并非通过 API 发起（如通过手机 应用或合作方控制台），现在也会触发 transfer.internal.in（收款账户收到 通知）或 transfer.internal.out（付款账户收到通知）Webhook。

这是对现有功能的补充：通过 POST /v1/accounts/{accountId}/transfers/internal 发起的内部转账已经会向双方发送 Webhook。现在，即使您未通过 API 发起的资金 移动，也会通知到您的 Webhook 端点，并在 payload 中包含 external: true 字段，表明该交易来源于外部。

v2.18.2 (2026-06-07) - 退款错误更精确​

PIX 退款（POST /v1/accounts/{accountId}/pix/out/refund）：当原始交易 不可退款（状态不是 Confirmed——已退款/已冲正、被拒绝或仍在处理中）时， 拒绝结果现在返回 errorCode: conflict，并在 errorReason/message 中给出 结算方的原因（例如 Transação com status diferente de 'Confirmado'.）。

此前该情况返回 errorCode: invalid_payload，且 errorReason 包含合作方的 原始 JSON。现在该代码正确地反映为状态冲突（而非无效载荷），原因信息也 更清晰。

此外，对账单的精确查询（GET /v1/accounts/{accountId}/statement 通过 endToEndId/identifier）现在会直接查询结算方，条目中可能包含可选字段 initiation、errorMessage 和 fee，以及完整的 payer/payee/counterParty。

v2.18.1 (2026-06-07) - 余额为只读（我方不做余额冻结）​

合约澄清：本 API 不处理余额冻结。GET /v1/accounts/{accountId}/balance 仅在 locked 字段中展示由结算方（MT）冻结的金额（镜像 MT 的冻结值）。 不存在余额 lock/unlock 接口，也没有"本地 hold"。

余额响应不再包含 locks 字段（本地冻结列表）——该字段从未被填充，已从 规范中移除。total、locked、available、currency 和 updatedAt 字段保持不变。

v2.18.0 (2026-06-06) - 每日余额、更丰富的对手方信息及新的对账单筛选条件​

新接口 GET /v1/accounts/{accountId}/daily-balance：返回账户的每日余额序列 ——每日开始时的余额（总额/冻结/可用）以及当日的汇总流水（PIX 收入/支出、TED 收入/支出、内部转账、boleto 付款、稳定币 mint/burn 以及手续费）。日期为 巴西利亚时间（BRT）的自然日。最大查询窗口为 30 天。仅返回 2026-06-04 起的结算数据（合作方在该日期之前的数据不可靠，更早的数据将被省略）——响应中 包含 cutoffDate 与 timezone。

对账单（GET /v1/accounts/{accountId}/statement）——新增字段（增量、向后兼容）：

  • transactionType：代码 C（贷记/收入）或 D（借记/支出），与 direction 对应。
  • counterParty 现在在合作方提供时包含对手方的银行信息：bankName、bankIspb、 bankCode、branch、account、accountType、pixKey（此前仅有 name 和 document）。

对账单——筛选现已全部在服务端进行：

  • operation 筛选（PIX、TED、BOLETO、INTERNAL_TRANSFER）在合作方侧应用， totalElements/totalPages 准确。可与 order（asc/desc）及 startDate/endDate 组合使用。
  • 已移除 status 与 operation=FEE 筛选：它们此前仅作用于当前页（分页之后）， 会导致计数不一致。响应中的 filteredCount 字段也已移除。如需按状态或手续费筛选， 请在您侧处理返回的 items。

v2.17.0 (2026-06-05) - identifier 长度上限提升至 38 个字符​

集成方在 PIX 出款、QR 码（静态/动态）以及内部转账中提交的 identifier 字段，现支持最多 38 个字符（之前为 32）。 允许的字符集（[A-Za-z0-9._-]）和保留前缀 fee- 保持不变。

这是完全向后兼容的变更：现有不超过 32 字符的 identifier 仍然有效，集成方无需修改任何代码。仅上限被放宽。

动机：将单笔支付的 identifier 上限与 BigPix 批量基础 identifier 上限对齐（BigPix 已是 38 字符）。同时使用两种接口的 集成方不再需要为各自维护不同的 id 生成规则。

v2.16.0 (2026-06-02) - Legacy 对账单（cutover 前）​

新增端点 GET /v1/accounts/{accountId}/statement/legacy，用于查询从 旧核心（Finaya/Stark）导入的历史交易（legacy_transactions）。

契约： 与 GET /v1/accounts/{accountId}/statement 相同 （page、size、startDate、endDate、status、operation）。 响应 source: legacy，头 X-Source: legacy。每条记录含 ispb （Finaya 30306294、Stark 20018183）及 source: legacy。

不变： live 对账单（GET .../statement）仍仅 MT Bank 实时数据。

legacy + live 合并导出：异步 CSV（POST /v1/accounts/{accountId}/exports）。

v2.15.0 (2026-05-30) - 对账单 CSV 导出恢复​

对账单 CSV 导出已恢复：实时 MT Bank 数据与 legacy 历史 （legacy_transactions）合并导出。

端点：

  • POST /v1/accounts/{accountId}/exports — 创建异步任务 (202)
  • GET /v1/accounts/{accountId}/exports — 列出任务
  • GET /v1/accounts/{accountId}/exports/{exportId}/download — 预签名下载 URL

CSV： 与对账单字段对齐，含 ispb 列以区分 Finaya/Stark（legacy） 与 MT Bank（live）。不含交易后余额（balance）。live 查询按 31 天窗口分片。

v2.14.0 (2026-05-30) - 查询账户银行信息​

新增端点 GET /v1/accounts/{accountId}/bank-account，用于查询 已开户账户的银行代码（COMPE）、分行和账号。

响应 (200)：

  • bankCode、bankIspb、bankName、branch、accountNumber
  • holderDocument、holderName、accountId、status

适用于展示入金指引或在无 PIX 密钥时进行对账。仍在开户流程中的 账户返回 422 及明确说明。

v2.13.0 (2026-05-25) - QR Code 解码返回更丰富的字段​

POST /v1/accounts/{accountId}/pix/out/qr-code/decode 端点现在会返回结算行在 QR 抓取（capture）步骤中提供的全部信息—— 此前大部分字段仅记录在内部日志中。本次变更完全向后兼容：所有 原有字段名称与结构保持不变，仅新增可选字段。

新增的可选字段（仅在结算行返回时出现）：

  • originalAmount — 在折扣/利息/罚金生效前的 QR 原始金额（dynamic-due-date 下可能与 amount 不同）。
  • qrCodeType（static | dynamic-immediate | dynamic-due-date）与 qrCodeTypeId（数字）——提升至顶层（此前 仅出现在 Extra 中）。
  • allowChange —— 在 dynamic-immediate 下现在真正基于结算行 （AllowPayerChangeValue）填充；此前已在文档中提及但实际从未被 设置。
  • payeeTradeName —— 法人主体的商业名（通常在 dynamic-due-date 发票中出现）。
  • bankIspb / bankBranch / bankAccount / accountType —— 收款方银行账户信息。accountType 被规范化为 CHECKING | SAVINGS | PAYMENT | SALARY，未知变体以大写下划线 形式返回。
  • discount、deduction、interest、penalty —— dynamic-due-date 的金额组成。关系：amount = originalAmount - discount - deduction + interest + penalty。此前文档仅描述 discount，且取值始终为 0。
  • dueDate 与 paymentDeadline —— 提升至顶层（为兼容旧调用方， 仍同时保留在 Extra 中）。

兼容性：key、amount、payeeName、payeeDocument、 identifier、decodeId、description 字段名与结构均未变化。 现有集成无需修改即可继续运行。

v2.12.1 (2026-05-24) - 新增 PIX 状态 PENDING_APPROVAL​

PIX 相关端点（GET /v1/accounts/{accountId}/pix/payments/lookup、GET /v1/accounts/{accountId}/payments/{paymentId}、对账单和 webhook 信封）新增规范化状态：

  • PENDING_APPROVAL — 结算行已接受 PIX OUT 请求，但因内部审批 （多人会签、二次验证、反欺诈审查）被挂起。尚无 endToEndId， 资金未发生转移。结算行最终会放行（转为 PENDING → COMPLETED）或拒绝（转为 FAILED）。

为何引入此状态：此前，该场景会将合作方的原始值 （AWAITING-AUTHORIZATION）直接透传给公共 API。从本版本起， 我们绝不再透传合作方原始值 —— 所有状态都将经过规范化。 未列入已知词汇表的值统一映射为 UNKNOWN 并在我方触发结构化告警， 以便我们在下一个版本中补充映射。

对普通 PIX OUT 集成无影响（典型流程仍是 PROCESSING → COMPLETED/FAILED）。需监控中间状态的集成应将 PENDING_APPROVAL 视为非终态（继续轮询或等待下一条 webhook）。

pix.out.completed / pix.out.failed webhook 仍仅在终态时触发 —— PENDING_APPROVAL 不会触发出站 webhook。

v2.12.0 (2026-05-23) - TED 可用（发送 + 接收）​

重大版本：TED（Transferência Eletrônica Disponível BACEN）现在是公共 API 产品。涵盖银行间发送、异步状态查询和接收 webhook。结算银行：MT Instituição de Pagamentos（Compe 681 / ISPB 50871921）。参见 TED 指南。

新端点​

  • POST /v1/accounts/{accountId}/ted/out — 发送 TED（异步，202）
  • GET /v1/accounts/{accountId}/transfers/ted/{tedId} — 查询状态（PROCESSING → COMPLETED | FAILED）

新 webhooks​

  • ted.out.requested — TED 在结算银行注册（初始状态）
  • ted.out.confirmed — 结算确认（终态 — 成功）
  • ted.out.failed — 拒绝/过期/48 小时超时（终态 — 失败）
  • ted.in.received — 您的账户收到 TED

时段和时效​

  • 工作日 06:30–17:00 → 同一工作日结算（发送后约 30 分钟）
  • 时段外 → 安排到 D+1 工作日；状态保持 PROCESSING 直到结算
  • 服务器每 1 分钟运行防御性轮询，最多 48 小时 — 即使结算银行 webhook 失败也保证收敛

弃用​

ted.payment（v1 遗留目录）成为 ted.out.confirmed 的已弃用别名。在 v2.x 生命周期内一起分发；ted.payment 将在 v3.0 中移除（日期待定）。

  • 新集成方：只订阅 ted.out.confirmed
  • 遗留集成方：可保留 ted.payment 直到 v3.0；迁移是取消订阅 + 订阅 ted.out.confirmed（负载相同）

v2.11.1 (2026-05-22) - 修复:同租户下多个订阅时 webhook 重复推送​

对在同一租户下为同一 eventType 配置了多个活跃订阅的接入方有直接影响的缺陷修复。

旧版本中,每一个匹配的订阅都会向出口(Hookdeck)发起一个独立的 POST。由于 Hookdeck 过滤器是按 body 中的 tenantId + type 进行匹配, 这些 POST 都会被分发到所有目的地,导致推送数量被放大:同一租户下 有 N 个订阅匹配同一事件时,会收到 N² 次推送,而不是 N 次。

从本版本开始,每个事件只产生 1 个 POST 到出口,由 Hookdeck 负责 分发到 N 个目的地(每个订阅 1 次推送,不再重复)。

载荷与契约保持不变,仅修复了推送数量。如果你已实现按信封 id 进行 客户端去重(推荐),可继续保留。

v2.11.0 (2026-05-22) - Webhook 信封恢复 v1 格式​

通过 POST /v1/webhooks 注册的 URL 接收到的出站 webhook payload，信封格式 恢复为 v1 所记录的同一格式。已从 v1 迁移到 v2 但未调整 webhook 解析器的客户， 现在能在原来的位置接收到所有字段。

信封（所有事件通用）：

字段之前（v2.10）现在（v2.11）
schemaVersion缺失"1.0"
environment缺失"production" | "sandbox"
accountId（根级）仅在 data.accountId加到根级（data.accountId 仍保留）
tenantId（根级）已存在保留

data 字段按事件调整（与 v1 对齐）：

  • pix.in.completed：endToEndId 重命名为 endToEnd；新增 receivedAt。
  • pix.out.completed / pix.out.failed：status 现在是 "SUCCESS" / "FAILED"（之前是 "COMPLETED"）；使用密钥发送 PIX 时新增 key: { type, key }；新增 completedAt；失败时新增 error（=errorReason）。
  • pix.refund.received：refundEndToEndId → refundEndToEnd； originalEndToEndId → originalEndToEnd；新增 receivedAt。
  • qrcode.paid：endToEndId → endToEnd；paidAmount → amount； payerName/payerDocument 合并为 payer: { name, document }；新增 qrcodeId（=txid）、type（static | dynamic）、receivedAt、 status: "SUCCESS"。
  • qrcode.cancelled：新增 status: "CANCELLED" 和 type。
  • qrcode.expired：新增 status: "EXPIRED" 和 type。
  • pix.med.opened / pix.med.updated：名称修正为 pix.med.*（后端原本发出 med.opened / med.decided，这些不在公开目录中—— 实际上集成商从未收到这些事件）。originalEndToEndId → originalEndToEnd； 新增 status（OPEN | PENDING_DECISION | ACCEPTED | REJECTED | CANCELED）。
  • transfer.internal.in / transfer.internal.out：endToEndId → endToEnd。
  • boleto.paid / boleto.failed：status 现在是 "SUCCESS" / "FAILED"； 失败时新增 error 别名。

已移除：currency 字段不再发送也不再文档化——所有金额按合同均为 BRL （巴西雷亚尔），使用点作为小数分隔符（150.50）。v2 大多数事件中 currency 从未真正进入生产，移除以关闭最后一个缺口。

兼容性​

不再为旧名称提供别名。如果您原先使用 data.endToEndId 处理 PIX in 或 data.paidAmount 处理 QR 已支付，必须改名为 data.endToEnd 和 data.amount。 请参考 Webhooks 中的最新示例。

v2.10.0 (2026-05-22) - 退款原因与合作银行对齐​

POST /v1/accounts/{accountId}/pix/out/refund（以及 POST /pix/out 中 mode=REFUND）现在 reason 字段只接受封闭的 kebab-case slug 列表。旧值（USER_REQUESTED、FRAUD、 BANK_ERROR、CASHIER_ERROR、CUSTOMER_REQUEST）不再被接受—— 使用这些值的请求会收到 HTTP 400，并列出有效的 slug。

接受的 slug 会原样转发给合作银行（MT Bank），不做转换：

Slug使用场景
user-requested终端客户申请退款
transaction-error通用交易错误
unauthorized-transaction未授权交易
fraud已确认/疑似欺诈
trade-disagreement商业纠纷
withdrawal-purchasePIX Saque/Troco
contractual-divergence合同分歧
operational-error操作/处理错误
duplicate-payment重复支付

变更原因： v2 退款端点之前对所有请求返回 HTTP 422，因为旧词汇与合作 银行接受的词汇不匹配。本版本将公开 API 与合作银行 1:1 对齐，避免不透 明的映射。

v2.9.0 (2026-05-21) - 对账单中的对手方证件号​

对账单项（GET /v1/accounts/{accountId}/statement）现在除了对手方姓名外， 还会返回 对手方证件号（CPF/CNPJ）：

  • recipientName：对手方姓名（原有字段）。
  • recipientDocument：新字段 —— CPF（11 位）或 CNPJ（14 位）， 仅数字、无掩码。
  • counterParty：新对象，聚合 { name, document }。当两个字段都为空时省略。

对于 direction: "IN" 的交易，对手方为 付款方； direction: "OUT" 则为 收款方。所有字段向后兼容 —— 不需要证件号的对接方无需做任何调整。

v2.0 (2026-05-21) - 全新 CorpX 平台​

v2 是基于更快、更可预测的基础设施对平台的完整重写，并直接与新的 清算行集成。总体上向后兼容 v1。

迁移指南

迁移所需的一切都集中在一个文档中：

认证​

  • 新的基础 URL：https://tenant.api.corpx.com/v1（原 https://api.corpxapi.com/v1）
  • 新的 Token URL：https://auth.api.corpx.com/oauth2/token
  • 每个集成方有新的 client_id + client_secret（通过安全渠道交付）
  • 作用域：api/full → api2/read api2/write
  • Idempotency-Key 变为可选（缺失时自动生成）
  • 所有 /v1/* 请求均需提供 X-Tenant-Id（GET /v1/me 与健康检查除外）；路径含 accountId 时必须与账户所属租户一致

对账单已整合为单一端点​

  • GET /v1/accounts/{accountId}/statement 现在始终为实时 —— 实时查询清算行（无本地缓存）。
  • 之前从同一缓存读取的派生端点（/pix/transactions、/pix/payments、 /payments 别名）现在也是实时的。
  • 切换后 30 天内，旧版 v1 API 和后台继续在线，处于只读模式， 可用于历史查询。
  • /transactions/real-statement、/transactions/legacy-statement 和 /payments/{id}/legacy 在 v2 上不存在 —— 使用 /statement （当前数据）或只读 v1 API（历史数据）。

已废弃端点（在 2026-11-21 之前仍可用）​

v1 上存在但未保留在 v2 规范形态中的 4 条路径，已作为已废弃别名重新启用。它们仍正常响应，仅在响应中附加 3 个警示响应头：

Deprecation: true
Sunset: Sat, 21 Nov 2026 00:00:00 GMT
Link: </v1/accounts/.../新路径>; rel="successor-version"

这些响应头遵循 RFC 8594（Deprecation）和 RFC 9745（Sunset）。预定下线日期：2026-11-21 —— 之后开始返回 410 Gone。它们不再出现在 OpenAPI 和 Postman 集合中。

  • GET /v1/accounts/{id}/pix/payments/{paymentId} → 使用 /pix/payments/lookup?identifier=
  • GET /v1/accounts/{id}/payments/{paymentId}（无 /pix/ 别名） → 使用 /pix/payments/lookup?identifier=
  • GET /v1/accounts/{id}/pix/qr-code（不带 /lookup） → 使用 /pix/qr-code/lookup?identifier=
  • POST /v1/accounts/{id}/pix/out/qrcode（无连字符） → 使用 /pix/out/qr-code

已移除的端点（v2 上返回 404）​

  • POST /v1/webhooks/replay → 无替代
  • GET /v1/integrator/webhooks → 使用 GET /v1/webhooks
  • GET /v1/integrator/webhooks/{id}/deliveries → 无替代
  • POST /v1/integrator/events/replay + /batch → 无替代
  • POST .../pix/med/{medId}/send + /response → 使用 /decide + /answer

GET /v1/health 在 v2 上仍然存在（并新增 GET /health 别名用于 外部健康检查）。

新增端点​

  • GET /v1/me（用于调试已认证的 client_id）
  • GET /v1/transactions/{id}/timeline（路径中无 accountId）
  • GET /v1/accounts/{id}/pix/out/bigpix/{batchId}（BigPix 批次聚合状态）
  • GET /health（/v1/health 的无前缀别名）
  • Boleto 全家族（POST .../boleto/preview|pay、GET .../boleto/payments/{id}） —— v1 上为 503，现在已激活

行为变更（相同路径，新的结构或语义）​

  • 对账单及派生端点：缓存 → 实时；不再有派生的 tariff_ref；X-Source: live 请求头；单次查询最大 31 天窗口。
  • Internal transfer by-bank-account：可选接受 holderDocument + holderName（非破坏性）。
  • Locked balance unlock：v2 仅校验 lockId；忽略多余字段（非破坏性）。
  • 交易对象上的 fee 字段暂时移除 —— 通过对账单中 identifier=fee-{slug}-{operationReferenceId} 进行手动对账。 未来版本将无载荷变更地恢复。

MED 与 webhook 暂时暂停​

  • 迁移期间 /v1/accounts/{id}/pix/med/* 端点返回 HTTP 503。 开放争议遵循 BACEN 的自然生命周期 —— 仅 API 集成被暂停。
  • 暂停的 webhooks：fee.*、pix.med.*、edi.*。可以继续订阅这些 事件 —— 一旦恢复，会自动继续投递。手续费仍以单独的行出现在 对账单中（带有 identifier=fee-{slug}-{ref}）。

兼容性（您的代码无需更改）​

  • BigPix（POST .../pix/out/bigpix 与 .../bank-account/bigpix）： body 仍为单笔（{amount, key, ...}）；分块仍在服务端处理，与 v1 相同。
  • PIX out 变体（/pix/out/async、/bank-account/async、/bank-account/bigpix）：保留。
  • /v1/accounts/{accountId}/transfers/internal（全部 3 种模式）：路径和 body 保留。
  • /v1/accounts/{id}/pix/qr-code/static body：value 与 v1 相同。
  • /v1/accounts/{id}/pix/out/qr-code/decode：路径保留。
  • /v1/accounts/{id}/pix/keys（GET + POST + DELETE）：保留。
  • /v1/accounts/{id}/pix/key/{pixKey}（DICT lookup）：保留。

支持​

联系方式：suporte-api@corpx.com 在租户切换期间 —— 工作时间 1 小时内回复。

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：提供请求头、错误处理与最佳实践的详细说明。