跳到主要内容

更新日志

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

v2.53.0 (2026-08-07) - maxLookupRatio 移除，按窗口的限额改为始终生效​

  • maxLookupRatio 限额已移除。 它允许的查询次数为 ratio × 最近 24 小时内已完成 的转账笔数。这与 24 小时窗口的 maxUsageRatio 是同一个计算，但精度更差：只有一个 窗口，没有自己的样本下限，需要依赖 50 次查询的全局下限才不会卡住没有转账的账户。 窗口机制在从 5 分钟到 30 天的十二个档位上做了同样的事。
  • 该字段仍被接受，但会被忽略。 请求体中仍带有该字段的策略不会因此报错，只是这个 数值不再参与判定。429 消息中不再出现 ratio 这一拒绝原因， (bootstrap floor of 50 lookups/24h applied) 这条提示也一并消失。
  • 按窗口的限额现在始终生效。 此前它们只在有人写入策略的地方存在。现在，未声明数值 的档位会继承全平台基线：所有窗口的 maxUsageRatio 为 2.2、maxFailureRatio 为 0.3，样本下限为 30 分钟以内 20、1 小时至 12 小时 50、从 24 小时起按每天 500 计。 这些数值来自对 14 天真实流量的测算，在该历史区间内没有拦下任何账户。
  • 您需要做什么。 大概率无需任何操作。如果您的账户策略此前声明的 maxLookupRatio 严于每笔转账 2.2 次查询，实际上限会放宽；如果声明的更宽松，则改由 24 小时窗口判定。绝对上限（maxLookupsPerDay、maxLookupsPerMinute、 maxNotFoundPer5min）保持不变。详见 政策与规则。

v2.51.0 (2026-08-07) - 按时间窗口的密钥查询限额​

  • dictLookup 策略新增按时间窗口的速率上限。 在原有四项限额之外，每个窗口 （5m、15m、30m、1h、3h、6h、12h、24h、3d、7d、14d、30d） 都可以限制两个速率：每笔已完成 PIX Out 对应的查询次数（maxUsageRatio），以及 未解析出密钥的查询占比（maxFailureRatio）。详情与示例见 策略。
  • 不配置则一切照旧。 窗口默认不启用：只对配置了它们的账户或租户生效，未做任何 改动的接入方行为完全不变。
  • errorCode 仍为 dict_lookup_limit_exceeded。 变化的是消息内容，现在会说明 是哪个窗口超限、测得多少、上限是多少——例如 120 lookups for 10 successful transfers (12.0 per transfer); max 6.0。按错误码处理的无需任何改动；若您把消息 展示给最终用户，现在的文案更有用。
  • 多个窗口同时超限时，响应引用最短的那个，它是直接原因，也是最先恢复的。
  • 每个窗口都有样本下限（minLookups）。 低于该值时两个速率都不会拒绝，以免一个 查询次数极少的新账户被基于三次调用算出的速率阻断。

v2.50.0 (2026-08-07) - 开户与携带流程结束后，持有人会回到您的应用​

  • POST /v1/accreditations/pf 与 POST /v1/accreditations/pj 新增可选字段 callbackUri。 持有人完成其步骤后——人脸采集、BYO 确认或携带授权——会被带回 您的应用或网站，而不是停留在我们的完成页上。处理结果就带在该 URI 上，通过 outcome 返回，同时还有 accreditationId、完成者的 personId，以及当该 accreditation 涉及多人时的 remainingPeople。完整指南见 返回您的应用。
  • 该 URI 必须在首次使用前登记。 请联系 CorpX 支持团队，准确告知您将使用的 URI。 可接受 https:// 与您应用的自定义 scheme（deeplink）；比对为精确匹配，不支持 通配符，也不做前缀匹配。未登记的 URI 会当场拒绝本次创建，返回新增的 400 invalid_callback_uri 错误——而不是等到流程末尾才失败。
  • URI 上的这些参数不能证明任何事情。 它们出现在地址栏中，持有人本人就可以修改； 它们的用途是让您的应用决定展示哪个界面。任何会产生实际效果的决定，仍然取决于 webhook 或 GET /v1/accreditations/{accreditationId}。并且 outcome=biometry_approved 表示生物识别这一步结束了，并不表示账户已激活： 激活仍然通过 accreditation.active 送达。
  • persons[] 中新增 personId 字段， 在创建与查询的响应中均会返回。它是每个人在 该 accreditation 中的稳定标识符，也正是出现在返回 URI 中的值——CPF 不会被放进一个 会留在浏览器历史和代理日志中的 URI 里。这是新增字段：您已经在读取的内容没有任何变化。
  • 不使用 callbackUri 时，所有流程均保持不变。

v2.49.1 (2026-08-07) - account_not_entitled 现在同样适用于对账单与每日余额​

  • 在 v2.49.0 宣布为 409 account_not_entitled 的场景中，对账单与每日余额此前仍返回 502 partner_unauthorized。 该错误码确实已在那个版本上线，但这两项查询仍返回带有 "请几分钟后重试"提示的 502——这在本场景下并不成立：在清算机构为该账户开通此项服务 之前，该状态是持续性的。
  • GET /v1/accounts/{accountId}/statement 与 GET /v1/accounts/{accountId}/daily-balance 现在在此场景下返回 409 account_not_entitled，与 API 的其他操作一致。请将其作为确定性错误处理——携带 accountId 联系客服——而不是临时不可用。完整说明见错误。
  • 502 partner_unauthorized 保持不变，仍用于 CorpX 与清算机构之间真实的认证失败。

v2.49.0 (2026-08-06) - 清算机构未开通的服务不再表现为我方的临时故障​

  • 新增错误码 account_not_entitled（HTTP 409，不可重试）。 当账户已完成开户， 但清算机构未为其开通该项操作时返回此错误——同一账户的其他操作仍可正常使用。在 清算机构完成开通之前，该状态是持续性的：重试无法解决。收到此错误时，请携带 accountId 联系客服。完整说明见错误。
  • 此前该情况返回 502 partner_unauthorized，含义正好相反。 那条消息声称 CorpX 的凭证被拒绝，并建议几分钟后重试——在这种场景下两点都不成立，并导致接入方无休止 地重试。502 partner_unauthorized 保持不变，仍用于 CorpX 与清算机构之间真实的 认证失败。
  • 如果您在该路由上对 502 做了重试，请复查。 该场景现在返回 409，应作为确定性 错误处理（提交工单），而不是临时不可用。

