> ## Documentation Index
> Fetch the complete documentation index at: https://developers-sandbox.uqpaytech.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 更新日志

> UQPAY 各产品的 API 与文档更新。

**2026-09-18**

Developer tools

### \[BREAKING] SDK与CLI 3.1.0发布

* 受影响客户端：Node.js、Python、Go、Java SDK与UQPAY CLI（请求类型、响应/Webhook模型及安装路径）。
* 发布版本：五款客户端均已提供`3.1.0`，见[客户端下载与安装命令](https://developers-sandbox.uqpaytech.com/docs/zh/developer-tools/client-releases.md)。

本次将原4.0.0的版本号调整为3.1.0，完整保留其功能；相对3.0.0的迁移要求不变。

#### 具体变化

| 范围 | 调整前 | 调整后（3.1.0） |
| - | - | - |
| 客户端版本 | `3.0.0` | 五款客户端统一为`3.1.0` |
| Go模块与import路径 | `github.com/uqpay/uqpay-sdk-go/v3` | 保持`github.com/uqpay/uqpay-sdk-go/v3` |
| RFI响应附件 | 上传文件ID字符串 | 文件详情对象；请求附件仍为上传文件ID |

本次还统一适配PIN管理、Sandbox模拟入账显式传入`account_id`、受益人账号/IBAN校验，以及响应/Webhook模型。统一PIN操作省略`type`表示首次`SET`；无需当前PIN的重置应显式传`RESET`，验证旧PIN后修改应使用`UPDATE`并传六位`old_pin`。PIN请求受理不代表操作完成。

#### 谁需要采取行动

从3.0.0升级前，请检查[3.1.0迁移要求](https://developers-sandbox.uqpaytech.com/docs/zh/developer-tools/client-releases.md#sdk-and-cli-v310)，调整受影响的强类型请求/响应处理，并在Sandbox验证集成。Go 3.0.0用户保持`/v3`路径并运行`go mod tidy`；使用`/v4`的集成须改为`/v3`。Java用户须下载GitHub Release的thin JAR并配置运行时依赖；该制品不通过Maven Central分发。

本SDK版本未新增后续的预授权请款请求字段或CARD/Mastercard Send受益人类型。SDK版本与Gateway API文档版本独立。

**2026-09-17**

Global Account

### \[NEW] Mastercard Send 卡出款

* 受影响接口：[Create Beneficiary](https://developers-sandbox.uqpaytech.com/docs/zh/global-account/v1.6/api-reference/create-beneficiary.md)、[Update Beneficiary](https://developers-sandbox.uqpaytech.com/docs/zh/global-account/v1.6/api-reference/update-beneficiary.md)、[List Payment Methods](https://developers-sandbox.uqpaytech.com/docs/zh/global-account/v1.6/api-reference/list-payment-methods.md)、[Create Payout](https://developers-sandbox.uqpaytech.com/docs/zh/global-account/v1.6/api-reference/create-payout.md)（请求和响应）。
* 受影响事件：[Beneficiary Created](https://developers-sandbox.uqpaytech.com/docs/zh/global-account/v1.6/webhooks/beneficiary-created.md) 与 [Payout Status](https://developers-sandbox.uqpaytech.com/docs/zh/global-account/v1.6/webhooks/payout-status.md)（卡交易的通知载荷）。

#### 具体变化

| 项目 | 支持行为 |
| - | - |
| 卡受益人 | 使用 `payment_method: CARD` 和 `bank_details.clearing_system: MASTERCARD SEND`，提供卡号、持卡人姓名和有效期月份；公司受益人还须提供地址 |
| 支付方式查询 | 按国家、币种及收款实体 `entity_type` 查询可用方式和字段校验规则 |
| 卡出款 | 使用已保存的 CARD 受益人，或在出款请求中传入完整受益人对象 |
| 响应与通知 | 受益人使用 `payment_method: CARD`，出款订单使用 `payout_method: CARD`，通知使用 `data.payment_type: CARD` |

#### 谁需要采取行动

现有 LOCAL/SWIFT 集成无需调整。采用 Mastercard Send 的集成须开通产品及相应付款方/收款方授权，校验卡资料，并在响应和通知处理逻辑中支持 `CARD`。创建成功响应或 `payout.ready.send` 事件不代表付款完成。参见[Mastercard Send 接入指南](https://developers-sandbox.uqpaytech.com/docs/zh/global-account/v1.6/guide/payout.md#mastercard-send-payouts)。

Global Acquiring

### \[BREAKING] 移除PaymentAttempt请款金额字段

* 受影响响应：[查询PaymentAttempt](https://developers-sandbox.uqpaytech.com/docs/zh/global-acquiring/v1.6/api-reference/retrieve-payment-attempt.md)、PaymentAttempt列表，以及PaymentIntent响应内嵌的`latest_payment_attempt`对象。
* 受影响事件：[PaymentAttempt Webhooks](https://developers-sandbox.uqpaytech.com/docs/zh/global-acquiring/v1.6/webhooks/paymentattempt-result.md)（通知载荷）。

#### 具体变化

| 响应字段 | 调整前 | 调整后 |
| - | - | - |
| PaymentAttempt的`captured_amount` | 返回此字段 | 不返回此字段 |
| PaymentIntent的`captured_amount` | 支付级聚合金额 | 保留，仍表示支付级聚合金额 |

#### 谁需要采取行动

若集成读取或强制要求PaymentAttempt的`captured_amount`，请调整响应和Webhook处理逻辑。支付级聚合金额使用[PaymentIntent](https://developers-sandbox.uqpaytech.com/docs/zh/global-acquiring/v1.6/api-reference/retrieve-payment-intent.md)的`captured_amount`，单笔请款金额使用`capture_records[].capture_amount`。两者粒度不同；将金额视为渠道已完成请款前，还应检查请款处理状态。

### \[NEW] 预授权与最终请款

* 受影响接口：创建、确认、请款、查询及列表PaymentIntent（请求和响应），以及撤销和退款接口。
* 适用于支持预授权的账户和渠道上的卡支付。参见[预授权与手动请款](https://developers-sandbox.uqpaytech.com/docs/zh/global-acquiring/v1.6/guide/direct-api-integration.md#pre-authorization-and-manual-capture)。

#### 具体变化

| 项目 | 支持行为 |
| - | - |
| 授权类型 | 通过`authorization_type=pre_authorization`创建或确认支付 |
| 最终请款 | 在返回的授权到期时间前完成一次请款；部分金额的最终请款要求渠道支持；不支持非最终请款和零金额请款 |
| PaymentIntent响应 | 提供授权到期时间和可用额度；详情和列表查询还提供单笔请款记录 |
| 响应状态 | 预授权状态包含`PARTIALLY_CAPTURED`和`EXPIRED` |

#### 谁需要采取行动

采用预授权的集成需确认账户和渠道支持，按最终请款限制设计流程，并支持对应响应状态。实现撤销和退款前，请检查[撤销](https://developers-sandbox.uqpaytech.com/docs/zh/global-acquiring/v1.6/guide/cancellation.md)和[退款](https://developers-sandbox.uqpaytech.com/docs/zh/global-acquiring/v1.6/guide/refunds.md)的适用条件。

### \[ENHANCED] 支付Webhook卡信息

* 受影响事件：[PaymentAttempt Webhooks](https://developers-sandbox.uqpaytech.com/docs/zh/global-acquiring/v1.6/webhooks/paymentattempt-result.md)（通知载荷中的线上卡和线下卡支付详情）。

#### 具体变化

| 响应字段 | 调整前 | 调整后 |
| - | - | - |
| `payment_method.card.issuer_country_code`和`payment_method.card_present.issuer_country_code` | 不返回此字段 | 返回大写发卡国家代码，无法获取时为空字符串 |

#### 谁需要采取行动

无需强制调整现有集成；需要发卡国家信息的集成可读取新增字段。

Account Center

### \[BREAKING] Create SubAccount公司进件要求更新

* 受影响接口：[Create SubAccount](https://developers-sandbox.uqpaytech.com/docs/zh/account-center/v1.6/api-reference/create-sub-account.md)（请求）。
* 本次调整适用于`entity_type`为`COMPANY`且`inherit`为`-1`的请求。使用`inherit=1`创建公司子账户不受影响。

#### 具体变化

| 请求字段 | 调整前 | 2026-09-17起 |
| - | - | - |
| `ownership_details.representatives[].email_address` | 可选 | 每位代表人均必填 |
| `ownership_details.representatives[].ownership_percentage` | 可选 | 每位代表人均必填；代表人无持股比例时传入`"0"` |
| `business_details.account_purpose` | 可选；还支持`BUSINESS_PAYMENT`、`BILL_PAYMENT`、`CHARITABLE_DONATION`、`LOAN_REPAYMENT`、`INVESTMENT`和`COLLECTION_OF_BUSINESS` | 必填；仅支持`PAYMENT_COLLECTION`、`PAYOUT_DISBURSEMENT`、`MULTI_CURRENCY_BANKING`、`CARD_ISSUING`、`CRYPTO_RAMP`、`GLOBAL_TRANSFER`、`TREASURY_FX`和`OTHERS`，传入“调整前”列出的六个枚举值时请求会被拒绝 |
| `business_details.banking_countries` | 可选 | 必填；每个值必须是ISO 3166-1 alpha-2国家/地区代码 |
| `business_details.banking_currencies` | 可选 | 必填；每个值必须是ISO 4217 alpha-3币种代码 |
| `business_details.articles_of_association` | 可选 | 必填；每项支持base64编码文件内容或UQPAY文件ID |

#### 谁需要采取行动

如果你使用`inherit=-1`创建公司子账户，请在本次调整生效前更新请求参数。更新后的校验将于**2026-09-03**在Sandbox提供，你可以在Production上线前验证公司进件请求能否正常受理。

Card Issuance

### \[BREAKING] PIN 管理接口升级

* 影响接口：[Manage Card PIN](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/reset-pin.md)（请求与响应）。
* 该接口统一处理 PIN 的设置、重置和修改，并包含 Set or Reset Virtual Card PIN 的能力。

#### 具体变化

| 项目 | 调整前 | 调整后 |
| - | - | - |
| 请求 `type` | 无需传入 | 可选，不传时默认为 `SET`：`SET`（首次设置）、`RESET`（免旧 PIN 重置）、`UPDATE`（验证旧 PIN 后修改） |
| 请求 `old_pin` | 不适用 | `UPDATE` 必填，必须传入当前六位数字 PIN；其他操作禁止传入 |
| 成功响应 | `request_status` | 返回 `request_status`、`card_id`、`card_order_id`、`order_status`、`create_time`；仅表示异步受理，需跟踪订单最终结果 |

#### 需要采取行动的客户

* **将 `/cards/pin` 受理成功视为 PIN 已变更的客户**：请调整结果处理，跟踪订单最终状态后，再向持卡人确认操作完成。
* **已集成 [Set or Reset Virtual Card PIN](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/manage-card-pin.md) 的客户**：旧接口 `POST /api/v1/issuing/cards/manage/pin` 将于 **2026-10-17** 下线，请在下线前迁移至 `POST /api/v1/issuing/cards/pin`。

### \[BREAKING] 持卡人年龄校验调整

* 影响请求：[Create Cardholder](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/create-cardholder.md)、[Update Cardholder](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/update-cardholder.md) 的 `date_of_birth`，以及 [Create Card](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/create-card.md) 的 `cardholder_required_fields.date_of_birth`。

#### 具体变化

| 项目 | 调整前 | 调整后 |
| - | - | - |
| 持卡人年龄 | 年满 18 周岁 | 年满 18 周岁且未满 80 周岁；包含 18 岁，不包含 80 岁 |

#### 需要采取行动的客户

* **当前提交 80 周岁及以上持卡人出生日期的客户**：请在 **2026-09-17** 前调整持卡人准入校验。不符合年龄要求的请求将被拒绝。

### \[BREAKING] Enhanced 持卡人第三方 KYC 引用 ID 校验调整

* 影响接口：[Create Cardholder](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/create-cardholder.md)（请求）。
* 通过 `kyc_verification.method=THIRD_PARTY` 方式创建 Enhanced 持卡人时，在 `kyc_verification.kyc_proof.reference_id` 中上送第三方 KYC 提供商的引用 ID。

#### 具体变化

| 项目 | 调整前 | 调整后 |
| - | - | - |
| 请求 `kyc_verification.kyc_proof.reference_id` | 最少 10 个字符 | 10–64 个字符（含 10 和 64）；超出范围的请求将被拒绝 |

通过 [Update Cardholder](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/update-cardholder.md) 提交该 KYC 证明，或通过 [Create Card](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/create-card.md) 的 `cardholder_required_fields.kyc_verification.kyc_proof.reference_id` 提交时，也适用同一要求。

#### 需要采取行动的客户

* **通过 `THIRD_PARTY` 方式提交 KYC 证明，且当前引用 ID 超过 64 个字符的客户**：请在 **2026-09-17** 前调整集成，使用实际 KYC 提供商提供的、符合长度要求的有效引用 ID。请勿自行截断服务商的引用 ID。

### \[BREAKING] Enhanced 持卡人第三方 KYC provider 校验调整

* 影响接口：[Create Cardholder](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/create-cardholder.md)（请求）。
* 通过 `kyc_verification.method=THIRD_PARTY` 方式创建 Enhanced 持卡人时，在 `kyc_verification.kyc_proof.provider` 中上送 KYC 验证服务商。

#### 具体变化

| 项目 | 调整前 | 调整后 |
| - | - | - |
| 请求 `kyc_verification.kyc_proof.provider` | 字符串，未限定固定枚举 | 仅接受 `SUMSUB`、`MYINFO`、`JUMIO`、`DIDIT`、`SHUFTI`、`REGTANK`；其他值将被拒绝 |

通过 [Update Cardholder](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/update-cardholder.md) 提交该 KYC 证明，或通过 [Create Card](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/create-card.md) 的 `cardholder_required_fields.kyc_verification.kyc_proof.provider` 提交时，也适用同一要求。

#### 需要采取行动的客户

* **通过 `THIRD_PARTY` 方式提交 KYC 证明，且当前 provider 不在支持范围内的客户**：请在 **2026-09-17** 前调整集成，上送与实际 KYC 验证服务商对应的受支持枚举值。

### \[BREAKING] 交易 wallet\_type 返回值标准化

* 影响响应：[List Cards Transactions](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/list-cards-transactions.md) 的 `data[].wallet_type`、[Retrieve Cards Transaction](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/retrieve-cards-transaction.md) 的 `wallet_type`，以及全部[交易 Webhook](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/webhooks/transaction.md)（`issuing.transaction.*`）的 `data.wallet_type`。

#### 具体变化

| 项目 | 调整前 | 调整后 |
| - | - | - |
| 非空 `wallet_type` | `ApplePay`、`GooglePay` 等原始值 | 标准值，区分 Apple Pay、Google Pay、Samsung Pay 的非接触式支付与电子商务场景；无法识别的值返回 `OTHER`。完整值域见接口文档 |
| 空 `wallet_type` | 空字符串 | 空字符串 |

#### 需要采取行动的客户

* **对上述响应或 Webhook 使用固定枚举、严格校验或钱包分类规则的客户**：请在 **2026-09-17** 前适配标准值及空字符串。

**2026-09-11**

Card Issuance

### \[NEW] 交易详情新增清算状态

[查询卡交易](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/retrieve-cards-transaction.md)的成功响应新增 `settlement_status`。交易列表响应保持不变。

`SETTLED` 包含部分清算，不表示全额结算已完成。如果你的响应解析器会拒绝未知字段，请检查它对 `settlement_status` 的处理。

**2026-09-03**

Global Account

### \[BREAKING] Create Virtual Account application 合同与生命周期调整

受影响资源：

* [升级虚拟账户 API 集成](https://developers-sandbox.uqpaytech.com/docs/zh/global-account/v1.6/guide/migrate-to-virtual-account-applications.md)
* [Create Virtual Account](https://developers-sandbox.uqpaytech.com/docs/zh/global-account/v1.6/api-reference/create-virtual-account.md)
* [List Virtual Account Applications](https://developers-sandbox.uqpaytech.com/docs/zh/global-account/v1.6/api-reference/list-virtual-account-applications.md)
* [Retrieve Virtual Account Application](https://developers-sandbox.uqpaytech.com/docs/zh/global-account/v1.6/api-reference/retrieve-virtual-account-application.md)
* [虚拟账户申请 Webhook](https://developers-sandbox.uqpaytech.com/docs/zh/global-account/v1.6/webhooks/virtual-account-create-update.md)

Sandbox 调整将于 **2026-08-13** 生效，Production 将于 **2026-09-03** 生效。

#### 整体变化

* [Create Virtual Account](https://developers-sandbox.uqpaytech.com/docs/zh/global-account/v1.6/api-reference/create-virtual-account.md) 现在会针对必填的国家和单个币种创建一笔申请。你可以明确选择一种收款方式，也可以让系统评估两种可用方式。
* Create 成功时返回 HTTP `200`、已受理的申请及各收款方式的处理结果。这表示异步处理已经开始，不表示银行信息已经可以使用。
* 使用新增的 [List Virtual Account Applications](https://developers-sandbox.uqpaytech.com/docs/zh/global-account/v1.6/api-reference/list-virtual-account-applications.md) 和 [Retrieve Virtual Account Application](https://developers-sandbox.uqpaytech.com/docs/zh/global-account/v1.6/api-reference/retrieve-virtual-account-application.md) 跟踪异步申请生命周期。
* [虚拟账户申请 Webhook](https://developers-sandbox.uqpaytech.com/docs/zh/global-account/v1.6/webhooks/virtual-account-create-update.md) 现在通过 `virtual.account.create`、`virtual.account.update` 和 `virtual.account.closed` 报告整笔申请的变化。
* 申请 API 响应和 Webhook 数据包含 `account_id` 和 `direct_id`，便于将每笔申请关联到正确的账户层级。

#### 谁需要采取行动

目前调用 Create Virtual Account 或消费虚拟账户 Webhook 的集成需要在 Production 上线前完成适配。请按照[升级虚拟账户 API 集成](https://developers-sandbox.uqpaytech.com/docs/zh/global-account/v1.6/guide/migrate-to-virtual-account-applications.md)完成代码改造和 Sandbox 验收；请求参数、状态、错误与对账行为详见[通过 API 集成虚拟账户](https://developers-sandbox.uqpaytech.com/docs/zh/global-account/v1.6/guide/virtual-account-api-lifecycle.md)。

#### 升级 SDK 或 CLI

各款 UQPAY SDK 与 CLI 的 `2.0` 发布线均已支持虚拟账户申请合同。请在 Production 上线前按下表升级到当前版本。Node.js SDK 与 CLI `2.0.1` 还会在可安全重试的写请求中复用同一个幂等键；远端结果不确定时要求先核对状态，不再盲目重放写请求：

| 客户端 | 升级方式 |
| - | - |
| Node.js（`@uqpay/sdk`） | `npm install @uqpay/sdk@2.0.1` |
| Python（`uqpay`） | `pip install --upgrade uqpay==2.0.0` |
| Go（`uqpay-sdk-go/v2`） | `go get github.com/uqpay/uqpay-sdk-go/v2@v2.0.0 && go mod tidy` |
| Java（`uqpay-sdk-java`） | 从 [GitHub Releases](https://github.com/uqpay/uqpay-sdk-java/releases/tag/v2.0.0) 下载 `uqpay-sdk-java-2.0.0.jar` |
| CLI（`@uqpay/cli`） | `npm install -g @uqpay/cli@2.0.1` |

这是客户端的主版本升级。Go 项目还需要把 import path 更新为 `github.com/uqpay/uqpay-sdk-go/v2`。升级前请查看[客户端发布说明](https://developers-sandbox.uqpaytech.com/docs/zh/developer-tools/client-releases.md)和[虚拟账户迁移指南](https://developers-sandbox.uqpaytech.com/docs/zh/global-account/v1.6/guide/migrate-to-virtual-account-applications.md)。

#### 推荐阅读路径

1. 先阅读[升级虚拟账户 API 集成](https://developers-sandbox.uqpaytech.com/docs/zh/global-account/v1.6/guide/migrate-to-virtual-account-applications.md)，确认需要修改的代码并完成 Sandbox 验收清单。
2. 改造客户端接口调用时，依次查看 [Create Virtual Account](https://developers-sandbox.uqpaytech.com/docs/zh/global-account/v1.6/api-reference/create-virtual-account.md)、[List Virtual Account Applications](https://developers-sandbox.uqpaytech.com/docs/zh/global-account/v1.6/api-reference/list-virtual-account-applications.md) 和 [Retrieve Virtual Account Application](https://developers-sandbox.uqpaytech.com/docs/zh/global-account/v1.6/api-reference/retrieve-virtual-account-application.md)，了解各接口的请求参数与响应结构。
3. 使用[通过 API 集成虚拟账户](https://developers-sandbox.uqpaytech.com/docs/zh/global-account/v1.6/guide/virtual-account-api-lifecycle.md)实现状态、错误、可用性判断和对账处理。
4. 使用[虚拟账户申请 Webhook](https://developers-sandbox.uqpaytech.com/docs/zh/global-account/v1.6/webhooks/virtual-account-create-update.md)实现 Webhook 验签、去重、顺序处理和补偿查询。

**2026-08-28**

## Account Center

**\[BREAKING] Create SubAccount代码格式校验和公司进件选项更新**

* 受影响接口：[Create SubAccount](https://developers-sandbox.uqpaytech.com/docs/zh/account-center/v1.6/api-reference/create-sub-account.md)（请求）。
* `banking_countries`中的每个值都必须是ISO 3166-1 alpha-2国家/地区代码，`banking_currencies`中的每个值都必须是ISO 4217 alpha-3币种代码。包含其他格式值的请求会被拒绝。UQPAY仍只处理每个数组中的前三个值。
* 对于公司子账户，`business_details.account_purpose`同时支持现有枚举值和新增枚举值`PAYMENT_COLLECTION`、`PAYOUT_DISBURSEMENT`、`MULTI_CURRENCY_BANKING`、`CARD_ISSUING`、`CRYPTO_RAMP`、`GLOBAL_TRANSFER`及`TREASURY_FX`。
* 公司请求可以通过`business_details.articles_of_association`可选传入公司章程文件数组。每项支持base64编码的文件或UQPAY文件ID。

### 谁需要采取行动

在更新后的Production API上线前，请确保`banking_countries`和`banking_currencies`中的每个值都使用规定的代码格式。现有公司`account_purpose`枚举值无需迁移。

**2026-08-27**

## Account Center

**Create SubAccount 请求处理已简化**

* 受影响接口：[Create SubAccount](https://developers-sandbox.uqpaytech.com/docs/zh/account-center/v1.6/api-reference/create-sub-account.md)（请求）和 [Get Additional Documents](https://developers-sandbox.uqpaytech.com/docs/zh/account-center/v1.6/api-reference/get-additional-documents.md)（响应）。
* Create SubAccount 请求不再要求选择业务线。
* `expected_activity.turnover_monthly` 始终按 USD 解释。`expected_activity.turnover_monthly_currency` 不再使用；如果继续传入，UQPAY 会忽略该字段。
* `banking_countries` 和 `banking_currencies` 可以传入超过三个值，但 UQPAY 对每个数组只处理前三个值。
* Get Additional Documents 已废弃。该接口仍为兼容现有集成而保留，并返回空数组。
* 现有 Create SubAccount 集成仍可继续运行；新集成应省略 `turnover_monthly_currency`，并且不再使用 Get Additional Documents。

## Card Issuance

**\[ENHANCED] `card.verification.otp` Webhook现可标识OTP下发方式和目标**

* 受影响Webhook：[`card.verification.otp`](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/webhooks/verification-otp)。
* `data.verification_method`用于标识OTP通过`SMS`还是`EMAIL`下发。
* `data.verification_target`在`SMS`方式下包含`country_code`和`phone_number`，在`EMAIL`方式下包含`email`。
* 如果你的Webhook接收端使用严格的schema或拒绝未知字段，请更新实现以接受新增字段和枚举值。

## Stablecoin Account

**充值和提现查询现可返回Travel Rule状态**

* 受影响接口：[List Deposits](https://developers-sandbox.uqpaytech.com/docs/zh/stablecoin-account/v1.6/api-reference/list-deposits.md)、[Retrieve Deposit](https://developers-sandbox.uqpaytech.com/docs/zh/stablecoin-account/v1.6/api-reference/retrieve-deposit.md)、[List Withdraws](https://developers-sandbox.uqpaytech.com/docs/zh/stablecoin-account/v1.6/api-reference/list-withdraws.md)和[Retrieve Withdraw](https://developers-sandbox.uqpaytech.com/docs/zh/stablecoin-account/v1.6/api-reference/retrieve-withdraw.md)（响应）。
* 查询响应恒定包含`need_travel_rule`。充值订单为`true`时，必须提交发起方Travel Rule信息；该值反映订单当前状态，所需信息记录后会变为`false`。提现订单恒为`false`，因为所需信息在建单前收集。
* 响应还包含可为`null`的`travel_rule_status`。非空值为`REJECTED`、`PENDING`、`APPROVED`和`ON_HOLD`。
* 现有集成无需修改；请使用`need_travel_rule`而非仅凭`travel_rule_status`判断是否需要提交信息。

**2026-08-26**

## Account Center

**公司代表人的出生日期现为可选字段**

* 受影响接口：[Create SubAccount](https://developers-sandbox.uqpaytech.com/docs/zh/account-center/v1.6/api-reference/create-sub-account.md)（请求）。
* 当 `entity_type` 为 `COMPANY` 时，不再要求提供 `ownership_details.representatives[].date_of_birth`。
* 如果提供该字段，仍必须使用 `YYYY-MM-DD` 格式。
* 本次调整不影响个人子账户：当 `entity_type` 为 `INDIVIDUAL` 时，`individual_info.date_of_birth` 仍为必填字段。
* 现有集成可以继续发送该字段，无需修改。

**2026-08-20**

## Global Acquiring

**出款响应新增手续费与金额明细**

* 受影响接口：[Create Payout](https://developers-sandbox.uqpaytech.com/docs/zh/global-acquiring/v1.6/api-reference/create-payout.md)、[Retrieve Payout](https://developers-sandbox.uqpaytech.com/docs/zh/global-acquiring/v1.6/api-reference/retrieve-payout.md) 和 [List all Payouts](https://developers-sandbox.uqpaytech.com/docs/zh/global-acquiring/v1.6/api-reference/list-payouts.md)（响应）。
* 出款响应新增 `payout_fee`、`debited_amount` 和 `transfer_amount`，币种均为 `payout_currency`。
* 手续费从出款金额中扣除：`debited_amount = payout_amount`；`transfer_amount = payout_amount - payout_fee`。
* 手续费单独收取：`debited_amount = payout_amount + payout_fee`；`transfer_amount = payout_amount`。
* 现有集成可以继续使用当前响应字段；对账时请使用 `debited_amount` 和 `transfer_amount` 分别核对余额扣款金额与下游出款金额。

**2026-08-14**

## Account Center

**`individual_info.company_name` 现为可选字段**

* 受影响接口：[Create SubAccount](https://developers-sandbox.uqpaytech.com/docs/zh/account-center/v1.6/api-reference/create-sub-account.md)（请求）。
* 当 `entity_type` 为 `INDIVIDUAL` 时，不再要求提供 `individual_info.company_name`。
* 如果提供该字段，仍沿用现有格式和校验规则。

**2026-08-04**

## Developer tools

**五个客户SDK已统一至`v1.2.0`**

Node.js、Go、Python、Java和CLI SDK现以`v1.2.0`作为首个共同稳定基线。本次发布统一了它们对Account Center、Global Account、Global Acquiring、Card Issuance与Supporting Services当前公开API的支持范围。Stablecoin Account（Ramp）不包含在本次SDK发布范围内。

| SDK | 版本 | 升级命令 |
| - | - | - |
| Node.js（`@uqpay/sdk`） | `1.2.0` | `npm install @uqpay/sdk@1.2.0` |
| Python（`uqpay`） | `1.2.0` | `pip install --upgrade uqpay==1.2.0` |
| Go（`uqpay-sdk-go`） | `v1.2.0` | `go get github.com/uqpay/uqpay-sdk-go@v1.2.0 && go mod tidy` |
| Java（`uqpay-sdk-java`） | `1.2.0` | 从[GitHub Releases](https://github.com/uqpay/uqpay-sdk-java/releases/tag/v1.2.0)下载JAR |
| CLI（`@uqpay/cli`） | `1.2.0` | `npm install -g @uqpay/cli@1.2.0` |

**运行环境要求**

* Node.js SDK和CLI npm安装器：Node.js 22或更高版本。
* Python SDK：Python 3.11或更高版本。
* Go SDK：保持Go 1.19及以上版本的源码兼容性。
* Java SDK：Java 11或更高版本。

**本次发布后的版本规则**

* 五个SDK共享`MAJOR.MINOR`，用于标识已对齐的API能力基线。
* SDK自身的兼容性修复可以独立提升`PATCH`，因此各SDK的完整版本号不一定始终相同。
* 后续统一的API覆盖范围更新将根据兼容性提升共享的`MAJOR.MINOR`版本。

> [!WARNING]
>
> 这是一次初始基线对齐发布。升级前请查看相应SDK仓库的changelog。现有Node.js和CLI项目如果仍锁定在`0.x` caret版本范围，仅执行`npm update`不会升级到`1.2.0`；请使用上表中的显式安装命令。

> [!NOTE]
>
> Java `1.2.0`目前仅以thin JAR形式通过GitHub Releases分发，尚未发布到Maven Central。你的应用构建需要解析其运行时依赖。

**2026-07-30**

## Card Issuance

**\[BREAKING] Personal Visa 绑卡现需提供卡 SKU 元数据**

* 受影响接口：[Assign Card](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/assign-card.md)。
* 绑定 Personal Visa 卡时，请求必须包含 `metadata.card_sku_code`，该字段为恰好 12 个字符的字符串。
* 绑定其他卡产品时，请省略 `metadata`。
* 本改动仅影响调用 Assign Card 的 Personal Visa 集成，其他卡产品不受影响。

**2026-07-25 (System Upgrade)**

# 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-system-upgrade](https://developers.uqpay.com/zh/changelog#2026-07-25-system-upgrade)

感谢您的理解与支持。如在升级期间遇到紧急问题，请及时联系 UQPAY 客户支持团队，我们将协助您处理。

UQPAY CST TEAM

2026 年 7 月 21 日

**2026-07-25**

## Account Center

**入驻 RFI webhook 新增 `rfi_type` 取值**

* 受影响 webhook：[入驻RFI](https://developers-sandbox.uqpaytech.com/docs/zh/account-center/v1.6/webhooks/onboarding-rfi.md) —— `data.rfi_type` 字段。
* `rfi_type` 在 `onboarding` 之外还可能返回以下取值：
  * `business_line` —— 为账户开通业务线。
  * `screening` —— 制裁、PEP 或负面媒体筛查命中。
  * `edd` —— 加强尽调，如资金来源、异常交易模式等。
  * `periodic` —— 周期性复审，如 KYC 复核、证件续期、UBO 刷新。
  * `change` —— 变更登记，如董事、地址、股权结构变更。
  * `operations` —— 运营事件，如拒付、退款。
  * `regulatory` —— 监管要求，如税务证明、牌照续期。
  * `other` —— 上述类型未覆盖的其它情形。
* 向后兼容 —— 仅为新增取值。处理流程不变：获取 RFI 详情、上传所需文件、再提交 Answer RFI。请确认你的集成不会因为 `rfi_type` 取值无法识别而拒绝或丢弃通知。

**2026-07-16**

Global Account

### \[BREAKING] 受益人地址校验现适用于所有币种和支付方式

* 受影响接口：[Create Beneficiary](https://developers-sandbox.uqpaytech.com/docs/zh/global-account/v1.6/api-reference/create-beneficiary.md)、[Update Beneficiary](https://developers-sandbox.uqpaytech.com/docs/zh/global-account/v1.6/api-reference/update-beneficiary.md)，以及请求中提交完整 `beneficiary` 信息而非 `beneficiary_id` 的 [Create Payout](https://developers-sandbox.uqpaytech.com/docs/zh/global-account/v1.6/api-reference/create-payout.md)。
* 受影响请求字段：`address.street_address`、`address.city`、`address.state`。Create Payout 使用内联受益人信息时，对应字段为 `beneficiary.address.street_address`、`beneficiary.address.city`、`beneficiary.address.state`。
* 这些字段的非空值必须匹配正则 `^[A-Za-z0-9\s\-_().,:@#~!$%^&*+={}\[\]\\|"'<>?/・……]+$`。该正则允许英文字母、数字、空白字符，以及以下符号：`_ - ( ) . , : @ # ~ ! $ % ^ & * + = { } [ ] \ | " ' < > ? / ・ ……`。
* 空字符串和未传字段会跳过字符正则校验；该字段是否必填，仍由对应接口和 payout 场景已有的必填规则决定。
* 本次将校验范围从此前的 SGD/SG 特定场景扩大到所有币种和支付方式。`country`、`postal_code` 以及非 SGD/SG 场景下的 `bank_details.account_holder` 校验不变。[Check Beneficiary](https://developers-sandbox.uqpaytech.com/docs/zh/global-account/v1.6/api-reference/check-beneficiary.md) 不受影响。

## Card Issuance

**\[NEW] 商户维度风控**

* 受影响接口：[Create Card](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/create-card.md)、[Update Card](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/update-card.md)、[List Cards](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/list-cards.md)、[Retrieve Card](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/retrieve-card.md)。
* `risk_controls` 新增两个可选字段 `allowed_merchants` 和 `blocked_merchants`，各接收一组商户编码，用于限制卡片可交易的商户：白名单会拒绝列表以外的所有商户，黑名单只拒绝列表内的商户。
* 新增接口 [List Merchant Brands](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/list-merchant-brands.md) 用于查询这两个字段可接受的商户编码。可按 `display_name`（大小写不敏感的前缀匹配）或 `merchant_code`（精确匹配）过滤——两者至少填一个，因此无法列出全量商户目录。
* 每张卡只能配置 `allowed_merchants` 或 `blocked_merchants` 之一，且列表不得超过 20 条。商户风控与 `allowed_mcc` / `blocked_mcc` 相互独立，同一张卡可以同时配置 MCC 规则和商户规则。
* 调用 Update Card 时，不传该字段表示保持原值不变；传空数组表示清空。
* 仅 Business Visa 支持。详见 [Spending controls](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/spending-controls.md) 和 [Card products](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/card-products.md)。
* 向后兼容——已有卡片在未显式配置前不受影响。

**2026-07-10 (Upcoming Change)**

## Card Issuance

**\[Postponed] \[BREAKING] 第三方 Enhanced KYC 新增必填字段 `documents`**

> [!WARNING]
>
> **已暂缓。** 原定 2026-07-10 的生效日期不再适用。本次改动暂缓，届时不会在该日期生效 —— 你当前无需做任何调整。新的生效日期将在此处另行公告后再生效。

* 受影响接口：[Create Cardholder](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/create-cardholder.md)、[Update Cardholder](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/update-cardholder.md)。凡在 `ENHANCED` KYC 等级提交 `kyc_verification` 处均适用。
* 当 `kyc_verification.method` 为 `THIRD_PARTY` 时，`kyc_verification.kyc_proof` 新增必填数组 `documents`，用于承载验证背后的合规报告文件。每一项引用一个通过 [Upload A File](https://developers-sandbox.uqpaytech.com/docs/zh/account-center/v1.6/api-reference/upload-file.md) 上传的文件，并声明其 `report_type`：
  * `IDV` —— 仅身份验证报告。
  * `AML` —— 仅反洗钱筛查报告。
  * `IDV_AML` —— 一份文件同时覆盖两者。
* 必须包含一份身份验证报告 —— 单独的 `IDV` 报告或合并的 `IDV_AML` 均可；`AML` 报告为可选。报告可拆成两份文件（`IDV` 加 `AML`）分开上送，也可用一份合并文件（`IDV_AML`）上送。
* 这是一个非兼容（breaking）改动：一旦生效，`THIRD_PARTY` 请求若缺少身份验证报告会被拒绝。请在新的生效日期（将在此处另行公告）之前更新相关逻辑。
* 完整流程见 [Enhanced KYC Card Issuance](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/enhanced-kyc-card-issuance.md)。

**2026-07-09**

## Card Issuance

**新增接口：Claim Unsolicited Refund（认领无源退款）**

* 新增接口：[Claim Unsolicited Refund](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/claim-unsolicited-refund.md) —— `POST /v1/issuing/transactions/unsolicited_refund/release`。仅支持 Business Visa Card。
* 当针对原授权交易的商户退款迟迟未到账时使用。返回 `SUCCESS` 仅表示申请已受理并进入异步处理，不代表退款已入账。
* 失败原因见 [错误码](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/error-codes.md#transaction-errors)。

**授权决策请求新增 `pos_env` 与 `eci` 字段**

* 受影响流程：[Authorization decisions](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/authorization-decisions.md) —— UQPAY 发送到你端点的解密后请求体。
* 新增两个透传字段，便于你区分一笔授权是常规消费还是订阅（recurring）扣费，从而做差异化风控与展示：
  * `pos_env` —— POS 环境：`C` credential on file、`I` 分期、`R` 周期性。
  * `eci` —— 邮购/电话、电商及支付标识（`00`–`08`）；`02` 表示周期性交易。
* 向后兼容 —— 仅为新增字段。完整取值表见指南。

**List Card Arts 新增 `product_id` 筛选参数**

* 受影响接口：[List Card Arts](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/list-card-arts.md)。
* 可选 query 参数 `product_id`，将返回的 card art 筛选为该卡产品可用的部分。不传则维持现状 —— 返回账户可用的全部 card art。
* 向后兼容 —— 新增的可选参数。

**2026-07-02**

## Account Center

**\[BREAKING] 创建个人类型 SubAccount 时新增两个必填字段 `gender` 与 `annual_income`**

* 受影响接口：[Create SubAccount](https://developers-sandbox.uqpaytech.com/docs/zh/account-center/v1.6/api-reference/create-sub-account.md)
* 当 `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`。

> [!NOTE]
>
> 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](https://developers-sandbox.uqpaytech.com/docs/zh/stablecoin-account/v1.6/api-reference/create-deposit-sender.md) —— 为到账充值提交发起方（来源方）的 Travel Rule 数据，使该笔以及后续来自相同来源地址的充值得以继续处理。
* 充值 Webhook（`ramp.deposit.pending`）新增 `need_travel_rule`，仅当该笔充值确需补填来源 Travel Rule 才能继续处理时出现且为 `true`。收到后以该笔充值的 `from_address` 调用 Submit Deposit Sender Travel Rule。
* [List Address Book](https://developers-sandbox.uqpaytech.com/docs/zh/stablecoin-account/v1.6/api-reference/list-address-book.md) 新增可选查询参数 `address_kind`（默认 `whitelist`，或 `deposit_sender`），用于查看已补录的充值来源条目。
* 三项改动均向后兼容 —— 新增接口、新增可选参数，以及一个按需才出现的字段。

**2026-06-11**

## Account Center

**\[UPDATE] 入驻 RFI Webhook 新增 `required_documents` 与 `reason` 字段**

* 受影响 Webhook：[Onboarding RFI](https://developers-sandbox.uqpaytech.com/docs/zh/account-center/v1.6/webhooks/onboarding-rfi.md)
* `rfi.action_required` 通知体现在包含 `required_documents`（合规所需的证件类型代码）与 `reason`（说明本次 RFI 触发原因的自由文本）。
* 你可以直接从通知中读取所需材料，无需先调用 [Retrieve RFI](https://developers-sandbox.uqpaytech.com/docs/zh/account-center/v1.6/api-reference/retrieve-rfi.md)。
* 向后兼容 —— 忽略新字段的既有处理逻辑维持原有行为。

**2026-06-05**

## Issuing

**\[UPDATE] 收紧 `residential_address` 字段的字符校验**

* 受影响接口：[Create Cardholder](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/create-cardholder.md)、[Update Cardholder](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/update-cardholder.md)、[Create Card](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/create-card.md)（通过 `cardholder_required_fields` 一步开卡）
* `residential_address` 的所有字段（`line1`、`line2`、`city`、`state`、`postal_code` 等）现在仅接受大小写字母（A-Z、a-z）、数字（0-9）、空格及以下标点：`, . ' / # ( ) - &`。
* 包含其他任意字符（例如 `;`）的请求会被拒绝 —— 修正后可重新提交。空的可选字段不参与校验。
* 本次为校验收紧：此前可通过的值现在可能被拒绝。如果你在地址字段中传入上述以外的字符，请检查你的集成。

**2026-06-04**

## Issuing

**\[NEW] Standard 虚拟卡 PIN 管理**

* 新增接口：[Set or Reset Virtual Card PIN](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/manage-card-pin.md)
* 为 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](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/reset-pin.md) 维持原有行为。

**2026-05-22**

## Issuing

**\[NEW] 卡面 —— 选择 Enhanced 虚拟卡在 Apple Wallet 与 Google Wallet 中展示的设计**

* **适用范围：** 在 Apple Wallet 与 Google Wallet 中渲染，仅适用于已添加到 Apple Pay 或 Google Pay 的 Enhanced 虚拟卡。不会展示在你自己的 UI 或实体卡上 —— 参见新增的 [卡面指南](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/card-art.md) 了解解析顺序与限制。
* 新增接口：[List Card Arts](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/list-card-arts.md)、[Set Default Card Art](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/set-default-card-art.md)
* 影响接口：[Create Card](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/create-card.md)、[Update Card](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/update-card.md) —— 请求体新增可选字段 `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` —— 参见 [错误码](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/error-codes.md)。
* 向后兼容 —— 未传 `card_art_id` 的现有集成正常工作，自动使用账户默认卡面。

**2026-05-21**

## Issuing

**\[UPDATE] Elevate Per-Transaction Limit 接口的 `duration_in_days` 范围扩展**

* 影响接口：[Elevate Per-Transaction Limit](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/elevate-card-limit.md)
* `duration_in_days` 字段现支持 `1`–`14`（此前为 `1`–`7`）；默认值由 `7` 调整为 `14`。

**2026-05-20**

## Global Acquiring

**\[NEW] Create PaymentIntent 新增 `customer` 与 `customer_id` 字段**

* 影响接口：[Create PaymentIntent](https://developers-sandbox.uqpaytech.com/docs/zh/global-acquiring/v1.6/api-reference/create-payment-intent.md)
* 请求体新增可选字段 `customer`（内联对象）和 `customer_id`；响应中相应新增顶层 `customer_id` 与 `customer`。
* 客户对象新增可选 `external_customer_id` 字段，便于商户携带自有客户标识。
* 这两个字段用于在托管支付页上启用 Card on File。
* 向后兼容 —— 未传这些字段的现有集成无需调整。

**2026-05-15**

## Issuing

**\[NEW] 临时提升单笔交易限额**

* 新增接口：[Elevate Per-Transaction Limit](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/elevate-card-limit.md)
* 新增 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`](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/webhooks/card-elevate-limit) 或 [`card.elevate_limit.failed`](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/webhooks/card-elevate-limit) Webhook 推送。
* 仅对特定卡 BIN 开放 —— 如需启用，请联系 UQPAY。

**2026-05-14**

## Issuing

**\[NEW] ASAF 网络保护（Network Protection）—— 将丢失、被盗、注销的 Visa 卡上报至卡组织网络**

* 新增接口：[Enroll Card in Network Protection](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/enroll-card-network-protection.md)、[Remove Card from Network Protection](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/remove-card-network-protection.md)
* 新增 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](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/retrieve-card.md)、[List Cards](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/list-cards.md) 的响应体中，每张卡新增 `network_protection` 对象。
* 使用 ASAF action code（`04`、`41`、`43`、`46`、`54`）注册卡片后，Visa 处理完成即可在卡组织网络层面统一拒绝该卡的授权请求。移除接口则将卡片重新撤出网络保护。
* 注册与移除均为异步流程 —— API 响应仅确认请求受理，最终结果通过生命周期 Webhook 推送。费用扣款通过 enrollment-fee 与 maintenance-fee 两个 Webhook 单独下发。
* **仅支持 Visa 卡。** 向后兼容 —— 未启用该功能的现有集成无需调整。

**2026-05-08**

## Issuing

**\[NEW] 单卡 3DS 注册控制字段 `enable_3ds`**

* 影响接口：[Create Card](https://developers-sandbox.uqpaytech.com/docs/card-issuance/v1.6/api-reference/create-card.md)、[Update Card](https://developers-sandbox.uqpaytech.com/docs/card-issuance/v1.6/api-reference/update-card.md)、[Retrieve Card](https://developers-sandbox.uqpaytech.com/docs/card-issuance/v1.6/api-reference/retrieve-card.md)、[List Cards](https://developers-sandbox.uqpaytech.com/docs/card-issuance/v1.6/api-reference/list-cards.md)
* 影响 webhook：`card.create.succeeded`、`card.update.succeeded`
* `risk_controls` 下新增 `enable_3ds` 字段，控制卡片是否注册 3DS。配合既有的 `allow_3ds_transactions` 完整控制 3DS 行为 —— 详见更新后的 [3D Secure 指南](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/3d-secure.md)。
* 仅 Visa BIN 支持。卡片在 `PENDING` 或 `ACTIVE` 状态时可修改。
* 仅在卡片显式设置过该字段时返回。未设置时，卡片继承 Account 级 3DS 配置。
* 向后兼容 —— 未传入 `enable_3ds` 的现有集成无需调整。

**2026-05-07**

## Issuing

**\[BREAKING] 安全 Iframe 渲染行为变更**

[安全 Iframe](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/secure-iframe-guide.md) 集成模式将上线一组布局与控件调整。即使你不更新任何客户端代码，已有集成的渲染效果也可能发生明显变化。建议在生产发布前先在沙盒中验证渲染效果。

* 生效时间：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 集成指南](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/secure-iframe-guide.md)。

***

**\[NEW] 安全 Iframe 新增 `show_data` URL 参数**

在[安全 Iframe](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/secure-iframe-guide.md) URL 上传 `show_data=true`，可在加载时直接展示卡号、有效期与 CVV，无需用户操作。默认值：`false`。仅推荐在受信任环境下使用。

***

**\[NEW] 安全 Iframe 新增 `cardholder_name` URL 参数**

在[安全 Iframe](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/secure-iframe-guide.md) URL 上传 `cardholder_name=true`，可渲染持卡人姓名字段。默认值：`false`（隐藏）。向后兼容。

***

**\[ENHANCED] 安全 Iframe `styles` 新增选择器与属性**

[安全 Iframe](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/secure-iframe-guide.md) 的 `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` —— 可用于标签/取值的对齐控制。

**2026-04-24**

## Issuing

**\[NEW] 一步发卡 —— 单次调用同时创建持卡人与卡片**

* 影响接口：[Create Card](https://developers-sandbox.uqpaytech.com/docs/card-issuance/v1.6/api-reference/create-card.md)（请求与响应）
* `cardholder_id` 改为可选。当不传该字段时，提供完整的 `cardholder_required_fields` 字段块，系统会在同一次请求中创建持卡人并发卡。
* 向后兼容 —— 已有集成继续传 `cardholder_id` 时行为不变。
* 完整集成流程见[一步发卡指南](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/one-step-card-issuance.md)。

***

**\[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](https://developers-sandbox.uqpaytech.com/docs/card-issuance/v1.6/api-reference/create-cardholder.md)
* 现可成功创建使用科索沃（ISO 3166-1 alpha-2 `XK`、alpha-3 `XKX`）手机号的持卡人。
* 国家代码：`+383`。手机号长度（不含国家代码）：8–9 位。
* 完整国家清单见[持卡人手机号校验规则](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/phone-number-validation-rules-for-cardholder.md)。

**2026-04-16**

## 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 格式。

**2026-04-02**

## Acquiring

**\[ENHANCED] Create Payout：新增 `payout_account_id` 字段，支持站内账户出款**

出款创建接口现支持可选的 `payout_account_id` 参数，商户可将出款资金转入 UQPAY 站内账户，而非预配置的外部银行账户。

* 影响接口：[Create Payout](https://developers-sandbox.uqpaytech.com/docs/global-acquiring/v1.6/api-reference/create-payout.md)（请求）
* 变更内容：
  * 请求体新增可选字段 `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` —— 持卡人信息已更新

**2026-03-26**

## Acquiring

**\[BREAKING] API 响应结构调整：卡交易新增风控与认证字段**

* 影响接口（仅响应）：[Create PaymentIntent](https://developers-sandbox.uqpaytech.com/docs/global-acquiring/v1.6/api-reference/create-payment-intent.md)、[Retrieve PaymentIntent](https://developers-sandbox.uqpaytech.com/docs/global-acquiring/v1.6/api-reference/retrieve-payment-intent.md)、[Update PaymentIntent](https://developers-sandbox.uqpaytech.com/docs/global-acquiring/v1.6/api-reference/update-payment-intent.md)、[Confirm PaymentIntent](https://developers-sandbox.uqpaytech.com/docs/global-acquiring/v1.6/api-reference/confirm-payment-intent.md)、[Capture PaymentIntent](https://developers-sandbox.uqpaytech.com/docs/global-acquiring/v1.6/api-reference/capture-payment-intent.md)、[Cancel PaymentIntent](https://developers-sandbox.uqpaytech.com/docs/global-acquiring/v1.6/api-reference/cancel-payment-intent.md)、[List PaymentIntents](https://developers-sandbox.uqpaytech.com/docs/global-acquiring/v1.6/api-reference/list-payment-intents.md)、[Retrieve PaymentAttempt](https://developers-sandbox.uqpaytech.com/docs/global-acquiring/v1.6/api-reference/retrieve-payment-attempt.md)、[List PaymentAttempts](https://developers-sandbox.uqpaytech.com/docs/global-acquiring/v1.6/api-reference/list-payment-attempts.md)
* 变更内容：
  * 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`（结构同上）

***

**\[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-20**

## 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 请求关联说明（已被取代）**

本条历史记录中的请求关联行为已被 [2026-09-03 虚拟账户申请合同](#2026-09-03)取代。Create 请求现使用必填幂等键，application 响应和事件使用 `application_id` 与 `public_version` 关联。

## 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

**2026-02-27**

## 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` 字段不再必填。

**2026-01-29**

## 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 过滤
* 所有参数均为可选，可单独使用或任意组合。

**2026-01-08**

## Acquiring

**\[NEW] 银行账户管理 API**

新增四个用于管理收单结算银行账户的接口：

* Create Bank Account
* Retrieve Bank Account
* Update Bank Account
* List Bank Accounts

注意事项：

* 每个币种只能配置一个结算银行账户。
* 已创建的银行账户不可删除。

## Issuing

**\[NEW] 授权决策能力**

合作方现可对卡交易实现实时授权决策逻辑：通过部署 Webhook 服务接收 UQPAY 下发的授权请求即可。

**2025-12-26**

## 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` 字段已废弃，将被移除。

**2025-12-04**

## Acquiring

**\[ENHANCED] 3DS 场景下 `browser_info.mobile` 校验放宽**

* 影响接口：Create PaymentIntent（请求）、Confirm PaymentIntent（请求）
* `browser_info.mobile` 现仅在客户端为移动端时必填。3DS 场景下 PC web 客户端不再要求此字段。

**2025-11-27**

## Acquiring

**\[ENHANCED] Payment Intent 与 Payment Attempt Webhook 新增静态二维码字段**

* 影响 Webhook：`acquiring.payment_intent.*`、`acquiring.payment_attempt.*`
* Webhook 通知体新增字段 `static_qrcode`、`static_qrcode_extension`、`static_qrcode_number_plate`。
* 这些字段仅在静态二维码支付场景下返回。

**2025-11-13**

## 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` 类型的支持。

**2025-10-30**

## 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"
}
```

**2025-10-23**

## Acquiring

**`ip_address` 字段在 PaymentIntent 中提升至顶层**

* 影响接口：Create PaymentIntent（请求）、Confirm PaymentIntent（请求）
* `browser_info.ip_address` 提升至顶层（与 `payment_method` 同级）。
* 当 `payment_method.card.three_ds_action = enforce_3ds` 时，`ip_address` **必填**。

**2025-10-16**

## 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。

**2025-09-26**

## Account Center

**\[ENHANCED] TPSP 主账户下子账户创建增强**

* 影响接口：Create SubAccount（请求）
* 公司类实体新增 `ownership_details.representatives.face_docs`。
* 个人类实体新增 `identity_verification.face_docs`。
* 两类实体均新增 `tos_acceptance.tos_agreement`（可选；置为 `1` 表示自动签署 TPSP 服务条款）。
* 在 TPSP 主账户下创建子账户时，`face_docs` 必填。
* 公司类实体：至少一名具备特定职位的代表人需提供人脸验证文件。

**2025-09-18**

## Acquiring

**\[NEW] 账户余额与出款接口**

发布 5 个新接口：

* Retrieve Balance
* List Balances
* Create Payout
* Retrieve Payout
* List Payouts —— 出款状态实时更新可通过 Webhook 接收。

**2025-09-11**

## 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` 时触发。

**2025-09-05**

## 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`。

**2025-08-28**

## 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` 字段，表示已使用的累计卡片限额。

**2025-08-21**

## 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 变更。

**2025-08-14**

## 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 卡行为不变。

**2025-08-07**

## 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` 字段，可携带自定义引用号。

**2025-07-31**

## 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 代理标识。

**2025-07-24**

## 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"`。

**2025-07-19**

## 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。

**2025-07-10**

## Acquiring

**\[NEW] `acquiring.payment_intent.failed` Webhook**

* 当 Payment Intent 因到期被自动关闭时触发。
* 手动取消的订单不触发此事件。
* 在控制台订阅该事件即可接收。

## Issuing

**\[ENHANCED] `transaction_status` 新增 `PENDING` 状态**

* 影响接口：List Cards Transactions（响应）、Retrieve Cards Transaction（响应）
* `transaction_status` 新增合法取值 `PENDING`。

**2025-07-04**

## 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 格式。

**2025-06-26**

## 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`）因卡产品而异。

**2025-06-19**

## Issuing

**\[NEW] 卡交易接口与报表新增 `wallet_type` 字段**

* 影响接口：List Cards Transactions（响应）、Retrieve Cards Transaction（响应）
* 影响 Webhook：`issuing.transaction.*`
* 影响报表：Card Transactions Report、Card Settlement Report
* 新增 `wallet_type` 字段，标识所使用的数字钱包（如 `ApplePay`、`GooglePay`）。

**2025-06-18**

## Acquiring

**\[BREAKING] Webhook 事件类型由 `acquiring.payment.*` 重命名为 `acquiring.payment_intent.*`**

***

**\[NEW] `acquiring.payout.created` Webhook** —— 商户发起出款请求时触发。

**\[NEW] `acquiring.refund.created` Webhook** —— 商户发起退款请求时触发。

**2025-06-12**

## 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`，标识事件发生时刻的卡可用余额。

**2025-06-05**

## 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 管理员锁定；解锁需提交正式邮件申请。

**2025-05-29**

## 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 交易金额上限。

**2025-05-28**

## 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`。其余类型暂不支持。

**2025-05-23**

## 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 交易最大允许金额。

**2025-05-21**

## Acquiring

Acquiring API 首次正式发布。本版本提供 Payment Intents、Payment Attempts、Refunds 与 Webhook 通知能力。

**2025-05-16**

## 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"]`）。

**2025-05-15**

## Issuing

**\[NEW] Cardholder 接口新增 `number_of_cards` 字段**

* 影响接口：List Cardholders（响应）、Retrieve Cardholder（响应）
* 新增 `number_of_cards` 字段。

**2025-05-14**

## Issuing

**\[BREAKING] `x-on-behalf-of` 请求头必须为合法 UUID**

* 影响接口：所有支持 `x-on-behalf-of` 请求头的接口
* 若传入，该值必须是对应已存在子账户的合法 UUID。非法值将被拒绝。

**2025-04-25**

## Issuing

**\[BREAKING] Activate Card 新增必填字段 `pin`**

* 影响接口：`POST /api/v1/issuing/cards/activate`（请求）
* 新增必填字段 `pin`。
* 新增可选字段 `no_pin_payment_amout`。
* 该变更为破坏性变更，已有集成必须更新以包含 `pin` 字段。

**2025-04-18**

## Issuing

**\[NEW] Create Card 与 Update Card 新增 3DS 控制**

* 影响接口：`POST /api/v1/issuing/cards`、`POST /api/v1/issuing/cards/{id}`
* 新增可选字段 `risk_controls`。向后兼容 —— 已有卡片在未显式配置时不受影响。

**2025-04-17**

## Banking

**\[NEW] 汇率接口**

* 新增接口：`GET /api/v1/exchange/rates`
* 返回当前汇率。仅供参考 —— 锁汇请使用 Create Quote 接口。

**2025-04-15**

## 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`。向后兼容。

**2024-07-20**

## 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` —— 模拟向全球账户充值（仅沙盒）
* 描述与参数限制的文档修正。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.