> ## Documentation Index > Fetch the complete documentation index at: https://developers.uqpay.com/llms.txt > Use this file to discover all available pages before exploring further. # 更新日志 > UQPAY 各产品的 API 与文档更新。 # UQPAY 系统升级及 Webhook 出口 IP 新增通知 尊敬的客户： 您好！ UQPAY 计划于北京时间本周六晚间对生产环境进行系统升级。升级期间，部分服务将暂时不可用或出现短暂异常，请提前做好业务安排。 ## 维护时间 * 开始时间：2026 年 7 月 25 日（星期六）22:00 UTC+8（2026 年 7 月 25 日 14:00 UTC） * 预计结束时间：2026 年 7 月 26 日（星期日）01:00 UTC+8（2026 年 7 月 25 日 17:00 UTC） * 预计持续时间：3 小时 ## 业务影响范围 ### Acquiring Acquiring 的所有业务功能均不受本次升级影响，可正常使用。 ### Banking 维护期间，入金到账处理保持运行；除入金外的所有业务功能将暂时无法使用。为降低风险，建议您尽量避开维护窗口安排入金。 ### Issuing Issuing 的所有业务功能均不受本次升级影响，可正常使用，持卡人的卡片交易也可正常进行。 ### Ramp 维护期间，入金到账处理保持运行；除入金外的所有业务功能将暂时无法使用。为降低风险，建议您尽量避开维护窗口安排入金。 ### Ramp Transfer 永久调整（升级完成后生效） 本次升级完成后，`POST /v1/ramp/transfer` 接口的适用范围将进行以下长期调整： * 不再支持 Banking 与 Ramp 账户之间的法币互转； * 仅保留从 Ramp 向 Issuing 转移 XUSD 的能力。 资金兑换为法币后可直接发起出款，无需再通过该接口转移至 Banking。请注意，维护窗口内 Ramp 出款功能暂时不可用，需待维护完成后再发起。 请受影响客户提前检查并调整现有调用流程。 ## Access Token 说明 在维护窗口内的系统切换过程中，用于调用 Acquiring 和 Issuing API 的现有 `x-auth-token` 将在某一时点失效，即使该 Token 尚未到期。您无需提前更换 Token；如在维护窗口内收到 Token 失效或鉴权失败响应，请： 1. 重新调用 Request Access Token 接口获取新的 Token； 2. 使用新 Token 重试原请求。 重新获取 Token 仅用于处理 Acquiring 和 Issuing API 的 Token 失效或鉴权失败，不会恢复维护期间暂时不可用的 Banking 和 Ramp 功能。 ## 其他集成配置 除本文明确说明的 Webhook 出口 IP 新增及 Ramp Transfer 调整外，以下配置均保持不变： * API Base URL； * API Key 和 Client ID； * 已配置的 Webhook endpoint。 ## Webhook 出口 IP 新增——需要客户操作 本次系统升级将新增以下 Webhook 出口 IP： ```text theme={null} 56.10.39.6 ``` 如贵司对 Webhook 来源 IP 配置了防火墙或安全白名单，请在维护开始前将该 IP 加入白名单。 升级后的 Webhook 出口 IP 完整列表如下： ```text theme={null} 18.143.59.64 54.179.248.205 13.250.234.88 18.136.58.213 56.10.39.6 ``` 请在现有配置基础上新增 `56.10.39.6`，并保留全部现有 IP，无需移除任何旧 IP。 系统切换期间，Webhook 投递可能出现短暂中断，少量事件通知可能无法送达。Webhook 通知缺失不代表业务处理失败，最终状态请以查询接口返回结果为准。为确保贵司本地记录完整，请在维护结束后主动通过相关查询接口核对维护窗口内的关键业务状态，并完成一次业务对账。如发现记录不一致，请及时联系 UQPAY 客户支持团队。 详情及后续更新：[https://developers.uqpay.com/zh/changelog#2026-07-25-upcoming-change](https://developers.uqpay.com/zh/changelog#2026-07-25-upcoming-change) 感谢您的理解与支持。如在升级期间遇到紧急问题，请及时联系 UQPAY 客户支持团队，我们将协助您处理。 UQPAY CST TEAM 2026 年 7 月 21 日 ## Global Account **\[BREAKING] 受益人地址校验现适用于所有币种和支付方式** * 受影响接口：[Create Beneficiary](/zh/global-account/v1.6/api-reference/create-beneficiary)、[Update Beneficiary](/zh/global-account/v1.6/api-reference/update-beneficiary)，以及请求中提交完整 `beneficiary` 信息而非 `beneficiary_id` 的 [Create Payout](/zh/global-account/v1.6/api-reference/create-payout)。 * 受影响请求字段：`address.street_address`、`address.city`、`address.state`。Create Payout 使用内联受益人信息时，对应字段为 `beneficiary.address.street_address`、`beneficiary.address.city`、`beneficiary.address.state`。 * 2026-07-16 生效。这些字段的非空值必须匹配正则 `^[A-Za-z0-9\s\-_().,:@#~!$%^&*+={}\[\]\\|"'<>?/・……]+$`。该正则允许英文字母、数字、空白字符，以及以下符号：`_ - ( ) . , : @ # ~ ! $ % ^ & * + = { } [ ] \ | " ' < > ? / ・ ……`。 * 空字符串和未传字段会跳过字符正则校验；该字段是否必填，仍由对应接口和 payout 场景已有的必填规则决定。 * 本次将校验范围从此前的 SGD/SG 特定场景扩大到所有币种和支付方式。`country`、`postal_code` 以及非 SGD/SG 场景下的 `bank_details.account_holder` 校验不变。[Check Beneficiary](/zh/global-account/v1.6/api-reference/check-beneficiary) 不受影响。 ## Card Issuance **\[Postponed] \[BREAKING] 第三方 Enhanced KYC 新增必填字段 `documents`** **已暂缓。** 原定 2026-07-10 的生效日期不再适用。本次改动暂缓，届时不会在该日期生效 —— 你当前无需做任何调整。新的生效日期将在此处另行公告后再生效。 * 受影响接口：[Create Cardholder](/zh/card-issuance/v1.6/api-reference/create-cardholder)、[Update Cardholder](/zh/card-issuance/v1.6/api-reference/update-cardholder)。凡在 `ENHANCED` KYC 等级提交 `kyc_verification` 处均适用。 * 当 `kyc_verification.method` 为 `THIRD_PARTY` 时，`kyc_verification.kyc_proof` 新增必填数组 `documents`，用于承载验证背后的合规报告文件。每一项引用一个通过 [Upload A File](/zh/account-center/v1.6/api-reference/upload-file) 上传的文件，并声明其 `report_type`： * `IDV` —— 仅身份验证报告。 * `AML` —— 仅反洗钱筛查报告。 * `IDV_AML` —— 一份文件同时覆盖两者。 * 必须包含一份身份验证报告 —— 单独的 `IDV` 报告或合并的 `IDV_AML` 均可；`AML` 报告为可选。报告可拆成两份文件（`IDV` 加 `AML`）分开上送，也可用一份合并文件（`IDV_AML`）上送。 * 这是一个非兼容（breaking）改动：一旦生效，`THIRD_PARTY` 请求若缺少身份验证报告会被拒绝。请在新的生效日期（将在此处另行公告）之前更新相关逻辑。 * 完整流程见 [Enhanced KYC Card Issuance](/zh/card-issuance/v1.6/guide/enhanced-kyc-card-issuance)。 ## Card Issuance **新增接口：Claim Unsolicited Refund（认领无源退款）** * 新增接口：[Claim Unsolicited Refund](/zh/card-issuance/v1.6/api-reference/claim-unsolicited-refund) —— `POST /v1/issuing/transactions/unsolicited_refund/release`。仅支持 Business Visa Card。 * 当针对原授权交易的商户退款迟迟未到账时使用。返回 `SUCCESS` 仅表示申请已受理并进入异步处理，不代表退款已入账。 * 失败原因见 [错误码](/zh/card-issuance/v1.6/guide/error-codes#transaction-errors)。 **授权决策请求新增 `pos_env` 与 `eci` 字段** * 受影响流程：[Authorization decisions](/zh/card-issuance/v1.6/guide/authorization-decisions) —— UQPAY 发送到你端点的解密后请求体。 * 新增两个透传字段，便于你区分一笔授权是常规消费还是订阅（recurring）扣费，从而做差异化风控与展示： * `pos_env` —— POS 环境：`C` credential on file、`I` 分期、`R` 周期性。 * `eci` —— 邮购/电话、电商及支付标识（`00`–`08`）；`02` 表示周期性交易。 * 向后兼容 —— 仅为新增字段。完整取值表见指南。 **List Card Arts 新增 `product_id` 筛选参数** * 受影响接口：[List Card Arts](/zh/card-issuance/v1.6/api-reference/list-card-arts)。 * 可选 query 参数 `product_id`，将返回的 card art 筛选为该卡产品可用的部分。不传则维持现状 —— 返回账户可用的全部 card art。 * 向后兼容 —— 新增的可选参数。 ## Account Center **\[BREAKING] 创建个人类型 SubAccount 时新增两个必填字段 `gender` 与 `annual_income`** * 受影响接口：[Create SubAccount](/zh/account-center/v1.6/api-reference/create-sub-account) * 2026-07-02 生效。当 `entity_type` 为 `INDIVIDUAL` 时，`individual_info` 对象新增两个必填字段： * `individual_info.gender` —— 个人性别，取值 `MALE` 或 `FEMALE`。 * `individual_info.annual_income` —— 个人年收入，以字符串金额传入，币种为 USD。 * 这是一个非兼容（breaking）改动：缺少任一字段的请求会被拒绝。请在 2026-07-02 之前及时更新相关逻辑。 * 公司类型 SubAccount（`entity_type` 为 `COMPANY`）不受影响。 **SDK 支持** 以下 SDK 版本已支持新增必填字段，请在 2026-07-02 前升级： | SDK | 最低版本 | 升级方式 | | ----------------------- | -------- | ---------------------------------------------------------------------------- | | Node.js (`@uqpay/sdk`) | `0.3.1` | `npm install @uqpay/sdk@latest` | | Python (`uqpay`) | `0.2.0` | `pip install -U uqpay` | | Go (`uqpay-sdk-go`) | `v1.1.0` | `go get github.com/uqpay/uqpay-sdk-go@latest && go mod tidy` | | Java (`uqpay-sdk-java`) | `1.1.0` | 从 [GitHub Releases](https://github.com/uqpay/uqpay-sdk-java/releases) 下载 JAR | | CLI (`@uqpay/cli`) | `0.3.1` | `npm install -g @uqpay/cli@latest` | 升级后，为 `INDIVIDUAL` 实体调用 Create SubAccount 时，设置 `individual_info.gender`（`MALE` 或 `FEMALE`）和 `individual_info.annual_income`。 Node.js / CLI：请用 `npm install @uqpay/sdk@latest`（不要用 `npm update`）——低于 `0.3.0` 的版本受 `^0.2.x` 范围锁定，不会自动升级。 ## Stablecoin Account **Binance 充值 Travel Rule 支持** * 新增接口：[Submit Deposit Sender Travel Rule](/zh/stablecoin-account/v1.6/api-reference/create-deposit-sender) —— 为到账充值提交发起方（来源方）的 Travel Rule 数据，使该笔以及后续来自相同来源地址的充值得以继续处理。 * 充值 Webhook（`ramp.deposit.pending`）新增 `need_travel_rule`，仅当该笔充值确需补填来源 Travel Rule 才能继续处理时出现且为 `true`。收到后以该笔充值的 `from_address` 调用 Submit Deposit Sender Travel Rule。 * [List Address Book](/zh/stablecoin-account/v1.6/api-reference/list-address-book) 新增可选查询参数 `address_kind`（默认 `whitelist`，或 `deposit_sender`），用于查看已补录的充值来源条目。 * 三项改动均向后兼容 —— 新增接口、新增可选参数，以及一个按需才出现的字段。 ## Account Center **\[UPDATE] 入驻 RFI Webhook 新增 `required_documents` 与 `reason` 字段** * 受影响 Webhook：[Onboarding RFI](/zh/account-center/v1.6/webhooks/onboarding-rfi) * `rfi.action_required` 通知体现在包含 `required_documents`（合规所需的证件类型代码）与 `reason`（说明本次 RFI 触发原因的自由文本）。 * 你可以直接从通知中读取所需材料，无需先调用 [Retrieve RFI](/zh/account-center/v1.6/api-reference/retrieve-rfi)。 * 向后兼容 —— 忽略新字段的既有处理逻辑维持原有行为。 ## Issuing **\[UPDATE] 收紧 `residential_address` 字段的字符校验** * 受影响接口：[Create Cardholder](/zh/card-issuance/v1.6/api-reference/create-cardholder)、[Update Cardholder](/zh/card-issuance/v1.6/api-reference/update-cardholder)、[Create Card](/zh/card-issuance/v1.6/api-reference/create-card)（通过 `cardholder_required_fields` 一步开卡） * `residential_address` 的所有字段（`line1`、`line2`、`city`、`state`、`postal_code` 等）现在仅接受大小写字母（A-Z、a-z）、数字（0-9）、空格及以下标点：`, . ' / # ( ) - &`。 * 包含其他任意字符（例如 `;`）的请求会被拒绝 —— 修正后可重新提交。空的可选字段不参与校验。 * 本次为校验收紧：此前可通过的值现在可能被拒绝。如果你在地址字段中传入上述以外的字符，请检查你的集成。 ## Issuing **\[NEW] Standard 虚拟卡 PIN 管理** * 新增接口：[Set or Reset Virtual Card PIN](/zh/card-issuance/v1.6/api-reference/manage-card-pin) * 为 Standard 虚拟卡首次设置 4 位数字 PIN（`type: SET`），或修改 PIN（`type: RESET`）。 * `RESET` 必须通过 `old_pin` 提供卡片当前 PIN —— 不支持忘记密码找回。如果当前 PIN 已丢失，无法通过 API 重置。 * 该流程为异步处理 —— 响应仅确认请求已受理，并返回 PIN 操作订单（`card_id`、`card_order_id`、`create_time`）。同一张卡同一时间只能有一笔进行中的 PIN 操作。 * 实体卡 PIN 管理不受影响 —— [Reset Card PIN](/zh/card-issuance/v1.6/api-reference/reset-pin) 维持原有行为。 ## Issuing **\[NEW] 卡面 —— 选择 Enhanced 虚拟卡在 Apple Wallet 与 Google Wallet 中展示的设计** * **适用范围：** 在 Apple Wallet 与 Google Wallet 中渲染，仅适用于已添加到 Apple Pay 或 Google Pay 的 Enhanced 虚拟卡。不会展示在你自己的 UI 或实体卡上 —— 参见新增的 [卡面指南](/zh/card-issuance/v1.6/guide/card-art) 了解解析顺序与限制。 * 新增接口：[List Card Arts](/zh/card-issuance/v1.6/api-reference/list-card-arts)、[Set Default Card Art](/zh/card-issuance/v1.6/api-reference/set-default-card-art) * 影响接口：[Create Card](/zh/card-issuance/v1.6/api-reference/create-card)、[Update Card](/zh/card-issuance/v1.6/api-reference/update-card) —— 请求体新增可选字段 `card_art_id`。 * Update Card 带 `card_art_id` 为异步操作（`order_status: PROCESSING`），仅对 `VIRTUAL` 且 `ACTIVE` 状态的卡片生效。 * 新增错误码：`card_art_not_available`、`card_art_not_configured`、`card_art_not_supported` —— 参见 [错误码](/zh/card-issuance/v1.6/guide/error-codes)。 * 向后兼容 —— 未传 `card_art_id` 的现有集成正常工作，自动使用账户默认卡面。 ## Issuing **\[UPDATE] Elevate Per-Transaction Limit 接口的 `duration_in_days` 范围扩展** * 影响接口：[Elevate Per-Transaction Limit](/zh/card-issuance/v1.6/api-reference/elevate-card-limit) * `duration_in_days` 字段现支持 `1`–`14`（此前为 `1`–`7`）；默认值由 `7` 调整为 `14`。 ## Global Acquiring **\[NEW] Create PaymentIntent 新增 `customer` 与 `customer_id` 字段** * 影响接口：[Create PaymentIntent](/zh/global-acquiring/v1.6/api-reference/create-payment-intent) * 请求体新增可选字段 `customer`（内联对象）和 `customer_id`；响应中相应新增顶层 `customer_id` 与 `customer`。 * 客户对象新增可选 `external_customer_id` 字段，便于商户携带自有客户标识。 * 这两个字段用于在托管支付页上启用 Card on File。 * 向后兼容 —— 未传这些字段的现有集成无需调整。 ## Issuing **\[NEW] 临时提升单笔交易限额** * 新增接口：[Elevate Per-Transaction Limit](/zh/card-issuance/v1.6/api-reference/elevate-card-limit) * 新增 Webhook：`card.elevate_limit.succeeded`、`card.elevate_limit.failed` * 为卡片在限定时间内临时提升单笔交易限额（1–14 天，默认 14 天），不影响卡片的长期限额设置。提额到期后，单笔交易限额自动恢复至原标准上限。 * 单笔提额上限：USD / XUSD 最高 `80,000`；SGD 最高 `100,000`。 * 同一张卡同一时间只能存在一条处理中或生效中的提额记录。提额仍在效期内再次提交，将返回 `400`。 * 提额流程为异步流程 —— API 响应仅确认请求受理，最终结果通过 [`card.elevate_limit.succeeded`](/zh/card-issuance/v1.6/webhooks/card-elevate-limit) 或 [`card.elevate_limit.failed`](/zh/card-issuance/v1.6/webhooks/card-elevate-limit) Webhook 推送。 * 仅对特定卡 BIN 开放 —— 如需启用，请联系 UQPAY。 ## Issuing **\[NEW] ASAF 网络保护（Network Protection）—— 将丢失、被盗、注销的 Visa 卡上报至卡组织网络** * 新增接口：[Enroll Card in Network Protection](/zh/card-issuance/v1.6/api-reference/enroll-card-network-protection)、[Remove Card from Network Protection](/zh/card-issuance/v1.6/api-reference/remove-card-network-protection) * 新增 Webhook：`card.risk_control.network_protection.enrolled`、`card.risk_control.network_protection.removed`、`card.risk_control.network_protection.enrollment_fee.charged`、`card.risk_control.network_protection.maintenance_fee.charged` * 影响接口：[Retrieve Card](/zh/card-issuance/v1.6/api-reference/retrieve-card)、[List Cards](/zh/card-issuance/v1.6/api-reference/list-cards) 的响应体中，每张卡新增 `network_protection` 对象。 * 使用 ASAF action code（`04`、`41`、`43`、`46`、`54`）注册卡片后，Visa 处理完成即可在卡组织网络层面统一拒绝该卡的授权请求。移除接口则将卡片重新撤出网络保护。 * 注册与移除均为异步流程 —— API 响应仅确认请求受理，最终结果通过生命周期 Webhook 推送。费用扣款通过 enrollment-fee 与 maintenance-fee 两个 Webhook 单独下发。 * **仅支持 Visa 卡。** 向后兼容 —— 未启用该功能的现有集成无需调整。 ## Issuing **\[NEW] 单卡 3DS 注册控制字段 `enable_3ds`** * 影响接口：[Create Card](/card-issuance/v1.6/api-reference/create-card)、[Update Card](/card-issuance/v1.6/api-reference/update-card)、[Retrieve Card](/card-issuance/v1.6/api-reference/retrieve-card)、[List Cards](/card-issuance/v1.6/api-reference/list-cards) * 影响 webhook：`card.create.succeeded`、`card.update.succeeded` * `risk_controls` 下新增 `enable_3ds` 字段，控制卡片是否注册 3DS。配合既有的 `allow_3ds_transactions` 完整控制 3DS 行为 —— 详见更新后的 [3D Secure 指南](/zh/card-issuance/v1.6/guide/3d-secure)。 * 仅 Visa BIN 支持。卡片在 `PENDING` 或 `ACTIVE` 状态时可修改。 * 仅在卡片显式设置过该字段时返回。未设置时，卡片继承 Account 级 3DS 配置。 * 向后兼容 —— 未传入 `enable_3ds` 的现有集成无需调整。 ## Issuing **\[BREAKING] 安全 Iframe 渲染行为变更** [安全 Iframe](/zh/card-issuance/v1.6/guide/secure-iframe-guide) 集成模式将上线一组布局与控件调整。即使你不更新任何客户端代码，已有集成的渲染效果也可能发生明显变化。建议在生产发布前先在沙盒中验证渲染效果。 * 生效时间：2026-05-07，北京时间 20:00 左右（UTC+8） * 可能影响已有集成渲染效果的变更： * **页面最大宽度**：`512px` → `1280px`。父容器宽度超过 512px 的卡片，渲染宽度会比之前更宽。 * **Iframe 内容高度**：原由内容自适应（auto） → 固定为 `300px`。超过 300px 的内容可能被裁剪或滚动展示。 * **Iframe 容器最小高度**：原无限制 → `min-height: 400px`。内容较短的容器会被撑高至 400px。 * **底部「Show / Hide data」切换按钮已移除。** 敏感数据（卡号、有效期、CVV）的显示/隐藏改为通过 `CVV` 标签旁边的眼睛图标控制，该图标常驻可见。点击被遮蔽的字段值（`****`、`**/**`、`***`）也可切换显示状态。 * 如需保留之前的固定尺寸，可通过 `styles` 参数对 `.uq-card-container` 设置 `width` / `height` —— 用法详见[安全 Iframe 集成指南](/zh/card-issuance/v1.6/guide/secure-iframe-guide)。 *** **\[NEW] 安全 Iframe 新增 `show_data` URL 参数** 在[安全 Iframe](/zh/card-issuance/v1.6/guide/secure-iframe-guide) URL 上传 `show_data=true`，可在加载时直接展示卡号、有效期与 CVV，无需用户操作。默认值：`false`。仅推荐在受信任环境下使用。 *** **\[NEW] 安全 Iframe 新增 `cardholder_name` URL 参数** 在[安全 Iframe](/zh/card-issuance/v1.6/guide/secure-iframe-guide) URL 上传 `cardholder_name=true`，可渲染持卡人姓名字段。默认值：`false`（隐藏）。向后兼容。 *** **\[ENHANCED] 安全 Iframe `styles` 新增选择器与属性** [安全 Iframe](/zh/card-issuance/v1.6/guide/secure-iframe-guide) 的 `styles` 参数现支持： * 新增选择器：`.uq-card-cardholder`（持卡人姓名样式）、`.uq-page-background`（iframe 页面背景，默认 `transparent`）。 * `.uq-card-container` 支持 `width`、`height`、`min-height`、`max-width`、`min-width` —— 可用于恢复之前的固定尺寸。 * `.uq-card-row` 支持 `display`、`justify-content`、`align-items`、`flex-direction`、`gap` —— 可用于标签/取值的对齐控制。 ## Issuing **\[NEW] 一步发卡 —— 单次调用同时创建持卡人与卡片** * 影响接口：[Create Card](/card-issuance/v1.6/api-reference/create-card)（请求与响应） * `cardholder_id` 改为可选。当不传该字段时，提供完整的 `cardholder_required_fields` 字段块，系统会在同一次请求中创建持卡人并发卡。 * 向后兼容 —— 已有集成继续传 `cardholder_id` 时行为不变。 * 完整集成流程见[一步发卡指南](/zh/card-issuance/v1.6/guide/one-step-card-issuance)。 *** **\[ENHANCED] `card.verification.otp` Webhook 现已支持 Apple Pay 绑定** * 影响 Webhook：`card.verification.otp` * 该验证 OTP 事件现同时支持 Google Pay 与 Apple Pay 钱包绑定场景。此前仅在 Google Pay 绑定时下发。 * 已有集成无需调整 —— 已订阅 `card.verification.otp` 的商户会自动收到 Apple Pay 绑定的 OTP 通知。 *** **\[NEW] 持卡人手机号校验新增支持科索沃** * 影响接口：[Create Cardholder](/card-issuance/v1.6/api-reference/create-cardholder) * 现可成功创建使用科索沃（ISO 3166-1 alpha-2 `XK`、alpha-3 `XKX`）手机号的持卡人。 * 国家代码：`+383`。手机号长度（不含国家代码）：8–9 位。 * 完整国家清单见[持卡人手机号校验规则](/zh/card-issuance/v1.6/guide/phone-number-validation-rules-for-cardholder)。 ## Issuing **\[NEW] `issuing.transfer.status_changed` Webhook** * 当发卡转账状态发生变更（例如从 `pending` 变为 `succeeded` 或 `failed`）时下发的新 Webhook 事件。 * 在 Webhook 配置中订阅 `issuing.transfer.status_changed` 即可接收该通知。 *** **\[ENHANCED] `card.status.update` Webhook 新增 `available_balance` 与 `currency` 字段** * 影响 Webhook：`card.status.update.succeeded`、`card.status.update.failed` * 新增 `available_balance` —— 卡片在状态变更时刻的当前可用余额。 * 新增 `currency` —— 卡片币种，ISO 4217 格式。 ## Acquiring **\[ENHANCED] Create Payout：新增 `payout_account_id` 字段，支持站内账户出款** 出款创建接口现支持可选的 `payout_account_id` 参数，商户可将出款资金转入 UQPAY 站内账户，而非预配置的外部银行账户。 * 影响接口：[Create Payout](/global-acquiring/v1.6/api-reference/create-payout)（请求） * 变更内容： * 请求体新增可选字段 `payout_account_id`。 * 不传时维持现有行为 —— 资金按原配置发送至外部银行账户。 * 传入时，出款将以 UQPAY 站内转账形式打到指定账户。 * 长短两种 UQPAY 账户 ID 均可接受。 * 注意事项： * `payout_account_id` 应与调用方账户层级匹配：从子账户调用时传子账户 ID；从主账户调用时传主账户 ID。 * 该变更非破坏性、向后兼容 —— 已有集成无需调整。 ## Issuing **\[ENHANCED] 持卡人 KYC 体系改造：支持多级 KYC** 持卡人的创建、更新及发卡流程现支持基于卡 BIN 要求的分级 KYC。同时新增两个 Webhook 事件用于 KYC 全生命周期跟踪。 *** **Create & Update Cardholder：多级 KYC** * 影响接口：Create Cardholder（请求与响应）、Update Cardholder（请求与响应） * 变更内容： * 现支持三级 KYC： * `SIMPLIFIED` —— 仅基础字段，行为与旧版本一致，`cardholder_status` 立即置为 `SUCCESS` * `STANDARD` —— 要求 `nationality`、`identity`、`residential_address`，触发审核流程 * `ENHANCED` —— 在 `STANDARD` 基础上额外要求 `kyc_verification`，支持 `THIRD_PARTY` 和 `SUMSUB_REDIRECT` 两种方式 * 请求新增字段：`gender`、`nationality`、`identity`（对象）、`residential_address`（对象）、`kyc_verification`（对象） * 响应新增字段：`cardholder_status`、`idv_verification_url`、`idv_url_expires_at` * 注意事项： * 不传新字段时，行为完全向后兼容。 * 当 `cardholder_status` 为 `PENDING` 时，不允许更新 KYC 相关字段。 * `residential_address` 替代之前的 `delivery_address` 字段。 *** **Retrieve Cardholder 响应：新增字段** * 影响接口：Retrieve Cardholder（响应）、List Cardholders（请求与响应） * 变更内容： * 响应新增字段：`gender`、`nationality`、`residential_address`、`cardholder_status`、`review_status`、`idv_status`、`idv_verification_url`、`idv_url_expires_at` * List Cardholders 接受新查询参数 `cardholder_status`，可按状态过滤。 *** **Create Card：补充持卡人 KYC** * 影响接口：Create Card（请求与响应） * 变更内容： * 请求新增可选对象 `cardholder_required_fields` —— 允许商户在发卡环节补充缺失的持卡人 KYC 字段（包含 `gender`、`nationality`、`phone_number`、`date_of_birth`、`residential_address`、`identity`、`kyc_verification`）。 * 响应新增字段：`cardholder_status`、`message` * 注意事项： * 当持卡人不满足产品要求且未传 `cardholder_required_fields` 时，返回 `kyc_insufficient` 错误，并附带 `missing_fields`。 * 当发卡触发 KYC 审核时，卡片进入 `PENDING` 状态，审核通过后自动激活。 *** **List Products 响应：新增 `required_fields`** * 影响接口：List Products（响应） * 变更内容： * 每个产品对象新增 `required_fields` 数组，标识该卡 BIN 要求的持卡人字段。 * 数组每项包含：`name`、`type`（`string` 或 `object`）、`required`（布尔值）、`description`、`fields`（当 type 为 `object` 时的子字段）。 *** **\[NEW] 持卡人 KYC Webhook 事件** * 新增 Webhook 事件： * `cardholder.kyc.status_changed` —— 持卡人 KYC 状态变更 * `cardholder.updated` —— 持卡人信息已更新 ## Acquiring **\[BREAKING] API 响应结构调整：卡交易新增风控与认证字段** * 影响接口（仅响应）：[Create PaymentIntent](/global-acquiring/v1.6/api-reference/create-payment-intent)、[Retrieve PaymentIntent](/global-acquiring/v1.6/api-reference/retrieve-payment-intent)、[Update PaymentIntent](/global-acquiring/v1.6/api-reference/update-payment-intent)、[Confirm PaymentIntent](/global-acquiring/v1.6/api-reference/confirm-payment-intent)、[Capture PaymentIntent](/global-acquiring/v1.6/api-reference/capture-payment-intent)、[Cancel PaymentIntent](/global-acquiring/v1.6/api-reference/cancel-payment-intent)、[List PaymentIntents](/global-acquiring/v1.6/api-reference/list-payment-intents)、[Retrieve PaymentAttempt](/global-acquiring/v1.6/api-reference/retrieve-payment-attempt)、[List PaymentAttempts](/global-acquiring/v1.6/api-reference/list-payment-attempts) * 变更内容： * PaymentIntent 接口：`latest_payment_attempt.payment_method` 类型由 `string` 改为 `object` * PaymentAttempt 接口：`payment_method` 类型由 `string` 改为 `object` * PaymentIntent —— `latest_payment_attempt` 新增字段：`auth_code`、`arn`、`rrn`、`advice_code` * PaymentAttempt —— 顶层新增字段：`auth_code`、`arn`、`rrn`、`advice_code` * PaymentIntent —— 新增对象：`latest_payment_attempt.authentication_data` * 字段：`cvv_result`、`avs_result` * `authentication_data.three_ds` 字段：`ds_transaction_id`、`three_ds_version`、`eci`、`cavv`、`three_ds_authentication_status`、`three_ds_cancellation_reason` * PaymentAttempt —— 新增对象：`authentication_data`（结构同上） * 注意事项：生效时间 2026-03-26 *** **\[NEW] PaymentAttempt Webhook：卡交易新增风控与认证字段** * 影响 Webhook：`acquiring.payment_attempt.created`、`acquiring.payment_attempt.capture_requested`、`acquiring.payment_attempt.cancelled`、`acquiring.payment_attempt.failed` * 适用范围：仅卡交易（`payment_method.type = "card"` 或 `"card_present"`） * 变更内容： * 通知体新增字段：`auth_code`、`arn`、`rrn`、`advice_code` * 新增对象：`authentication_data` * 字段：`cvv_result`、`avs_result` * `authentication_data.three_ds` 字段：`ds_transaction_id`、`three_ds_version`、`eci`、`cavv`、`three_ds_authentication_status`、`three_ds_cancellation_reason` * 注意事项：生效时间 2026-03-26 ## Card Issuing **Create Card 新增 `usage_type`、`auto_cancel_trigger` 与 `expiry_at`** 通过在 Create Card 请求体中新增三个可选字段，引入对一次性卡的支持。 * 影响接口：Create Card（请求） * 变更内容： * 新增可选字段 `usage_type`（枚举：`NORMAL`、`ONE_TIME`；默认值：`NORMAL`）。不传时，卡按标准可重复使用卡处理。 * 新增可选字段 `auto_cancel_trigger`（枚举：`ON_AUTH`、`ON_CAPTURE`）。当 `usage_type` 为 `ONE_TIME` 时必填。定义触发自动注销的交易事件：`ON_AUTH` 在首次授权通过后立即注销；`ON_CAPTURE` 在首笔交易请款（结算）成功后注销。 * 新增可选字段 `expiry_at`（带时区偏移的日期时间字符串，例如 `2026-03-19T18:46:43+08:00`）。若该时间点之前未被首笔交易事件触发注销，则到期自动注销并释放未使用的余额。 ## Banking **Create Virtual Account 新增 `X-Request-Id` 请求头** 为 Create Virtual Account 引入可选的 `X-Request-Id` 请求头，调用方可传入自定义标识，并在关联 Webhook 事件中回传。 * 影响接口：Create Virtual Account、Webhook：`virtual.account.*` * 变更内容： * 新增可选请求头 `X-Request-Id`（字符串，最长 64 字符）。 * 若传入，该值将在关联的 Webhook 事件中以 `request_id` 字段回传。 ## Account Center **Create SubAccount：`individual_info` 新增四个必填字段** `individual_info` 对象在创建个人账户时新增四个必填字段。生效日期之后，缺失任一字段的请求将返回校验错误。 * 影响接口：Create SubAccount（请求） * 变更内容： * 新增必填字段 `individual_info.employment_status` —— 个人就业状态。 * 新增必填字段 `individual_info.industry` —— 个人所在行业。 * 新增必填字段 `individual_info.job_title` —— 个人职位。 * 新增必填字段 `individual_info.company_name` —— 个人所在公司名称。 * 生效时间：2026-03-19 ## Acquiring **`billing.phone_number` 改为可选** `billing.phone_number` 字段由必填改为可选。 * 影响接口：Create PaymentIntent（请求）、Confirm PaymentIntent（请求） * `billing.phone_number` 字段不再必填。 *** **\[NEW] 新增 Google Pay 与 Apple Pay 支付方式** * 影响接口：Create PaymentIntent（请求）、Confirm PaymentIntent（请求） * 新增 `googlepay` 与 `applepay` 作为可选支付方式。 ## Banking **\[BREAKING] Create Transfer 新增必填请求头 `x-idempotency-key`** * 影响接口：Create Transfer（请求） * 新增**必填**请求头参数：`x-idempotency-key` * 该变更为破坏性变更，所有 API 调用方必须在 Create Transfer 请求中加入此请求头。 * 生效时间：3 月 19 日 ## Account Center **Create SubAccount：`proof_documents.proof_of_address` 改为可选** * 影响接口：Create SubAccount（请求） * 创建子账户时，`proof_documents.proof_of_address` 字段不再必填。 ## Issuing **\[ENHANCED] List Issuing Balances Transactions 新增过滤参数** * 影响接口：List Issuing Balances Transactions（请求） * 新增四个可选过滤参数： * `transaction_type` —— 按交易类型过滤（如授权、冲正、退款、手续费、结算） * `transaction_status` —— 按状态过滤：`COMPLETED`、`PENDING` 或 `FAILED` * `currency` —— 按 ISO 4217 三位币种代码过滤（如 `USD`、`EUR`、`GBP`） * `transaction_id` —— 按精确交易 ID 过滤 * 所有参数均为可选，可单独使用或任意组合。 ## Acquiring **\[NEW] 银行账户管理 API** 新增四个用于管理收单结算银行账户的接口： * Create Bank Account * Retrieve Bank Account * Update Bank Account * List Bank Accounts 注意事项： * 每个币种只能配置一个结算银行账户。 * 已创建的银行账户不可删除。 ## Issuing **\[NEW] 授权决策能力** 合作方现可对卡交易实现实时授权决策逻辑：通过部署 Webhook 服务接收 UQPAY 下发的授权请求即可。 ## Account Center **\[BREAKING] Create SubAccount：`business_details.industry` 启用枚举校验** * 影响接口：Create SubAccount（请求） * `business_details.industry` 字段现必须传入行业代码列表中的合法值。 * 此前仅校验非空。 * **过渡期**：2025-12-25 至 2026-01-01 期间同时接受新旧值。2026-01-01 起强制执行。 *** **\[BREAKING] `business_code` 响应类型由 string 改为数组** * 影响接口：Retrieve Account（响应）、List Connected Accounts（响应） * `business_code` 由 `string` 改为 `array[string]`。 * 示例：`"business_code": "BANKING"` → `"business_code": ["BANKING"]` * 取值范围：`BANKING`、`ACQUIRING`、`ISSUING` * 已有集成若按单字符串解析，需相应更新。 *** **\[DEPRECATED] Create SubAccount 中的 `business_type` 字段已废弃** * 影响接口：Create SubAccount（请求） * `business_type` 字段已废弃，将被移除。 ## Acquiring **\[ENHANCED] 3DS 场景下 `browser_info.mobile` 校验放宽** * 影响接口：Create PaymentIntent（请求）、Confirm PaymentIntent（请求） * `browser_info.mobile` 现仅在客户端为移动端时必填。3DS 场景下 PC web 客户端不再要求此字段。 ## Acquiring **\[ENHANCED] Payment Intent 与 Payment Attempt Webhook 新增静态二维码字段** * 影响 Webhook：`acquiring.payment_intent.*`、`acquiring.payment_attempt.*` * Webhook 通知体新增字段 `static_qrcode`、`static_qrcode_extension`、`static_qrcode_number_plate`。 * 这些字段仅在静态二维码支付场景下返回。 ## Issuing **\[ENHANCED] Update Card Status 中 `update_reason` 字段长度限制** * 影响接口：Update Card Status（请求） * 最大长度：50 个中文字符或 100 个字符。 *** **\[NEW] `card.verification.otp` Webhook** * 当卡片绑定 Google Pay 需要 OTP 验证时触发。 * 在 Webhook 配置中订阅 `card.verification.otp` 事件即可接收该通知。 ## Banking **\[ENHANCED] List Balances Transactions 支持 INVOICE 类型过滤** * 影响接口：List Balances Transactions（请求） * `transaction_type` 过滤参数新增对 `INVOICE` 类型的支持。 ## Issuing **\[ENHANCED] Retrieve Cardholder 与 List Cardholders 新增 `delivery_address` 字段** * 影响接口：Retrieve Cardholder（响应）、List Cardholders（响应） * 持卡人响应对象新增 `delivery_address` 字段，结构如下： ```json theme={null} "delivery_address": { "city": "Singapore", "country": "SG", "line1": "9 N Buona Vista Dr", "line2": "THE METROPOLIS", "state": "Singapore", "postal_code": "138666" } ``` ## Acquiring **`ip_address` 字段在 PaymentIntent 中提升至顶层** * 影响接口：Create PaymentIntent（请求）、Confirm PaymentIntent（请求） * `browser_info.ip_address` 提升至顶层（与 `payment_method` 同级）。 * 当 `payment_method.card.three_ds_action = enforce_3ds` 时，`ip_address` **必填**。 ## Acquiring **\[ENHANCED] 美国与加拿大账单地址 `state` 字段条件必填** * 影响接口：Create PaymentIntent（请求）、Confirm PaymentIntent（请求） * 当 `billing.address.country_code` 为 `"US"` 或 `"CA"` 时，`payment_method.card.billing.address.state` 现为条件必填。 *** **\[NEW] 新增 TRUEMONEY、TNG、GCASH、DANA、KAKAOPAY、TOSSPAY、NAVERPAY 支付方式** * 影响接口：Create PaymentIntent、Confirm PaymentIntent * 新增 7 种支付方式，扩大东南亚市场覆盖范围。 *** **\[NEW] 手动请款接口** * 新增接口：`POST /v2/payment_intents/{id}/capture` * 支持 `auto_capture = false` 的支付流程，请款窗口可配置 1–24 小时。 * 若窗口期内未手动请款，UQPAY 在窗口结束后自动请款。 * 商户可在请款窗口期内取消订单。 ## Banking **\[ENHANCED] 收款人 Webhook 新增 `beneficiary_entity_type` 字段** * 影响 Webhook：`beneficiary.*` * Webhook 体新增 `beneficiary_entity_type` 字段。取值：`"INDIVIDUAL"` 或 `"COMPANY"`。 ## Issuing **\[ENHANCED] 手机号校验规则更新** * 影响接口：Create Cardholder（请求） * 以下国家手机号长度校验更新（不含国家/地区/区号）： * 尼日利亚（NG）：8 或 10 位 * 孟加拉国（BD）：8 或 10 位 * 利比亚（LY）：8 或 9 位 * 塞内加尔（SN）：7 或 9 位 * 马约特（YT）：8 或 9 位 * 厄瓜多尔（EC）：7 或 9 位 * 刚果共和国区号由 2420 改为 242。 ## Account Center **\[ENHANCED] TPSP 主账户下子账户创建增强** * 影响接口：Create SubAccount（请求） * 公司类实体新增 `ownership_details.representatives.face_docs`。 * 个人类实体新增 `identity_verification.face_docs`。 * 两类实体均新增 `tos_acceptance.tos_agreement`（可选；置为 `1` 表示自动签署 TPSP 服务条款）。 * 在 TPSP 主账户下创建子账户时，`face_docs` 必填。 * 公司类实体：至少一名具备特定职位的代表人需提供人脸验证文件。 ## Acquiring **\[NEW] 账户余额与出款接口** 发布 5 个新接口： * Retrieve Balance * List Balances * Create Payout * Retrieve Payout * List Payouts —— 出款状态实时更新可通过 Webhook 接收。 ## Banking **\[ENHANCED] 公司名与账户持有人字段支持中文括号** * 影响接口：Create Payout（请求）、Create Beneficiary（请求） * `company_name` 与 `account_holder` 字段新增对中文括号 `（）` 的支持。 * 仅在 `bank_country_code = CN`、`account_currency_code = CNH`、`payment_method = LOCAL`、`entity_type = COMPANY` 场景下生效。 *** **\[ENHANCED] 本地支付校验放宽** * 影响接口：Create Payout（请求）、Create Beneficiary（请求） * 当 `payment_method = LOCAL` 且 `account_currency_code` 不为 CNH 或 SGD 时，移除对 `bank_details.account_holder`、`first_name`、`last_name`、`company_name`、`address.street_address`、`address.city`、`address.state` 的校验。 *** **\[ENHANCED] `payout_reference` 校验规则更新** * 影响接口：Create Payout（请求） * SWIFT 出款：新增模式 `/^[a-zA-Z0-9/-?:().'+, ]+$/`（支持空格及更多特殊字符）。 * LOCAL 出款且币种非 CNH/非 SGD：不做校验。 *** **\[NEW] INR 跨币种出款新增发票文件要求** * 影响接口：Create Payout（请求） * 当 `beneficiary.bank_details.account_currency_code = "INR"` 且 `clearing_system = "IFSC"` 时，必须上传发票文件。 * 文件需通过 `documentation` 字段上传。 *** **\[BREAKING] `purpose_code` 枚举移除 `OTHER_SERVICES`** * 影响接口：Create Payout（请求） * `purpose_code` 字段移除 `OTHER_SERVICES` 取值。已有集成若使用该值需更新。 ## Acquiring **\[NEW] `acquiring.payment_intent.requires_action` Webhook** * 当客户认证阶段 Payment Intent 状态变为 `REQUIRES_CUSTOMER_ACTION` 时触发。 ## Account Center **\[BREAKING] Create SubAccount：文件类字段由对象改为数组** * 影响接口：Create SubAccount（请求） * 以下字段现接收数组而非单一对象： * `identity_verification.identity_docs` * `ownership_details.shareholder_docs` * `ownership_details.representatives.identity_docs` * `company_info.certification_of_incorporation` * `proof_documents.proof_of_address` * `proof_documents.source_of_funds` * `proof_documents.proof_of_position_and_income` ## Banking **\[NEW] 跨币种出款支持** * Create Quote：新增 `transaction_type` 字段 —— `conversion`（默认）用于换汇；`payout` 用于跨币种出款。 * Create Payout：新增 `payout_currency`、`payout_amount`、`quote_id` 字段。 * Retrieve Payout / List Payouts：新增 `quote_id` 与 `conversion` 字段（`currency_pair`、`client_rate`）。 * Webhook `payout.*`：新增 `conversion`、`quote_id`、`payout_amount`、`payout_currency` 字段。 *** **\[BREAKING] 收款人基础信息字段新增校验** * 影响接口：Create Beneficiary（请求）、Create Payout（请求） * 影响字段：`bank_details.account_holder`、`first_name`、`last_name`、`company_name`、`address.street_address`、`address.city`、`address.state` * 新校验适用于除 `bank_details.account_currency_code = CNH`、`payment_method = LOCAL`、`bank_country_code = CN` 之外的所有场景。 * 仅允许英文字符、数字、特殊字符与空格。 * 新加坡 SGD 个人账户（`entity_type = INDIVIDUAL`、`bank_country_code = SG`、`account_currency_code = SGD`）下，`account_holder` 适用更严格的校验。 *** **\[BREAKING] `payout_reference` 新增校验** * 影响接口：Create Payout（请求） * 仅允许英文字母、数字、空格、逗号（`,`）和句点（`.`）。 ## Issuing **\[NEW] 批量创建虚拟卡接口** * 新增接口：Bulk Create Virtual Cards * 新增 Webhook：`issuing.report.succeeded` —— 用于下发卡号文件的解密密钥。 * Assign Card 接口扩展，支持绑定批量创建出的虚拟卡。 * 提交后返回 `report_id`，需在过期前通过 Download Report 接口下载卡号文件。 * 调用 Bulk Create Virtual Cards 之前，必须先订阅 `issuing.report.succeeded`。 *** **\[ENHANCED] 卡报表新增 `Ori Transaction Id` 字段** * 影响报表：Card Transaction Report、Card Settlement Report * 新增字段 `Ori Transaction Id`。 ## Banking **`email` 与 `nickname` 字段改为可选** * 影响接口：Create Beneficiary（请求）、Create Payout（请求） * `email`：必填 → 可选 * `nickname`：必填 → 可选 *** **新加坡（SGD）账户字段调整** 当 `bank_details.bank_country_code = SG` 且 `bank_details.account_currency_code = SGD` 时： * 影响接口：Create Beneficiary（请求）、Create Payout（请求） * 移除：`company_name`、`first_name`、`last_name`、`address.country`、`address.street_address`、`address.city`、`address.state`、`address.postal_code` * 改为可选：`email`、`nickname` *** **\[BREAKING] SGD 个人账户 `bank_details.account_holder` 新增校验** * 影响接口：Create Beneficiary（请求）、Create Payout（请求） * 适用条件：`entity_type = INDIVIDUAL`、`bank_country_code = SG`、`account_currency_code = SGD`。 * 新校验：仅允许英文字母（A–Z、a–z）和空格；2–140 字符；必须包含一个空格分隔名与姓。 ## Issuing **\[NEW] List Cards 与 Retrieve Card 新增 `consumed_amount` 字段** * 影响接口：List Cards（响应）、Retrieve Card（响应） * 新增 `consumed_amount` 字段，表示已使用的累计卡片限额。 ## Account Center **\[ENHANCED] 账户接口新增 `business_code` 过滤与字段** * 影响接口：Retrieve Account（请求与响应）、List Connected Accounts（响应） * Retrieve Account 新增可选过滤参数 `business_code` —— 取值：`BANKING`、`ISSUING`、`ACQUIRING`（默认：`BANKING`）。 * Retrieve Account 与 List Connected Accounts 响应新增 `business_code` 字段。 *** **\[ENHANCED] Create SubAccount 代表人新增 `email_address` 字段** * 影响接口：Create SubAccount（请求） * `ownership_details.representatives[]` 新增可选字段 `email_address`。 *** **Create SubAccount：`website_url` 与 `company_description` 改为可选** * 影响接口：Create SubAccount（请求） * `business_details.website_url`：必填 → 可选 * `business_details.company_description`：必填 → 可选 ## Issuing **Simulate Authorization 支持卡 BIN `40963608`** * 影响接口：Simulate Authorization * 新增对 BIN `40963608` 的沙盒授权模拟支持。无 schema 变更。 ## Acquiring **\[NEW] Payment Attempt Webhook 事件** 新增 4 个 Payment Attempt（PA）状态流转 Webhook： * `acquiring.payment_attempt.created` —— PA 状态变为 `INITIATED` 时触发 * `acquiring.payment_attempt.capture_requested` —— PA 状态变为 `CAPTURE_REQUESTED` 时触发（消费者完成支付，对应 PI 进入 `SUCCESS`） * `acquiring.payment_attempt.cancelled` —— PA 状态变为 `CANCELLED` 时触发 * `acquiring.payment_attempt.failed` —— PA 状态变为 `FAILED` 时触发 PI/PA 一对一映射时，PA 失败意味着 PI 也失败。一对多映射时，单个 PA 失败不会导致 PI 失败。 在控制台订阅这些事件即可接收。 *** **\[NEW] Settlements 接口** * 新增接口：`GET /api/v2/payment/settlements` * 支持可选参数 `settlement_batch_id` 或 `payment_intent_id`，支持分页与时间范围过滤。 * 仅返回 `settlement_status = success` 的记录。 ## Banking **\[BREAKING] `bank_details.account_number` 限制为字母数字字符** * 影响接口：Create Payout（请求）、Create Beneficiary（请求） * 仅接受字母 A–Z/a–z 与数字 0–9。空格、连字符及其他特殊字符将被拒绝。 ## Issuing **\[NEW] Card 接口与 Webhook 新增 `update_reason` 字段** * 影响接口：List Cards（响应）、Retrieve Card（响应）、Update Card Status（响应） * 影响 Webhook：`card.status.update.*` * 新增 `update_reason` 字段，标识卡状态变更原因。 *** **\[ENHANCED] Card Recharge 与 Withdraw 支持 SHARE 卡** * 影响接口：Card Recharge（请求）、Card Withdraw（请求） * SHARE 卡现可通过 Recharge（增加）和 Withdraw（减少）调整 `card_available_balance`。 * SINGLE 卡行为不变。 ## Issuing **Create Card 中 `card_limit` 校验更新** * 影响接口：Create Card（请求） * BIN 527735、555071、555243：`card_limit` 必填且必须 ≥ 0.01。 * 其他 BIN：`card_limit` 可选；不传时默认为 0；传入时必须 ≥ 0 且最多保留两位小数。 *** **\[NEW] 新增账户级交易类型** * 影响接口/报表：List Issuing Balances Transactions（响应）、Account Transaction Report * 新增：`FUNDS_TRANSFER_IN`、`FUNDS_TRANSFER_OUT`、`FEE_REFUND`、`FEE_DEDUCTION`、`MARGIN_PAYMENT`、`MARGIN_REFUND`、`OTHER` *** **\[NEW] 新增卡级拒付交易类型** * 影响接口：Retrieve Cards Transaction（响应）、List Cards Transactions（响应） * 新增：`CHARGEBACK_DEBIT`、`CHARGEBACK_CREDIT` *** **\[NEW] 拒付 Webhook** * `issuing.transaction.chargeback.credit` —— 卡交易记入拒付贷记时触发 * `issuing.transaction.chargeback.debit` —— 卡交易记入拒付借记时触发 ## Banking **\[NEW] Deposit 接口与 Webhook 新增 `deposit_reference` 字段** * 影响接口：Retrieve Deposit（响应）、List Deposits（响应） * 影响 Webhook：`deposit.pending`、`deposit.compliance.rejected`、`deposit.completed` * 新增 `deposit_reference` 字段，可携带自定义引用号。 ## Issuing **\[NEW] `card.update.succeeded` 与 `card.update.failed` Webhook** * `card.update.succeeded` —— Update Card 触发的卡订单完成 `SUCCESS` 时触发 * `card.update.failed` —— Update Card 触发的卡订单完成 `FAILED` 时触发 *** **\[ENHANCED] List Issuing Balances Transactions 新增 `ending_balance` 与 `description` 字段** * 影响接口：List Issuing Balances Transactions（响应） * `ending_balance` —— 交易完成后的账户余额 * `description` —— 交易简短描述 *** **Card Settlement Report：`ATM Withdraw` 重命名为 `Authorization`** * 影响报表：Card Settlement Report * `Transaction Type` 枚举值 `ATM Withdraw` 重命名为 `Authorization`。 ## Banking **\[NEW] Retrieve Payout 与 List Payouts 新增 `purpose_code`** * 影响接口：Retrieve Payout（响应）、List Payouts（响应） * 新增 `purpose_code` 字段。 *** **Check Beneficiary 支持 PayNow 收款方** * 影响接口：Check Beneficiary（请求） * 新增 `additional_info.proxy_id` 参数，接受 PayNow 代理标识。 ## Issuing **Card Settlement Report：`Purchase` 重命名为 `Authorization`** * 影响报表：Card Settlement Report * `Transaction Type` 取值 `Purchase` 重命名为 `Authorization`。 ## Account Center **\[NEW] `ownership_details.representatives` 新增 `other_documents` 字段** * 影响接口：Create SubAccount —— `POST /v1/accounts/create_accounts`（请求）；Retrieve Account —— `GET /v1/accounts/{id}`（响应） * 新增可选字段 `other_documents`，可为代表人上传地址证明或补充文件。 * 注意：请求与响应中的字段名不同（请求为 `doc_str`，响应为 `front`）。 Create SubAccount 请求： ```json theme={null} "other_documents": [ { "type": "PROOF_OF_ADDRESS", "doc_str": "base64 string or file ID" } ] ``` Retrieve Account 响应： ```json theme={null} "other_documents": [ { "type": "PROOF_OF_ADDRESS", "front": "base64 string or file ID" } ] ``` 支持的 `type` 取值：`"PROOF_OF_ADDRESS"`、`"OTHERS"`。 ## Account Center **\[NEW] Create SubAccount 接口** * 新增接口：`POST /api/v1/accounts/create_accounts` * 支持在 ACQUIRING、BANKING、ISSUING 业务线下创建子账户。 * 同时支持 `COMPANY` 与 `INDIVIDUAL` 实体类型。 * 通过该接口创建的子账户仍可通过 List Connected Accounts 与 Retrieve Account 查询。 *** **\[NEW] Get Additional Documents 接口** * 新增接口：`GET /api/v1/accounts/get_additional` * 根据国家与业务码返回 COMPANY 子账户创建所需的必要与可选文件类型。 * 在发起子账户创建前调用以获取该清单。 *** **关于旧接口**：旧的 `Create Account`（`POST /api/v1/accounts`）继续可用，但仅支持 BANKING 业务线。新接入请使用 Create SubAccount。 ## Acquiring **\[NEW] `acquiring.payment_intent.failed` Webhook** * 当 Payment Intent 因到期被自动关闭时触发。 * 手动取消的订单不触发此事件。 * 在控制台订阅该事件即可接收。 ## Issuing **\[ENHANCED] `transaction_status` 新增 `PENDING` 状态** * 影响接口：List Cards Transactions（响应）、Retrieve Cards Transaction（响应） * `transaction_status` 新增合法取值 `PENDING`。 ## Banking **\[NEW] Payout 与 Beneficiary 接口新增 PayNow 支持** * 影响接口：Create Payout、Retrieve Payout、Create Beneficiary、List Beneficiaries、Retrieve Beneficiary、Update Beneficiary、Check Beneficiary * `bank_details.clearing_system` 新增枚举值 `PayNow`。 * 新增 `additional_info.proxy_id` 字段，支持 UEN、手机号或 VPA。 ## Acquiring / Account **\[BREAKING] `x-idempotency-key` 启用 UUID 格式校验** * 影响接口：所有 POST 接口（请求头） * `x-idempotency-key` 现必须为合法 UUID 格式。 ## Acquiring **\[NEW] PaymentAttempt 新增 `failure_code` 字段** * PaymentAttempt 响应新增 `failure_code` 字段，标识支付尝试的失败原因。 ## Banking **\[NEW] Create Payout 新增可选 `documentation` 字段** * 影响接口：`POST /api/v1/payouts`（请求） * 新增可选字段 `documentation`，允许在出款请求中附带支持文件。 ## Issuing **\[NEW] `card.create.succeeded` Webhook 新增 `risk_controls` 模块** * `card.create.succeeded` Webhook 体新增 `risk_controls` 模块。返回值（如 `3ds`、`mcc`）因卡产品而异。 ## Issuing **\[NEW] 卡交易接口与报表新增 `wallet_type` 字段** * 影响接口：List Cards Transactions（响应）、Retrieve Cards Transaction（响应） * 影响 Webhook：`issuing.transaction.*` * 影响报表：Card Transactions Report、Card Settlement Report * 新增 `wallet_type` 字段，标识所使用的数字钱包（如 `ApplePay`、`GooglePay`）。 ## Acquiring **\[BREAKING] Webhook 事件类型由 `acquiring.payment.*` 重命名为 `acquiring.payment_intent.*`** *** **\[NEW] `acquiring.payout.created` Webhook** —— 商户发起出款请求时触发。 **\[NEW] `acquiring.refund.created` Webhook** —— 商户发起退款请求时触发。 ## Banking **\[NEW] Create Account 代表人新增 `other_documentation` 字段** * 影响接口：`POST /api/v1/accounts`（请求） * `representatives[]` 新增可选字段 `other_documentation`，支持在创建账户时上传地址证明等补充文件。 ## Issuing **\[NEW] 卡相关 Webhook 新增 `card_available_balance` 字段** * 影响 Webhook：`card.create.*`、`card.recharge.*`、`card.withdraw.*` * 新增 `card_available_balance`，标识事件发生时刻的卡可用余额。 ## Banking **\[ENHANCED] Create Beneficiary 新增 `additional_info.organization_code` 字段** * 影响接口：`POST /api/v1/beneficiaries`（请求） * 新增可选字段 `additional_info.organization_code`（统一社会信用代码），用于公司类收款人。 *** **\[NEW] Retrieve Payout 与 List Payouts 新增 `failure_reason` 字段** * 影响接口：`GET /api/v1/payouts/{id}`（响应）、`GET /api/v1/payouts`（响应） * 出款响应对象新增 `failure_reason` 字段。 ## Issuing **\[NEW] List Card Products 新增 `card_currency` 字段** * 影响接口：`GET /api/v1/issuing/products`（响应） * 新增 `card_currency` 字段 —— 字符串数组，标识每款卡产品支持的币种。例如：`["SGD", "USD"]`。 *** **\[ENHANCED] List Card Products 新增 `card_form` 与 `max_card_quota` 字段** * 影响接口：`GET /api/v1/issuing/products`（响应） * `card_form` —— 支持的卡形态：`["VIR", "PHY"]` 或 `["VIR"]`。 * `max_card_quota` —— 当前账户下该产品可发卡的最大数量。 *** **\[BREAKING] 卡交易接口与 Webhook：`failure_reason` 重命名为 `description`** * 影响接口：`GET /api/v1/issuing/transactions`（响应）、`GET /api/v1/issuing/transactions/{id}`（响应） * 影响 Webhook：`issuing.transaction.*` * 当 `transaction_status = DECLINED`：字段内容为失败原因。 * 当 `transaction_status = APPROVED`：字段内容为补充备注（例如 3DS 交易的 `3DS Fee`）。 * 所有此前以 `failure_reason` 作为列名的交易报表文件，列名同步更新为 `description`。 *** **\[BREAKING] `issuing.transaction.refund` Webhook 简化 `transaction_status`** * `transaction_status` 移除 `REFUNDED` 取值。 * 此前的 `REFUNDED` 交易现映射为 `transaction_type: REFUND` + `transaction_status: APPROVED`。 *** **\[BREAKING] 卡状态值更新** * 影响接口：`GET /api/v1/issuing/cards/{id}`（响应）、`GET /api/v1/issuing/cards`（响应）、`POST /api/v1/issuing/cards/{id}/status`（请求）、`card.status.update.*` Webhook * `INACTIVE` 重命名为 `FROZEN` —— 卡片暂时停用，可重新激活。 * 新增 `BLOCKED` 状态 —— 卡片被 UQPAY 管理员锁定；解锁需提交正式邮件申请。 ## Banking **\[BREAKING] 出款状态移除 `SUBMISSION_FAILED`** * 影响接口：`POST /api/v1/payouts`（响应）、`GET /api/v1/payouts`（请求与响应）、`GET /api/v1/payouts/{id}`（响应） * `payout_status` 字段移除 `SUBMISSION_FAILED` 取值。 ## Issuing **\[ENHANCED] List Cards 新增 `cardholder_id` 参数** * 影响接口：`GET /api/v1/issuing/cards`（请求） * 新增可选查询参数 `cardholder_id`，可按持卡人过滤卡片。 *** **\[NEW] Retrieve Card 新增 `no_pin_payment_amount` 字段** * 影响接口：`GET /api/v1/issuing/cards/{id}`（响应） * 新增 `no_pin_payment_amount` 字段，标识免 PIN 交易的允许金额。格式：`<金额><币种>`（例如 `2000USD`）。 *** **\[ENHANCED] List Card Products 新增 `no_pin_payment_amount`** * 影响接口：`GET /api/v1/issuing/products`（响应） * 新增 `no_pin_payment_amount` 数组，标识每款产品配置的免 PIN 交易金额上限。 ## Acquiring **\[BREAKING] Payment 对象状态字段枚举值调整** * 影响接口：Payment Intents、Payment Attempts、Payment Refunds 接口 * 调整 `intent_status`、`attempt_status`、`refund_status` 的枚举值与定义。最新枚举请参考 API 参考页面。 *** **`payment_method` 取值范围限制** * 影响接口：Payment Intents 接口 * 支持取值：`card`、`card_present`、`alipaycn`、`alipayhk`、`unionpay`、`wechat`。其余类型暂不支持。 ## Issuing **\[ENHANCED] List Cards 新增 `cardholder_id` 过滤** * `GET /api/v1/issuing/cards` 新增可选查询参数 `cardholder_id`。 *** **\[NEW] Retrieve Card 新增 `no_pin_payment_amount`** * `GET /api/v1/issuing/cards/{id}` 响应新增 `no_pin_payment_amount` 字段。格式：`<金额><币种>`（例如 `2000USD`）。 *** **\[ENHANCED] List Card Products 新增 `no_pin_payment_amount` 上限** * `GET /api/v1/issuing/products` 响应新增 `no_pin_payment_amount` 数组，标识每个币种的免 PIN 交易最大允许金额。 ## Acquiring Acquiring API 首次正式发布。本版本提供 Payment Intents、Payment Attempts、Refunds 与 Webhook 通知能力。 ## Banking **\[NEW] Beneficiary 接口新增 `nationality` 与 `id_number` 字段** * 影响接口：Create Beneficiary、Update Beneficiary、Retrieve Beneficiary、List Beneficiaries * 新增 `nationality` —— 收款人国籍的两位字母国家代码。 * 新增 `id_number` —— 当 INDIVIDUAL 类型收款人为中国大陆居民、币种为 CNH、支付方式为 LOCAL 时条件必填。 ## Issuing **\[NEW] 风控配置新增 MCC 管理** * 影响接口：`POST /api/v1/issuing/cards`（Create Card）、`POST /api/v1/issuing/cards/{id}`（Update Card） * `risk_controls` 对象新增可选字段 `allowed_mcc` 与 `blocked_mcc`。 * 同一张卡只能配置其中一个。MCC 须以字符串数组传入（例如 `["5999", "6011"]`）。 ## Issuing **\[NEW] Cardholder 接口新增 `number_of_cards` 字段** * 影响接口：List Cardholders（响应）、Retrieve Cardholder（响应） * 新增 `number_of_cards` 字段。 ## Issuing **\[BREAKING] `x-on-behalf-of` 请求头必须为合法 UUID** * 影响接口：所有支持 `x-on-behalf-of` 请求头的接口 * 若传入，该值必须是对应已存在子账户的合法 UUID。非法值将被拒绝。 ## Issuing **\[BREAKING] Activate Card 新增必填字段 `pin`** * 影响接口：`POST /api/v1/issuing/cards/activate`（请求） * 新增必填字段 `pin`。 * 新增可选字段 `no_pin_payment_amout`。 * 该变更为破坏性变更，已有集成必须更新以包含 `pin` 字段。 ## Issuing **\[NEW] Create Card 与 Update Card 新增 3DS 控制** * 影响接口：`POST /api/v1/issuing/cards`、`POST /api/v1/issuing/cards/{id}` * 新增可选字段 `risk_controls`。向后兼容 —— 已有卡片在未显式配置时不受影响。 ## Banking **\[NEW] 汇率接口** * 新增接口：`GET /api/v1/exchange/rates` * 返回当前汇率。仅供参考 —— 锁汇请使用 Create Quote 接口。 ## Banking **\[NEW] 交易类 RFI 支持** * 新增 Webhook 事件类型 `rfi.transaction.action_required`，适用于充值与出款的 RFI 场景。 * 影响接口：`GET /api/v1/rfis/{id}`（Retrieve RFI）、`POST /api/v1/rfis/answer`（Answer RFI） * 两接口均新增 `rfi_type` 与 `transaction_type` 字段。 * 原有的开户 RFI 流程（`event_type = rfi.action_required`）保持不变。 ## Issuing **\[NEW] Update Cardholder 新增 `email` 字段** * 影响接口：`POST /api/v1/issuing/cardholders/{id}`（请求） * 新增可选字段 `email`。向后兼容。 ## Banking **首次发布更新日志** * 新增 changelog 文档。 * 新增充值类 Webhook：`deposit.pending`、`deposit.compliance.rejected`、`deposit.completed` * 新增充值类接口： * `GET /api/v1/deposit` —— 列出充值 * `GET /api/v1/deposit/{id}` —— 按 ID 查询单笔充值 * `POST /api/v1/simulation/desposit` —— 模拟向全球账户充值（仅沙盒） * 描述与参数限制的文档修正。