v2.48.0 (2026-08-06) - 清算机构的拒绝不再被报告为您账户的限额问题​

  • 新增错误码 partner_rate_limited（HTTP 429，可重试）。 当清算机构因请求过多而 拒绝调用时，现在返回 429 partner_rate_limited。此前这种情况返回的是 422 limit_exceeded，其含义是"操作金额超出了账户上配置的限额"——于是您会去核查 账户限额，而实际触发的只是调用频率。这个错误说明您的请求本身没有任何问题：请降低 频率并使用退避策略重试。完整说明见错误。
  • 查询不存在的 PIX 密钥现在返回 404 key_not_found。 在 GET /v1/accounts/{accountId}/pix/key/{pixKey} 中，DICT 里不存在的密钥此前返回 400 partner_error，即通用的通信失败错误码。现在返回接口参考中早已描述的 404 key_not_found，无需解析错误信息即可处理。如果您的代码是通过 400 里的文本 来判断密钥不存在，请改为处理 404。查询不存在的二维码没有变化：仍然是 404 not_found。
  • 清算机构在没有响应体的情况下拒绝调用，不再表现为 message 为空的 401。 现在返回 502 partner_unauthorized，并且 message 会写明清算机构拒绝了该次调用 且未返回响应体。此前的 401 看起来像是您的凭证被拒绝，而实际涉及的是 CorpX 自己与清算机构之间的认证——会让接入方排查错误的一侧。401 和 403 始终只与您的 凭证和权限有关。
  • 密钥查询上的 429 现在有两种含义，通过 errorCode 区分。 dict_lookup_limit_exceeded 是您账户的查询配额，message 会说明是哪个计数器触发 的——参见政策与规则。 partner_rate_limited 与您的配额无关：这是清算机构对 CorpX 流量的限流。如果您目前 在这条路由上只根据状态码处理 429，请先读取 errorCode，再判断是否是账户配额用尽。

v2.47.0 (2026-08-06) - ratio 下限降至 50，maxLookupRatio 默认值升至 4​

  • 对于查得多、转得少的账户，maxLookupRatio 的上限收紧了。 ratio 的上限为 最近 24 小时成功转账的笔数 × maxLookupRatio，并且永远不会低于一个下限——正是这道 保护让新账户能够查询第一笔支付所需的密钥。该下限此前为每 24 小时 500 次，现在改为 每个账户每 24 小时 50 次。这是收紧而不是放宽：此前上限来自该下限的账户，现在 上限变小了。
  • 实际效果是 ratio 重新成为真正起作用的限额。 下限为 500 时，由于始终以最严格的 限额为准，触发限额的一方触发的都是日额度——maxLookupRatio 几乎从未真正生效。下限 降到 50 后，查询上限重新随该账户的转账量变化，这正是 ratio 的用意。
  • maxLookupRatio 的全局默认值由 1.2 升至 4。 默认值适用于自身策略中没有设置该项 限额的账户。此前下限较高时，它掩盖了默认值：ratio 几乎从未真正起作用，所以 1.2 也 从未造成困扰。下限降到 50 之后，ratio 开始真正起作用，而 1.2 会拦下每笔转账仅多查 询一点点的接入方——这正是付款前先查询以核对收款人的常见用法。取值 4 之后，上限与 真实用量相符。如果您的账户策略中已设置 maxLookupRatio，则对您没有任何影响： 已配置的值仍然优先于默认值。
  • 您需要做什么。 如果您的集成查询密钥的次数远高于实际发起的支付笔数，请检查查询 方式（24 小时缓存不消耗额度），或申请复核您账户的限额。当最终生效的是该下限时， 429 dict_lookup_limit_exceeded 的消息会写明 (bootstrap floor of 50 lookups/24h applied)。各项限额的默认值见政策与规则， 下限说明见 ratio 的 50 次/24 小时下限。

v2.46.0 (2026-08-05) - 所有密钥查询限额一律按账户计算​

  • PIX 密钥查询限额现在一律按账户计算。 四项限额（maxLookupsPerDay、 maxLookupRatio、maxLookupsPerMinute 和 maxNotFoundPer5min）均按账户逐个计量： 一个账户的查询绝不会计入另一个账户，即使两者属于同一租户。账户本身就是 DICT 计量的 单位，因此限额现在也落在账户上。
  • 配置在租户上的策略对每个账户单独生效。 租户策略中的 maxLookupsPerDay: 50 含义是"每个账户每天可查询 50 次"，而不是"50 次由各账户分摊"——租户策略是套用到每个 账户的模板，不是共享额度池。如果您当初是按租户合计用量来设定这个数字，请重新评估： 实际上限已经变大。账户级策略在存在时仍然优先于租户策略。详见 政策与规则。
  • maxLookupRatio 的上限现在只统计真正发生的转账。 ratio 的分母现在只考虑该账户 已完成的转账（包括事后被退回的）。失败或被拒绝的付款不再抬高上限——此前，反复重试 一笔出错的付款反而会让查询额度随着每次失败而增加。500 次/24 小时的下限依旧有效， 现在按账户计算。
  • PIX Out 内部发生的密钥查询将开始消耗额度。 以 KEY 模式付款时，必须先解析密钥 才能出款，而这次询问走的是与显式查询相同的 DICT。本版本中该行为默认关闭，由配置 控制；目前对您没有任何影响，正式启用前我们会提前通知。启用后，PIX Out 可能返回 429 dict_lookup_limit_exceeded——此时不会创建任何付款，没有 paymentId，也没有 交易，因此使用相同的 Idempotency-Key 重发仍然是安全的。24 小时缓存在两条路径之间 共享，所以先查询密钥再付款只消耗一次查询，而不是两次；BigPix 对整批只解析一次密钥。 参见政策与规则。
  • POST /v1/accreditations/pj 中的 company.tradeName 变为必填（该条目在版本 发布之后补记）。清算机构对 CNPJ 强制要求商号，此前会在整个流程末尾——生物识别与 审核之后——才拒绝该 accreditation；现在在创建阶段就返回 400 missing_fields。 若公司没有登记商号，请填写公司注册名称。参见企业开户。

v2.45.1 (2026-08-05) - DICT 中不存在的密钥重新被正确识别​

  • 修复：不存在的 PIX 密钥此前被报告为通用的 not_found。 在按密钥转账时， 不存在的密钥返回的是通用的"资源未找到"错误码，与其他任何缺失资源相同。现在 返回 key_not_found，即错误码中已经描述的专用错误码——无需解析 错误信息即可处理"密钥错误"的情况。
  • 密钥枚举检测恢复正常。 5 分钟窗口内无结果查询次数的限制依赖于该分类，由于 同一缺陷，此前从未触发。连续查询大量不存在密钥的调用方现在会收到 429 dict_lookup_limit_exceeded，并附带扫描模式的提示信息。您账户的限额详见 政策与规则。

v2.45.0 (2026-08-05) - 尚在开户流程中的账户返回 409，不再是通信错误​

  • 新增错误码 account_not_ready（HTTP 409）。 当账户已在 CorpX 存在、但其开户 流程尚未完成时，针对该账户的任何银行操作现在都会返回 409 account_not_ready。 此前这类调用会落入 502 partner_error，看上去像接口故障，实际上只是开户过程中的 正常状态。完整清单见错误。
  • GET /v1/accounts/{accountId}/balance 在该情况下不再返回零余额。 之前返回 200，且 total、available、locked 均为零，与空账户无法区分。现在同样返回 409 account_not_ready。如果您的代码把零余额理解为“账户没有资金”，请把 409 理解为“账户尚不可用”，并在开户状态变为 ACTIVE 之后再进行操作。

v2.44.3 (2026-08-05) - 被拒绝的密钥查询开始计入每日配额​

  • 修复：被拒绝的 PIX 密钥查询不扣配额。 当 DICT 拒绝该次查询时——无论是密钥格式 有误，还是对方针对您的限额已经用尽——这次调用既不计入每日计数器，也不计入比例 计数器。实际后果是：对一个总是失败的密钥反复重试的循环，永远碰不到上限。现在这类 拒绝会像其他查询一样消耗配额，循环在达到账户限额后即会收到 429 dict_lookup_limit_exceeded。
  • 我方故障仍然不计配额。 查询不可用或超时依旧排除在计数器之外：不会因为不属于 您的故障而损失配额。
  • 现在收到 429 该怎么办。 请把密钥被拒视为最终结果，不要重复同一次查询。您的 账户限额见策略与规则。

v2.44.2 (2026-08-05) - 无标识符的二维码付款不再悄无声息​

  • 修复：无标识符的二维码入账完全不产生 webhook。 当付款来自不携带标识符的 BR Code 时——典型情形是在 API 之外拼装、txid 字段填 *** 的静态码—— qrcode.paid 和 pix.in.completed 都不会送达。钱进了账户，却只能在对账单里看到。 现在两个事件都会正常送达，其中 identifier 为空，method 为 STATIC_QR_CODE。 由于没有标识符可供关联，请用 endToEnd 作为这类入账的去重键。
  • 新增静态二维码指南。 涵盖创建、通过 webhook 接收 付款、对账与取消，并说明为什么应当通过 API 生成代码，而不是自行拼装 BR Code。

v2.44.1 (2026-08-05) - 入账 PIX 的 method 会告诉您是否来自二维码​

  • 修复：pix.in.completed 中的 method 一直为空。 该字段虽然存在于载荷中，但 从未被填充，因此仅凭 webhook 无法判断这笔入账来自二维码还是 PIX 密钥。现在它始终 会带上 STATIC_QR_CODE、DYNAMIC_QR_CODE 或 DICT（PIX 密钥或银行信息）。
  • 账单中的方式与之一致。 此前在 GET /v1/accounts/{accountId}/statement 中， 所有入账 PIX 都显示为 DICT，包括通过二维码支付的。本版本之前的流水未做重新处理。
  • 按方式匹配的策略规则对入账 PIX 生效。 以方式为条件的 pixIn 规则此前从不匹配， 因为参与评估的方式为空。

v2.43.4 (2026-08-03) - 开户不再因地址补充信息过短被拒​

  • 修复：因地址补充信息（complement）导致开户被拒。 补充信息少于三个字符（例如 A）会使开户在流程末尾、生物识别之后被拒绝。由于该字段是可选的，现在过短时会在 提交时省略，账户可以正常创建。
  • 字段类拒绝现在会指明字段和限制。 部分校验拒绝此前只返回一条要求检查请求体的 通用信息。现在响应会带上 errorCode invalid_field、partner.field 中的字段名， 以及包含预期限制的说明。

v2.43.3 (2026-08-03) - 被拒付款重发后可以重新执行​

  • 修复：使用相同的 Idempotency-Key 重发被拒付款，现在会重新执行。 在部分拒绝 场景下——最常见的是账户余额不足——用相同的 key 重发并不会重新执行付款，操作会卡在 PENDING，唯一的出路是换一个新 key 重新发起。现在任何确定性拒绝都允许重发，并复用 同一个 paymentId。
  • 拒绝响应的格式统一了。 422 始终包含 paymentId、status、errorCode、 errorReason 和 completedAt，无论拒绝原因是什么，格式都一致。
  • TIMEOUT 的行为不变。 当结果不确定时，用相同的 key 重发仍然只返回已有状态， 不会再次提交付款——在换用新 key 之前请先与账户流水核对。

幂等性页面已重写，说明了各个场景的行为（成功、拒绝、处理中、 TIMEOUT、新 key），以及各业务的去重依据——PIX、内部转账、Boleto 和 TED 的规则各不 相同。

v2.43.1 (2026-07-31) - 无法访问余额与流水的收款凭证​

  • read 不再是必选项。 它现在只涵盖账户级的宽泛查询（余额、流水、时间线、账目 明细），创建凭证时可自行选择。此前每个凭证都会带上 read，恰好挡住了细粒度权限 本应支持的场景。
  • 每个范围都能查询自己的领域。 仅有 qrcode.manage 即可创建 QR 码并查看是否 已付款；pix_keys.manage 可列出密钥；exports.create 可下载文件； webhooks.manage 可跟踪投递记录；med.defend 可查询 MED。资金划转类范围同样 可查询自身操作的状态。
  • qrcode.manage 加上单一账户，即得到一个只在该账户上通过 QR 码收款、其他一律 看不到的凭证。
  • 已签发的凭证保持不变——此前创建的凭证仍保留所获得的 read。若需收紧权限，请 签发新凭证并吊销旧的。

详见身份验证指南。

v2.43.0 (2026-07-31) - 集成凭证的细粒度权限范围​

  • 可自行决定每个凭证的能力。 在面板（API Credentials）中创建凭证时，租户管理员 勾选范围：read、qrcode.manage、pix_keys.manage、webhooks.manage、 exports.create 和 med.defend。缺少该路由范围的凭证会收到 403 insufficient_scope，并指明缺少的范围。
  • QR 码凭证可查询自身 QR 的付款状态。 qrcode.manage 同时涵盖创建、取消和查询 （GET .../pix/qr-code/lookup），因此可以拥有仅用于收款、无法访问余额与流水的凭证。
  • 按账户限制。 凭证可限制在租户的特定账户上——例如让某个子系统只访问一个账户。 任何用户都无法签发超出自身权限范围的凭证。
  • 涉及资金划转的范围由 CorpX 签发（pix_out.create、refund.create、 internal_transfer.create、ted.create、boleto_payment.create、 med.decide）。在面板中申请这些范围会返回 403 scope_not_self_service。
  • 现有凭证保持不变。 已在集成的凭证仍拥有完整访问权限 （api2/read api2/write），无需任何操作。

详见身份验证指南。

v2.42.0 (2026-07-30) - 因待办事项临时暂停访问​

  • 两个新错误代码：tenant_suspended 和 tenant_disabled。 当存在未处理的 待办事项时，租户的访问可能被临时暂停。租户已暂停时，查询（GET）仍可使用 ——余额、流水、操作状态——写操作返回 403 tenant_suspended；租户已停用时， 所有路由返回 403 tenant_disabled。
  • 凭据不会被吊销。 同一组 client_id/client_secret 仍可正常获取令牌，拒绝 发生在调用 API 时。待办事项处理完毕后，下一次调用即可恢复访问，无需新凭据或新 令牌。
  • 入账资金不受影响。 收到的 PIX 仍会入账，相关事件的 webhook 也照常发送。 暂停限制的是发起新操作，而不是接收。

详见认证指南。

v2.41.1 (2026-07-30) - 被拒绝的内部转账不再返回“处理中”​

  • 清算机构拒绝时返回 422。 POST /v1/accounts/{accountId}/transfers/internal （以及 /by-document 和 /by-bank-account 变体）此前在清算机构拒绝时返回 202 且 status: "PENDING"：交易实际已终结，响应却要求继续等待。现在拒绝会 返回 422，带 status: "FAILED"、errorCode 和 errorReason，与接口契约 一致。202 PENDING 仅保留给真正不确定的情况（同步窗口结束时操作仍在执行）。
  • 因余额不足被拒时返回 insufficient_funds 而非 partner_rejected。 清算机构因余额不足拒绝内部转账时只给出笼统说明（“清算机构拒绝了该操作”）。 现在我们在拒绝发生时读取可用余额：若不足以支付请求金额，响应为 insufficient_funds。没有该证据时仍为 partner_rejected，清算机构给出的 原因保留在 partner 区块中。
  • 内部转账的 workflowId 已修正。 使用相同 Idempotency-Key 重复提交时， 返回的 workflowId 曾带有 PIX out 前缀；现在返回该操作的真实 id （internal-out-…）。
  • TED 不再永远停留在 PROCESSING。 清算机构的最终结果其实已经送达，但被 投递到了错误的流程而丢失，TED 记录也从未更新。因此 GET /transfers/ted/{tedId} 和对账单即便在 TED 已完成或被拒绝时仍显示 "处理中"，而被拒绝的 TED 要等 48 小时后才以 ted.out.failed 出现，且原因是 笼统的超时而非真实的拒绝。现在结果一到就立即写入，此前卡住的 TED 也已按真实 状态完成对账。
  • TED：bankCode 仅接受 3 位 Compe 代码。 在该字段中发送 8 位 ISPB 现在会 立即以 400 invalid_bank_code 被拒绝。此前请求会以 202 被接受，到达清算机构 时却没有目标银行，TED 会一直卡在 PROCESSING — 既不完成也不失败。ISPB 在按 银行账户发起的 PIX（bankIspb）中仍然有效。
内部转账没有失败 webhook

transfer.internal.out webhook 仅在转账完成时发送。被拒绝时，结果就在该次调用 的响应里——这正是上述 422 的意义。不要等 webhook 来结清被拒绝的内部转账。

v2.41.0 (2026-07-29) - 支持已收 PIX 的部分退款​

  • 现已支持部分退款。 POST /v1/accounts/{accountId}/pix/out/refund 现在接受 小于原始 PIX 金额的 amount；此前仅接受全额，任何更小的金额都会以 400 partial_refund_not_supported 被拒绝。超过原始金额时仍返回 400 refund_amount_exceeded。
  • 同一笔 PIX 可以分多次退款，累计不超过原始金额。每次退款都需要各自的 Idempotency-Key 和 identifier：重复使用其中任意一个，API 会返回上一次退款 的结果，而不会发起新的退款。可退余额由清算合作方掌握 —— 超出部分会以 refund_amount_exceeded 返回。要查询已退金额，请查看账单：退款条目会引用原始 交易的 E2E。
  • partial_refund_not_supported 不再返回。 为了不影响已处理该错误码的集成， 文档中仍保留该代码，但任何响应都不再使用它。
  • 退款的 timeline 更完整。 退款的 pix_out.requested 事件新增两个可选字段： originalAmount（被退款的原始 PIX 金额）与 partialRefund（部分退款时为 true）。
  • mode: "REFUND" 仅在专用路由可用。 POST /v1/accounts/{accountId}/pix/out 及其 async 版本在 body 中收到该模式时改为返回 400 invalid_field —— 退款需要 只有 /pix/out/refund 才能解析的上下文。依赖此行为的流程请改用专用路由。

v2.40.0 (2026-07-29) - 面板中的所有规则均已生效​

  • 收到的 PIX 开始被校验。 面板的 PIX In 板块获得了引擎：付款方 CPF/CNPJ 白名单与 黑名单、同一持有人、金额上限、主体类型，以及允许/禁止的银行。收到的 PIX 无法被拒绝 —— 清算机构先入账，之后才通知我们 —— 因此校验发生在入账之后，有两种动作： ALLOW_AND_NOTIFY（默认：入账并告警）与 AUTO_REFUND（入账、告警并自动全额退回）。 两种情况下 pix.in.completed 仍会投递，且早于违规告警。
  • QR Code 创建开始遵守策略。 canCreateStatic、canCreateDynamic、minAmount 与 maxAmount 现在会在 POST 响应中以 422 policy_denied 拒绝创建。无金额的静态 QR（开放式，由付款方自行选择金额）不受金额上限校验，因为没有可比较的金额。
  • PIX 密钥创建开始遵守策略。 canCreate 与 maxKeys 会以 422 policy_denied 拒绝创建。该上限统计账户已有的密钥数量；若当时无法完成统计，创建照常进行 —— 查询失败 不会变成拒绝。
  • 退款开始遵守策略。 退款板块的 enabled 与 maxAmount 会以 422 policy_denied 拒绝由 API 在 POST /pix/out/refund 发起的退回。 监管退款（MED）不受影响。
  • policy.violation 覆盖所有领域。 phase 新增 pix_in，action 新增 ALLOW_AND_NOTIFY 与 AUTO_REFUND。收到的 PIX 违规时，载荷以 transactionId、 endToEnd 与 refunded 取代 paymentId，付款方置于 counterparty。新板块的规则 带前缀（pixIn.*、qrCode.*、keys.*、refund.*）；PIX out 规则仍无前缀。
  • 从未能落实的动作已从面板移除。 PIX In 不再提供 BLOCK 与 QUARANTINE（隔离 天数字段也已移除）：已入账的资金无法被冻结。含这些动作的既有配置现按 ALLOW_AND_NOTIFY 处理 —— 即告警，而不是承诺拦截。
  • 无效字段与板块已移除。 PIX Out 的 requireApprovalAbove、chunkSize、 duplicateGuardSecs 与 syncRateLimitPerMin 已从面板与文档中移除，MED 与 IP 白名单板块亦然 —— IP 管控位于您账户的网络配置中，而非此处。因此， 策略与规则指南中的“未生效的板块”部分不再存在：面板提供的 一切都会被执行。

v2.39.0 (2026-07-29) - 清算机构错误不再笼统​

  • 清算机构的拒绝现在有专属错误码。 此前，合作银行的任何失败在同步调用中都返回 partner_error（502），4xx 情况则返回 invalid_payload，无法说明该修正什么。现在 原因直接体现在 errorCode 中：limit_exceeded_daily、limit_exceeded_nightly、 limit_exceeded_monthly、limit_exceeded_transaction、pix_key_limit_exceeded、 recipient_account_not_found、identifier_conflict、balance_reservation_failed、 boleto_already_settled、boleto_scheduled、boleto_amount_mismatch、qr_gone、 qr_amount_mismatch、invalid_field、key_ownership_mismatch、 partner_account_disabled 等。完整列表见错误处理， 该表由代码中的错误目录生成。
  • 响应与 webhook 新增 partner 区块。 除我们的错误码与消息外，响应还包含清算机构 原始的 partner.code、partner.message 与 partner.field，便于自行排查而无需提交 工单。失败类 webhook 中位于 data.partner。它仅供参考：请继续以 errorCode 判断。
  • 限额相关的 HTTP 状态码变更。 超限此前透传清算机构的 403，很多客户会误读为鉴权 失败；现在返回 422。QR 码被移除此前为 410，现在为 409。清算机构的 5xx 仍为 502。
  • 可操作的消息取代原始消息。 webhook 与交易详情中的 errorReason 现在返回我们的 消息——在清算机构提供时包含剩余限额与字段名——而不是合作方的原文。
  • 开户失败原因更明确。 accreditation.failed 与 GET /v1/accreditations/{id} 现在 区分 partner_validation_failed（消息中包含被拒字段）、partner_unavailable （临时问题，可重新提交）与 existing_partner_account，不再统一归为笼统的拒绝。
  • 在 POST 阶段校验清算机构的已知限制。 address.number 超过 10 个字符、 address.cityIbgeCode 与 address.state 不一致、description 超过 140 字符、 分行号超过 4 位，现在会立即以 400 invalid_field 拒绝，而不是在清算机构侧失败—— 也不会在生物识别之后才让开户流程作废。
  • 修正已发布的错误目录。 文档中列出但 API 从未返回的错误码 （pix_limit_exceeded、pix_qr_expired、pix_qr_not_found、pix_qr_already_paid、 pix_qr_cancelled、pix_key_not_found、pix_key_already_exists、 insufficient_balance、invalid_key_type、invalid_emv、refund_not_allowed、 med_*、missing_idempotency_key、invalid_signature、authz_error）已删除。 清算机构余额不足为 insufficient_funds；DICT 中不存在的密钥为 key_not_found。

v2.38.0 (2026-07-28) - PIX out 规则正式生效，并通过 webhook 告警​

  • 面板中配置的 PIX out 规则开始生效。 kill switch、白名单、黑名单、同一持有人、 营业时间、单笔限额、夜间限额以及收款方类型（PF/PJ）现在会拒绝违反规则的转账。 未配置任何规则的用户不受影响：规则在保存的那一刻开始生效。
  • 新增 422 policy_denied 错误。 拒绝在 POST 响应中返回，violations 列出所有 被违反的规则，每条包含 rule 与 message。它既不是 403 也不是 400：请求本身合法， 只是被租户自己配置的规则拒绝。
  • 依赖收款方的规则在解析收款方之后评估。 在密钥与二维码模式下，只有在 DICT 查询 或 BR Code 解码之后才知道收款方文件号。此类情况下付款在 POST 时被接受，最终以 FAILED 结束且 errorCode: policy_denied，并在时间线与 webhook 中产生 pix.out.failed。
  • 新增 webhook 事件 policy.violation。 每次违规都会发送，包含 phase （edge、counterparty 或 dict_lookup）、action、blocked、amount、 被违反的规则，以及已知的交易对手信息。因限额被拒的 PIX 密钥查询（此前仅返回 429） 也会触发该事件。已订阅该事件的用户无需修改订阅即可开始接收。
  • 监控模式（NOTIFY_ONLY）。 PIX Out 板块新增 violationAction 字段：设为 NOTIFY_ONLY 时，违规会被记录并通过 webhook 通报，但付款照常进行。这是将规则改为 BLOCK 之前推荐的演练方式。
  • 关于生效范围的诚实说明。 策略与规则 指南现在区分了引擎 真正评估的规则与仅保存在配置中的板块（PIX in 及其动作、二维码、密钥、退款、MED、 IP 白名单）。我们也更正了“违规会出现在对账单中”的说法：被拒绝的 PIX out 从未到达 合作银行，因此不会出现在对账单里。

v2.37.3 (2026-07-28) - 修复：不带金额的二维码 PIX 付款​

  • 不带 amount 的二维码付款恢复正常。 当 BR Code 本身已包含金额时，付款 请求可以省略 amount。此前这类付款不会被执行，交易会一直停留在待处理状态， 且永远不会产生最终结果。现在系统会使用 BR Code 中的金额，付款正常完成。
  • 每笔交易都会有最终结果。 在请求送达清算行之前发生的失败，既不会触发 pix.out.failed，也不会写入时间线，交易因此无限期处于待处理状态。现在这类 情况会以 pix.out.failed 结束，并在 webhook 和时间线中同时提供 errorCode 与 errorReason。
  • 对于这类二维码付款，webhook 和时间线中发布的 amount 为 BR Code 实际收取的 金额。

v2.37.2 (2026-07-28) - 修复：ted.in.received 恢复投递​

  • 收到 TED 重新触发 webhook。 自 7 月 22 日起，清算行改用一种只在 Flow 字段中标明方向的格式发送 TED 通知，导致所有收款 TED 都被识别为付款 TED 的状态更新。结果是没有任何 ted.in.received 被派发，该笔入账也不会出现在 API 对账单中（余额与清算行对账单一直是正确的）。
  • 现在按清算行提供的方向对事件分类，并正常投递给订阅 ted.in.received 的租户。
  • 7 月 22 日至 28 日之间收到的 TED 已重新处理：webhook 携带原始 payload 和入账 时间（receivedAt）。

v2.37.1 (2026-07-26) - 自动携带改为按需开通​

  • 2.37.0 上线的持有人授权流程（PENDING_CONSENT + consentLink）现改为 按租户开通，需签订专门合同，且默认不开通。该能力会转移一个已有账户中 资金的控制权，因此不再对所有开户集成方自动生效。
  • 未开通时，POST /v1/accreditations/pf 传入已有账户的 CPF 会恢复此前的 行为：accreditation 以 FAILED 结束，errorReason=existing_partner_account， 并提示持有人向支持团队申请携带，由支持团队办理。
  • 已开通携带的租户不受影响。
  • 如需开通，请联系您的 CorpX 商务对接人。

v2.37.0 (2026-07-25) - 已有账户的 CPF 开户（由账户持有人授权）​

  • 使用已是账户持有人的 CPF 调用 POST /v1/accreditations/pf 不再返回 existing_partner_account 失败。accreditation 以 PENDING_CONSENT 创建，响应中包含 persons[].consentLink：账户持有人本人在该页面 授权您的 tenant 操作其已有账户。
  • 页面上，持有人先看到授权范围（包括动账与提现），然后完成 身份验证（活体自拍，按 CPF 与官方数据库核验），之后才会看到 账号与当前余额，再进行授权。授权记录包含日期、时间、设备以及 当时披露的余额。
  • 授权完成后，您会收到带 sharedAccount: true 的 accreditation.active 以及可用于操作的 accountId。这是同一个 账户：余额、对账单与 Pix 密钥都是原有的。
  • 共享账户： 原先操作该账户的一方继续保留权限。持有人授权的所有 tenant 都会收到每笔动账的 webhooks；非经您 API 发起的操作会带 external: true。
  • 新增事件：accreditation.consent.link.created（已生成授权链接）与 account.shared_access.granted（另一个 tenant 开始操作您已在操作的 账户）。
  • accreditation.failed 新增 errorReason：consent_declined、 consent_expired、consent_identity_failed、consent_link_failed。
  • POST /v1/accreditations/{id}/cancel 与 POST /v1/accreditations/{id}/persons/{cpf}/retry 现支持 PENDING_CONSENT（取消流程／重新签发链接）。
  • 持有人可通过支持撤销已授予的权限；撤销后，被撤销 tenant 对该账户的 调用返回 403。
  • 详见 已有账户的持有人。

v2.36.1 (2026-07-25) - accreditation 移除 pixLimits​

  • POST /v1/accreditations/pf 与 POST /v1/accreditations/pj 不再接受 pixLimits 字段。
  • 开户时 PIX 限额自动使用保守默认值。
  • 任何限额变更（上调或下调）仍需向支持人工申请。

v2.36.0 (2026-07-25) - PIX 限额变更 API 已停用​

  • PIX 限额下调 API 已停用 （PATCH /v1/accounts/{accountId}/pix/limits）。
  • 即日起，所有限额变更（上调与下调）均需向支持人工申请。
  • GET /v1/accounts/{accountId}/pix/limits 仍可用于查询。

v2.35.0 (2026-07-23) - MED（争议）webhooks 已恢复​

  • pix.med.opened 和 pix.med.updated webhooks 已恢复发送：当针对 贷记到您账户的 PIX 发起争议（MED）以及争议状态变更时，您会收到通知。
  • 载荷包含 medId、originalEndToEnd（争议中的 PIX）、amount、 reasonCode 和 status（OPEN、PENDING_DECISION、ACCEPTED、 REJECTED、CANCELED）。参见 Webhooks。
  • 在 Integrator Portal 中，pix.med.opened / pix.med.updated 不再 显示为"即将推出"，现可订阅。
  • 通过 API 抗辩（GET /pix/med、answer、decide、evidence/*） 仍暂时返回 503 —— 仅通知已恢复。

v2.34.3 (2026-07-23) - 无 fee-* 前缀的 CorpX 手续费入账​

  • 即使 identifier 未使用 fee-* 前缀（清算行仅提供操作 UUID）， 流水中的 CorpX 内部手续费转账仍会分类为 FEE。流水中的手续费 筛选与展示保持一致。

v2.34.2 (2026-07-23) - TED webhook 可靠送达​

  • 当账户收到 TED，或您发出的 TED 被清算/拒绝时，ted.in.received、 ted.out.confirmed、ted.out.failed 现可可靠送达。
  • 在 ted.in.received 中，若清算行提供信息，会填充 data.payer （姓名、证件、银行、支行、账户）。
  • 在 ted.out.failed 中，若清算行提供拒绝原因，会填充 data.errorReason。

v2.34.1 (2026-07-23) - 外部 pix.refund.completed 补齐 payer/payee​

  • 在 API 外发起的退款（data.external: true）的 pix.refund.completed / pix.refund.failed webhook 现已包含 data.payer 与 data.payee（姓名、证件、银行、支行、账户）， 与文档约定及 pix.out.* 载荷一致。
  • 若可得，也会填充 data.identifier。

v2.34.0 (2026-07-23) - PJ accreditation 公司文件​

  • POST /v1/accreditations/pj 支持 company.legalForm （mei | ltda | sa | cooperative；默认 ltda）。
  • 新接口 POST /v1/accreditations/{id}/documents：通过预签名 URL 上传 PDF，kinds 包括 company_articles、company_proof_of_address、 cnpj_card、financial_statements、business_license、 regulatory_license、other。
  • 全部生物识别通过后进入 PENDING_REVIEW。必填 PDF 取决于 legalForm（MEI/LTDA：articles + proof_of_address；SA/cooperative： 另需 cnpj_card + financial_statements）；文件时效由运营审核。
  • 缺少必填文件时 approve 返回 409 documents_incomplete；除非 forceIncompleteDocuments=true 且提供 reason（记录为 documentsOverride*）。
  • PJ 的 GET 返回 legalForm、documents、requiredDocumentKinds、 missingDocumentKinds。
  • cooperative 时 partners[] 为法定董事（文档已说明）。

v2.33.2 (2026-07-21) - 按证件号内部转账的目标歧义保护​

  • POST /v1/accounts/{accountId}/transfers/internal/by-document：当目标 证件号（CPF/CNPJ）存在多个激活账户时，请求将被拒绝并返回 409 multiple_destination_accounts，不再自动选择账户进行转账。请改用 /transfers/internal/by-bank-account（分行号 + 账号）或 /transfers/internal（destinationAccountId）指定目标。

v2.33.1 (2026-07-21) - BYO 确认链接 + accreditation Webhook​

  • BYO 流程下 accreditation 的 GET/POST 现返回 persons[].acceptanceLink（条款确认页 URL），以及 linkExpiresAt / acceptanceStatus。
  • accreditation 事件现出现在 GET /v1/webhooks/events 与门户 （Settings → Webhooks）：accreditation.pf.created、 accreditation.pj.created、accreditation.biometry.link.created、 accreditation.acceptance.link.created、accreditation.updated、 accreditation.active、accreditation.failed。
  • accreditation.pf.created / accreditation.pj.created 现于创建时 实际发出（POST 的异步确认）。

v2.33.0 (2026-07-21) - 取消 accreditation + 文档明确不去重​

  • 新接口 POST /v1/accreditations/{accreditationId}/cancel： 取消仍处于 PENDING_BIOMETRY 的 accreditation（证件号绑定租户之前）。 结果为 FAILED，errorReason=cancelled。
  • 文档/OpenAPI/Postman 明确说明 POST /v1/accreditations/pf|pj 不会去重：待处理期间重复同一证件号会创建新的 accreditation（201）； 生物识别后，已被 claim 的证件号返回 409 already_accredited。

v2.32.0 (2026-07-19) - 弃用同步 PIX out 二维码​

  • POST /v1/accounts/{accountId}/pix/out/qr-code（同步）及别名 /pix/out/qrcode 现返回 Deprecation、Sunset 和 Link 头 （后继：/pix/out/qr-code/async；计划 sunset 2026-11-21）。
  • EMV（复制粘贴）付款的规范路径为 POST .../pix/out/qr-code/async（202 + Webhook）。
  • 文档、OpenAPI 与 Postman 已优先展示异步端点。

v2.31.0 (2026-07-19) - 异步 PIX out 二维码（复制粘贴）​

  • 新接口 POST /v1/accounts/{accountId}/pix/out/qr-code/async： 安排 EMV（复制粘贴）付款并立即返回 202，与按密钥的异步 PIX out （/pix/out/async）模式一致。
  • 最终结果通过 Webhook（pix.out.completed、pix.out.failed、 pix.out.timeout）送达，或按 identifier 查询。
  • 同步接口 POST .../pix/out/qr-code 仍可用，行为不变。

v2.30.0 (2026-07-18) - 开户：CPF/CNPJ 仅在生物识别确认后绑定租户​

  • 在状态为 PENDING_BIOMETRY 时，POST /v1/accreditations/pf|pj 不再 创建账户，也不再预留证件号。
  • accountId 仅在生物识别/确认通过后出现（自 BIOMETRY_APPROVED 起）。
  • 在确认之前使用同一 CPF/CNPJ 重复 POST 会创建新的 accreditation （不会返回待处理的那条）。绑定之后返回 409 already_accredited。
  • 当证件号在清算方已有账户时，accreditation 失败并返回 errorReason=existing_partner_account，提示持有人通过支持请求将账户 控制权转移到您的租户。
  • POST /v1/accreditations/pf|pj 现要求提供 address.neighborhood （或 district）。

v2.29.2 (2026-07-15) - PIX out：通信超时不再发送 pix.out.failed​

  • 修复假阴性问题：当向银行合作方发送支付调用发生通信超时（未收到 HTTP 响应）时，API 会将订单标记为 FAILED 并发送 pix.out.failed —— 即使该笔支付可能已被处理并在 SPI 完成清算。随后可能收到迟到的 pix.out.completed，导致两个相互矛盾的终态事件。
  • 现在不确定的结果会进入确认窗口（轮询/合作方 Webhook）：如果支付成功， 仅发送 pix.out.completed；如果被拒绝，发送带真实原因的 pix.out.failed；5 分钟内无确认则发送 pix.out.timeout。
  • 文档中强化了契约语义：pix.out.failed 是终态且最终的（之后不会 再收到 completed）；不确定情况始终使用 pix.out.timeout。

v2.28.2 (2026-07-10) - pix.out.timeout Webhook​

  • 处于 TIMEOUT 的 PIX out 现在会发出出站 Webhook pix.out.timeout （此前仅写入时间线；fanout 会跳过 TIMEOUT）。
  • 确定性 EventID pix-out-timeout-{paymentId} — 不会与迟到的 pix.out.completed/failed 冲突。
  • Backoffice：可在 Webhook 配置中订阅 pix.out.timeout。
  • 文档（cashout / webhooks 中/英/葡）已对齐。

v2.28.1 (2026-07-10) - PIX 退款：仅支持全额​

  • POST /v1/accounts/{accountId}/pix/out/refund 现在会在调用清算方之前 拒绝部分退款。当前合作方的退款接口不接受金额字段，始终冲正整笔 PIX —— 更小的 amount 会静默导致全额退款。
  • 若 amount < 原始金额 → 400 partial_refund_not_supported。
  • 若 amount > 原始金额 → 400 refund_amount_exceeded。
  • amount 仍为必填，且必须等于原始 PIX 金额。
  • 文档（退款指南、OpenAPI、错误码）已更新。

v2.27.0 (2026-07-08) - 只读 API 凭证​

  • API 凭证现在可以拥有受限范围。只读凭证（api2/read）只能调用查询 端点（GET）；任何写操作（POST/PUT/PATCH/DELETE）都会返回 403 insufficient_scope。
  • 租户管理员可以在后台面板（API Credentials）中自助创建只读凭证。具备 写权限的凭证仍由 CorpX 在租户开通时提供。
  • 现有凭证不变：仍为 api2/read api2/write。
  • 注意：缺少令牌仍返回 401；无效/过期令牌现在返回 403（此前为 401）。 参见身份验证指南。

v2.26.0 (2026-07-08) - 开户功能按租户启用​

  • 开户端点（POST /v1/accreditations/pf|pj）现在要求您的租户已启用 accreditation（BaaS） 功能。未启用时 API 返回 403 feature_disabled。GET 查询不受影响。
  • 如需为您的租户启用开户功能，请联系 CorpX 团队。

v2.25.0 (2026-07-08) - 自助开户与人脸生物识别​

新增 accreditation（开户申请） 端点，可直接通过 API 开立个人 （PF）和企业（PJ）账户，并集成人脸生物识别。仅面向 BaaS 集成商 —— 详见文档新增的开户流程章节。

  • POST /v1/accreditations/pf —— 开立个人账户。默认流程中， CorpX 为账户持有人生成人脸采集链接（Unico）；生物识别通过后账户 自动开立。
  • POST /v1/accreditations/pj —— 开立企业账户。每位股东都会收到 各自的人脸采集链接；所有股东完成采集且 CorpX 审核通过后 （PENDING_REVIEW 阶段，企业开户必经）账户才会开立。
  • 自带生物识别（BYO） —— 已开通的租户可以提交在自有平台 （Unico、SERPRO、IDWALL、SUMSUB、ClearSale、CAF 或 Valid）采集的 人脸数据：先通过 POST /v1/accreditations/biometry-evidence 登记 证据文件，再在 biometry 对象中引用 evidenceId。账户持有人将在 带有您租户品牌的确认页面上完成确认。
  • 进度跟踪 —— GET /v1/accreditations/pf|pj（支持 document/status 过滤）、GET /v1/accreditations/{id}，以及按人 重发链接（POST .../persons/{cpf}/retry）。
  • 新增 webhook —— accreditation.updated（每次状态变更触发）、 accreditation.biometry.link.created、 accreditation.acceptance.link.created、accreditation.active 和 accreditation.failed。详见开户 Webhook。
  • 创建操作按租户 + 证件号幂等：使用相同 CPF/CNPJ 重复 POST 会返回既有的申请记录（200）。
  • OpenAPI 规范与 Postman Collection 已同步新增端点。

v2.24.2 (2026-07-07) - Webhook 与二维码查询中的付款方/收款方数据​

向后兼容的载荷增强——未删除任何字段，URL 未变。

  • pix.out.completed / pix.out.failed / pix.refund.* webhook： 通过 API 发起的 PIX（密钥、二维码、银行数据全部模式）的载荷现在 包含 payer（您的账户）和 payee（收款方，含已解析的姓名和 证件号）对象。此前这些对象仅出现在 API 之外发起的交易中。
  • 二维码查询（GET /v1/accounts/{accountId}/pix/qr-code 及 /lookup 别名）：当二维码状态为 PAID 时，响应现在会按文档 说明返回包含付款方姓名和证件号的 payer 对象。此前即使二维码 已支付该字段也可能缺失。
  • 无需任何操作：已解析 payer/payee 的集成将开始收到填充后的 数据；现有字段没有变化。

v2.24.1 (2026-07-07) - 对账单：未结算交易的独立状态​

对账的重要变更。 对账单现在也会包含已取消和分析中的交易， 并带有每条记录的独立状态。

  • 对账单按行显示状态。 GET /v1/accounts/{accountId}/statement、 GET /v1/accounts/{accountId}/pix/transactions 以及 CSV/PDF 导出 反映每条记录的状态：COMPLETED（已结算）、PROCESSING （已登记、未结算）、PENDING_APPROVAL（分析中）和 FAILED （已取消——未发生余额变动）。
  • 建议操作： 如果您的对账逻辑对账单行求和，请按 status = COMPLETED 过滤（退款另加 REVERSED）。FAILED 和 PROCESSING 行不应计入余额计算。
  • 状态词汇表与既有文档一致——没有新增字段。

v2.24.0 (2026-07-07) - PIX 转出：即时拒绝与风控分析​

PIX 转出流程的行为性、向后兼容变更——未新增或删除任何字段，URL 均未改变。

  • 同步流程拒绝更快。 当清算行立即拒绝转账（反欺诈或清算余额不足）时， POST /v1/accounts/{accountId}/pix/out 现在会立即返回 422 FAILED， 并填充 errorCode（partner_rejected 或 insufficient_funds）和 errorReason——此前会返回 202 PENDING，失败信息只能稍后通过 Webhook 或查询获知。
  • 风控分析以 PENDING_APPROVAL 呈现。 被风控团队拦截分析的转账， 在支付查询中现在显示为 PENDING_APPROVAL 状态（此前显示为 PROCESSING）。最终结果仍通过 pix.out.completed / pix.out.failed Webhook 送达。
  • 分析期间确认窗口延长。 处于 PENDING_APPROVAL 的支付最长等待 约 30 分钟才会标记为 TIMEOUT（此前为 5 分钟）——减少因确认 延迟到达而产生的误报 TIMEOUT。
  • TIMEOUT 情况下的 endToEndId。 在清算行没有任何确认的罕见 TIMEOUT 场景中，支付查询可能没有 endToEndId。请保存 identifier/paymentId 用于对账——它们始终存在。

v2.22.0 (2026-07-02) - TED 获得独立的规范路径​

纯增量、向后兼容的重组 —— 不会破坏任何现有集成。

  • TED 状态查询的新规范路径： GET /v1/accounts/{accountId}/ted/{tedId}。 旧路径 GET /v1/accounts/{accountId}/transfers/ted/{tedId} 仍可使用（响应完全相同）， 但已标记为 deprecated，将在下一个主版本中移除。
  • Swagger 和 Postman 已重组： TED 端点（POST /ted/out 与状态查询）现位于独立的 TED 分组，与内部转账分开。原来的 Transfers 分组更名为 Internal Transfers，仅包含 POST /transfers/internal* 与 GET /transfers/internal/lookup/*。

建议迁移：使用 GET /transfers/ted/{tedId} 查询状态的集成方可以直接改为 GET /ted/{tedId} ——响应负载完全一致。

v2.21.0 (2026-07-01) - Boleto ID 规范化​

Boleto 支付现在暴露一个统一的规范 ID，与其他通道（PIX、TED）保持一致。 本次变更为增量且向后兼容，未删除任何字段。

  • 各处均返回 paymentId。 POST /v1/accounts/{accountId}/boleto/pay 与状态 查询 GET /v1/accounts/{accountId}/boleto/payments/{id} 现在返回 paymentId（bol_<uuid>）——与 boleto.paid / boleto.failed Webhook 中 已下发的值完全相同（作为 paymentId 和 transactionId）。boletoId 字段作为别名保留（值相同）。
  • 状态查询接受两种 ID。 状态查询路径现在既接受规范的 paymentId （bol_…），也接受 partnerId（operationReferenceId，旧版），并在响应中 同时回显两者。集成方不再需要维护 paymentId ↔ partnerId 映射。

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）：保留。

支持​

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