> ## Documentation Index
> Fetch the complete documentation index at: https://developer.utgl.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Changelog

> Latest updates and announcements for the UTGL Developer Portal

<Update label="August 2026" description="v1.4.8">
  ## API Enhancements

  **Card Account `xid` Now Included in Client Identity Webhooks**

  The two client identity result webhooks now carry the card account's `xid` — your own reference for that card account — so you can reconcile KYC outcomes against your records without a follow-up lookup.

  ### What's New

  **`data.xid`** — a nullable `string` added to both events:

  * `cardaccount.client-identity.approved`
  * `cardaccount.client-identity.rejected`

  The value is the `xid` of the same card account identified by `data.cardAccountId`. It is `null` when that card account has no `xid`.

  This is an **additive** change. Event names and all existing fields are unchanged, and the events are still delivered when `xid` is absent.

  ### Example Payload — `cardaccount.client-identity.approved`

  ```json theme={null}
  {
    "id": "6b4332cd-0738-48fc-acbe-17f4edbcdcd7",
    "event": "cardaccount.client-identity.approved",
    "data": {
      "cardAccountId": "a857911b-d9c3-491a-98a7-a27c071d932d",
      "xid": "cobrander-card-account-123"
    },
    "time": "2025-01-16T08:02:14.413Z"
  }
  ```

  ### Example Payload — `cardaccount.client-identity.rejected`

  ```json theme={null}
  {
    "id": "49f85bf3-f616-4a9f-8aaa-564d900ee829",
    "event": "cardaccount.client-identity.rejected",
    "data": {
      "cardAccountId": "05a3881a-568e-45f3-b601-8601064ae3d5",
      "xid": "cobrander-card-account-456",
      "rejectedReason": "Invalid ID (expired doc)",
      "rejectionAdditionalInfo": "Please upload valid hotel booking information."
    },
    "time": "2025-01-16T08:19:22.350Z"
  }
  ```

  ### Action Suggested

  * If your webhook consumer uses a strict JSON decoder that rejects unknown fields, allow the new `xid` field before it reaches you.
  * If you set `xid` when creating card accounts, key your KYC reconciliation on `data.xid` instead of resolving `cardAccountId` through an extra API call.
  * Historical events are not backfilled or resent — only events generated after this release carry `xid`.

  📚 [Guide: Webhook Events →](/issuing/guides/webhook-events-1)

  ***

  ## API 增強

  **客戶身份 Webhook 現已包含卡賬戶 `xid`**

  兩個客戶身份結果 Webhook 現已帶有卡賬戶的 `xid`（即您自訂的卡賬戶參考編號），讓您無需額外查詢即可將 KYC 結果與自身記錄對賬。

  ### 新增內容

  **`data.xid`** — 於以下兩個事件新增的可為 `null` 的 `string` 欄位：

  * `cardaccount.client-identity.approved`
  * `cardaccount.client-identity.rejected`

  此值為 `data.cardAccountId` 所指向的同一卡賬戶的 `xid`。若該卡賬戶沒有 `xid`，則為 `null`。

  此為**新增性**變更。事件名稱及所有現有欄位維持不變，即使 `xid` 不存在，事件仍會照常派送。

  ### 載荷範例 — `cardaccount.client-identity.approved`

  ```json theme={null}
  {
    "id": "6b4332cd-0738-48fc-acbe-17f4edbcdcd7",
    "event": "cardaccount.client-identity.approved",
    "data": {
      "cardAccountId": "a857911b-d9c3-491a-98a7-a27c071d932d",
      "xid": "cobrander-card-account-123"
    },
    "time": "2025-01-16T08:02:14.413Z"
  }
  ```

  ### 載荷範例 — `cardaccount.client-identity.rejected`

  ```json theme={null}
  {
    "id": "49f85bf3-f616-4a9f-8aaa-564d900ee829",
    "event": "cardaccount.client-identity.rejected",
    "data": {
      "cardAccountId": "05a3881a-568e-45f3-b601-8601064ae3d5",
      "xid": "cobrander-card-account-456",
      "rejectedReason": "Invalid ID (expired doc)",
      "rejectionAdditionalInfo": "Please upload valid hotel booking information."
    },
    "time": "2025-01-16T08:19:22.350Z"
  }
  ```

  ### 建議行動

  * 如果您的 Webhook 接收端使用嚴格的 JSON 解析器並會拒絕未知欄位，請先容許新的 `xid` 欄位。
  * 如果您在建立卡賬戶時設定了 `xid`，請直接以 `data.xid` 進行 KYC 對賬，無需再透過額外 API 呼叫解析 `cardAccountId`。
  * 過往事件不會補發或重送 — 僅此版本發布後產生的事件會帶有 `xid`。

  📚 [指南：Webhook 事件 →](/issuing/guides/webhook-events-1)
</Update>

<Update label="June 2026" description="v1.4.7">
  ## API Enhancements

  **Card Dispute Fields Now Exposed**

  Card account and transaction payloads now surface dispute information so cobranders can display dispute state to cardholders and react to dispute lifecycle events.

  ### What's New

  **`CardAccount.disputeAmount`** — a `number` field on every card account response.

  * The total amount currently under dispute, denominated in the card account currency.
  * Returns `0` when there is no disputed amount.

  **`CardAccountTransaction.disputeStatus`** — a nullable `string` field on every card account transaction.

  * Possible values: `requested`, `pending`, `success`, `failed`, `reported`, or `null` (not disputed).

  ### Webhook Behavior

  The `cardaccount.transaction.updated` webhook now **also fires when a transaction's dispute status changes** (previously fired only on transaction status transitions such as `pending → posted`). The webhook payload's `data.disputeStatus` carries the latest value.

  ### Example Response — `GET /cardaccounts/transactions?cardAccountId=...`

  ```json theme={null}
  {
    "id": "...",
    "description": "UBER * PENDING Amsterdam NLD",
    "disputeStatus": "pending",
    "grossAmount": 1000
  }
  ```

  ### Example Response — `GET /cardaccounts`

  ```json theme={null}
  {
    "id": "...",
    "balance": 10000.25,
    "outstanding": 7500.50,
    "disputeAmount": 250.00,
    "available": 825.30
  }
  ```

  ### Action Suggested

  * If your UI surfaces card account balances, consider showing `disputeAmount` alongside `balance` / `outstanding` so users see funds locked in dispute review.
  * If you subscribe to `cardaccount.transaction.updated`, branch on `data.disputeStatus` to react to dispute lifecycle (e.g. notify the user when a dispute completes).

  📚 [API Reference: List Card Account Transactions →](/issuing/api-reference/card-accounts/get-card-account-transactions)
  📚 [Guide: Webhook Events →](/issuing/guides/webhook-events-1)

  ***

  ## API 增強

  **新增卡片爭議資料欄位**

  卡賬戶與交易回應現已提供爭議資訊，方便聯名銀行向持卡人展示爭議狀態並對爭議生命週期事件作出回應。

  ### 新增內容

  **`CardAccount.disputeAmount`** — 每個卡賬戶回應中的 `number` 欄位。

  * 以卡賬戶幣種計算的目前爭議中總金額。
  * 沒有爭議金額時返回 `0`。

  **`CardAccountTransaction.disputeStatus`** — 每筆卡賬戶交易上的可為 `null` 的 `string` 欄位。

  * 可能的值：`requested`、`pending`、`success`、`failed`、`reported`,或 `null`（非爭議）。

  ### Webhook 行為

  `cardaccount.transaction.updated` Webhook **現在也會在交易爭議狀態變更時觸發**（過去僅在交易狀態轉換如 `pending → posted` 時觸發）。Webhook 載荷中的 `data.disputeStatus` 會帶有最新值。

  ### 響應範例 — `GET /cardaccounts/transactions?cardAccountId=...`

  ```json theme={null}
  {
    "id": "...",
    "description": "UBER * PENDING Amsterdam NLD",
    "disputeStatus": "pending",
    "grossAmount": 1000
  }
  ```

  ### 響應範例 — `GET /cardaccounts`

  ```json theme={null}
  {
    "id": "...",
    "balance": 10000.25,
    "outstanding": 7500.50,
    "disputeAmount": 250.00,
    "available": 825.30
  }
  ```

  ### 建議行動

  * 如果您的介面顯示卡賬戶餘額，請考慮在 `balance` / `outstanding` 旁邊顯示 `disputeAmount`，以便使用者看到因爭議審核而鎖定的金額。
  * 如果您已訂閱 `cardaccount.transaction.updated`，請根據 `data.disputeStatus` 進行分支處理，以對爭議生命週期作出回應（例如在爭議完成時通知使用者）。

  📚 [API 參考：卡賬戶交易列表 →](/issuing/api-reference/card-accounts/get-card-account-transactions)
  📚 [指南：Webhook 事件 →](/issuing/guides/webhook-events-1)
</Update>

<Update label="May 2026" description="v1.4.6">
  ## Important Update

  **Card Endpoints: Business Errors Now Return HTTP 400**

  Seven card endpoints have been fixed so that **known business-state errors now return `HTTP 400 Bad Request`** with a typed `code` field, instead of `HTTP 500`. Genuine upstream/system failures continue to return `HTTP 500`. This change is live in production.

  ### Affected Endpoints and Error Codes

  | Endpoint                 | Business errors now returned as `400`                             |
  | ------------------------ | ----------------------------------------------------------------- |
  | `POST /cards/change-pin` | `INACTIVE_CARD`, `CARD_NOT_ISSUED`, `CARD_NUMBER_MISMATCH`        |
  | `POST /cards/activate`   | `UNPENDING_CARD`, `CARD_NUMBER_MISMATCH`, `CARD_EXPIRY_MISMATCH`  |
  | `POST /cards/lock`       | `CARD_ALREADY_LOCKED`, `INACTIVE_CARD`, `CARD_NUMBER_MISMATCH`    |
  | `POST /cards/unlock`     | `ERROR_UNLOCK_CARD_STATUS_INVALID`, `CARD_NUMBER_MISMATCH`        |
  | `POST /cards/suspend`    | `CARD_ALREADY_SUSPENDED`, `INACTIVE_CARD`, `CARD_NUMBER_MISMATCH` |
  | `POST /cards/unsuspend`  | `UNSUSPENDED_CARD`, `CARD_NUMBER_MISMATCH`                        |
  | `POST /cards/cancel`     | `CARD_ALREADY_CANCELLED`                                          |

  Any other failure on these endpoints (e.g. an upstream card processor error) continues to return `HTTP 500` with a generic error body.

  ### Action Required

  <Warning>
    This change is **already live in production**. If your integration treats `5xx` responses as retryable or transient, update your error handling now so that the business error codes above are handled as permanent `4xx` validation failures (do **not** retry).
  </Warning>

  * **Before**: business errors such as `CARD_ALREADY_LOCKED` leaked through as `HTTP 500`.
  * **After**: the same errors return `HTTP 400` with a structured body containing the error `code` — branch on `code`, not on the HTTP status alone.

  ### Example Response (After)

  ```json theme={null}
  {
    "statusCode": 400,
    "code": "CARD_ALREADY_LOCKED",
    "message": "Card is already locked"
  }
  ```

  ### Recommended Client Handling

  Branch on the **HTTP status**, not on individual `code` values. Use `body.code` for user-facing messages or telemetry — not for retry decisions.

  ```ts theme={null}
  if (response.status === 400) {
    // Permanent: caller mistake or card state issue.
    // Do NOT retry. Show body.message to the user;
    // log body.code for support / analytics.
    showError(body.message);
    logger.warn("card_op_rejected", { code: body.code });
  } else if (response.status >= 500) {
    // Upstream / system error. Response body is generic (no `code`).
    // Retry with the SAME `idempotencyKey` and exponential backoff
    // (cap the attempts). Treat network/timeout errors the same way.
    retryWithBackoff(request);
  }
  ```

  The full list of 400 `code` values is in the table above — useful when mapping each code to a localized user message in your UI.

  📚 [API Reference: Cards →](/issuing/api-reference/cards/activate-card)

  ***

  ## 重要更新

  **卡片端點：業務錯誤現在返回 HTTP 400**

  七個卡片端點已修正，**已知的業務狀態錯誤現在會返回 `HTTP 400 Bad Request`**，並附帶具類型的 `code` 欄位，而不再返回 `HTTP 500`。真正的上游或系統錯誤仍會返回 `HTTP 500`。此變更已於生產環境上線。

  ### 受影響的端點與錯誤碼

  | 端點                       | 現在以 `400` 返回的業務錯誤                                               |
  | ------------------------ | --------------------------------------------------------------- |
  | `POST /cards/change-pin` | `INACTIVE_CARD`、`CARD_NOT_ISSUED`、`CARD_NUMBER_MISMATCH`        |
  | `POST /cards/activate`   | `UNPENDING_CARD`、`CARD_NUMBER_MISMATCH`、`CARD_EXPIRY_MISMATCH`  |
  | `POST /cards/lock`       | `CARD_ALREADY_LOCKED`、`INACTIVE_CARD`、`CARD_NUMBER_MISMATCH`    |
  | `POST /cards/unlock`     | `ERROR_UNLOCK_CARD_STATUS_INVALID`、`CARD_NUMBER_MISMATCH`       |
  | `POST /cards/suspend`    | `CARD_ALREADY_SUSPENDED`、`INACTIVE_CARD`、`CARD_NUMBER_MISMATCH` |
  | `POST /cards/unsuspend`  | `UNSUSPENDED_CARD`、`CARD_NUMBER_MISMATCH`                       |
  | `POST /cards/cancel`     | `CARD_ALREADY_CANCELLED`                                        |

  這些端點上的其他錯誤（例如上游卡片處理器錯誤）仍會以 `HTTP 500` 配合通用錯誤主體返回。

  ### 需要採取的行動

  <Warning>
    此變更**已於生產環境上線**。如果您的整合將 `5xx` 響應視為可重試或暫時性錯誤，請立即更新錯誤處理邏輯，將上述業務錯誤碼視為永久性的 `4xx` 驗證錯誤（**請勿**重試）。
  </Warning>

  * **修正前**：例如 `CARD_ALREADY_LOCKED` 之類的業務錯誤會以 `HTTP 500` 形式返回。
  * **修正後**：相同錯誤會以 `HTTP 400` 返回，並在響應主體中包含結構化的 `code` 欄位 — 請根據 `code` 進行分支處理，而非僅依賴 HTTP 狀態碼。

  ### 響應範例（修正後）

  ```json theme={null}
  {
    "statusCode": 400,
    "code": "CARD_ALREADY_LOCKED",
    "message": "Card is already locked"
  }
  ```

  ### 建議的客戶端處理方式

  請以 **HTTP 狀態碼**作為分支判斷依據，而非個別的 `code` 值。`body.code` 應用於使用者訊息或紀錄分析 — 而非作為重試判斷的依據。

  ```ts theme={null}
  if (response.status === 400) {
    // 永久性錯誤：呼叫方或卡片狀態問題。
    // 請勿重試。將 body.message 顯示給使用者；
    // 將 body.code 記錄以便客服或分析使用。
    showError(body.message);
    logger.warn("card_op_rejected", { code: body.code });
  } else if (response.status >= 500) {
    // 上游或系統錯誤。響應主體為通用格式（沒有 `code` 欄位）。
    // 請以**相同的 `idempotencyKey`** 配合指數退避重試
    //（並限制重試次數）。網路或逾時錯誤亦比照處理。
    retryWithBackoff(request);
  }
  ```

  完整的 `400` `code` 值清單見上方表格 — 在介面上將每個 `code` 映射為本地化的使用者訊息時可派上用場。

  📚 [API 參考：卡片 →](/issuing/api-reference/cards/activate-card)
</Update>

<Update label="April 2026" description="v1.4.5">
  ## API Enhancements

  **New KYC Rejection Reason for Cards**

  Added a new detailed rejection reason for card KYC review:

  **Supporting Document Rejections (Non-HK Residents):**

  * `Additional Doc for Non-HK Resident (hotel info invalid)` - The hotel information provided in the supporting document is invalid

  This rejection reason is returned in the `rejectedReason` field when the KYC `status` is `rejected`.

  📚 [API Reference: Get Client Identity →](/issuing/api-reference/card-accounts/get-client-identity-information-for-a-card-account)

  ***

  **新增卡片 KYC 拒絕原因**

  新增一項卡片 KYC 審核的詳細拒絕原因：

  **證明文件拒絕（非香港居民）：**

  * `Additional Doc for Non-HK Resident (hotel info invalid)` - 證明文件中提供的酒店資料無效

  當 KYC `status` 為 `rejected` 時，此拒絕原因會在 `rejectedReason` 欄位中返回。

  📚 [API 參考：取得客戶身份資訊 →](/issuing/api-reference/card-accounts/get-client-identity-information-for-a-card-account)
</Update>

<Update label="March 2026" description="v1.4.4">
  ## API Enhancements

  **New KYC Rejection Reasons for Cards**

  Added three new detailed rejection reasons for card KYC review:

  **ID Document Rejections:**

  * `Invalid ID (name check hit)` - The cardholder's name triggered a name screening check
  * `Invalid ID (exceed the company's risk appetite)` - The application exceeds the company's risk appetite threshold

  **Supporting Document Rejections (Non-HK Residents):**

  * `Additional Doc for Non-HK Resident (missing id back photo)` - The back photo of the ID document is missing

  These rejection reasons are returned in the `rejectedReason` field when the KYC `status` is `rejected`.

  📚 [API Reference: Get Client Identity →](/issuing/api-reference/card-accounts/get-client-identity-information-for-a-card-account)

  ***

  **新增卡片 KYC 拒絕原因**

  新增三項卡片 KYC 審核的詳細拒絕原因：

  **身份證件拒絕：**

  * `Invalid ID (name check hit)` - 持卡人姓名觸發了姓名篩查
  * `Invalid ID (exceed the company's risk appetite)` - 申請超出公司風險承受範圍

  **證明文件拒絕（非香港居民）：**

  * `Additional Doc for Non-HK Resident (missing id back photo)` - 缺少身份證件背面照片

  當 KYC `status` 為 `rejected` 時，這些拒絕原因會在 `rejectedReason` 欄位中返回。

  📚 [API 參考：取得客戶身份資訊 →](/issuing/api-reference/card-accounts/get-client-identity-information-for-a-card-account)
</Update>

<Update label="March 2026" description="v1.4.3">
  ## API Enhancements

  **Enhanced Transaction Intent Descriptions**

  The `intent` field on transactions and the `intent` query parameter on the List Transactions endpoint now include detailed descriptions for all supported values:

  * `charge` - Card purchase or payment authorization
  * `refund` - Reversal or refund of a previous charge
  * `topup` - Funds loaded into the card account
  * `withdraw` - Funds withdrawn (e.g. ATM or cash advance)
  * `repay` - Repayment towards outstanding balance
  * `cashback` - Cashback reward credited to the account
  * `interest` - Interest accrued on outstanding balance
  * `transfer` - Balance transfer between card accounts
  * `fee` - Service fees (e.g. annual fee, late payment fee)
  * `other` - Uncategorized transaction types

  The `intent` query filter now also accepts an array of values for filtering by multiple intent types.

  📚 [API Reference: List Transactions →](/issuing/api-reference/card-accounts/get-card-account-transactions)

  ***

  **New KYC Rejection Reason**

  Added a new rejection reason for address verification during KYC review:

  * `Incomplete Info (not residential address)` - The address provided is not a valid residential address

  This rejection reason is returned in the `rejectedReason` field when the KYC `status` is `rejected`.

  📚 [API Reference: Get Client Identity →](/issuing/api-reference/card-accounts/get-client-identity-information-for-a-card-account)

  ***

  **交易意圖說明增強**

  交易的 `intent` 欄位及列出交易端點的 `intent` 查詢參數現已包含所有支援值的詳細說明：

  * `charge` - 卡片消費或支付授權
  * `refund` - 退款或撤銷先前的消費
  * `topup` - 資金存入卡賬戶
  * `withdraw` - 資金提取（如 ATM 或現金預借）
  * `repay` - 償還未清餘額
  * `cashback` - 現金回饋獎勵
  * `interest` - 未清餘額的利息
  * `transfer` - 卡賬戶之間的餘額轉帳
  * `fee` - 服務費用（如年費、逾期還款費）
  * `other` - 未分類的交易類型

  `intent` 查詢篩選器現在也支援數組值，可同時按多種意圖類型進行篩選。

  📚 [API 參考：列出交易 →](/issuing/api-reference/card-accounts/get-card-account-transactions)

  ***

  **新增 KYC 拒絕原因**

  新增一項用於地址驗證的 KYC 審核拒絕原因：

  * `Incomplete Info (not residential address)` - 提供的地址不是有效的住宅地址

  當 KYC `status` 為 `rejected` 時，此拒絕原因會在 `rejectedReason` 欄位中返回。

  📚 [API 參考：取得客戶身份資訊 →](/issuing/api-reference/card-accounts/get-client-identity-information-for-a-card-account)
</Update>

<Update label="February 2026" description="v1.4.2">
  ## New Features

  **Sandbox Simulation for Client Identity Verification**

  Programmatically simulate the approval or rejection of Client Identity (KYC) verification for card accounts in the Sandbox environment. This allows you to test your webhook handlers and downstream flows immediately without waiting for manual intervention.

  ### What's New:

  A new endpoint `POST /cardaccounts/simulate-client-identity-status` is now available in the Sandbox environment.

  <Warning>
    **Sandbox Only:** This endpoint is only available in the Sandbox environment and is not available in Production.
  </Warning>

  ### Usage:

  Send a request with the `cardAccountId` and the desired `action` (approve or reject).

  ### Example Request:

  ```json theme={null}
  {
    "cardAccountId": "123e4567-e89b-12d3-a456-426614174000",
    "action": "reject",
    "rejectedReason": "Document expired"
  }
  ```

  Simulating a status change triggers the exact same domain events and webhooks (e.g., `ClientIdentityApproved`, `ClientIdentityRejected`) as a real manual review, ensuring your integration is fully tested against production-like behavior.

  📚 [API Reference: Simulate Client Identity Status →](/api-reference/card-accounts/simulate-client-identity-approval-or-rejection)

  ***

  **客戶身份驗證沙盒模擬**

  在沙盒環境中以程式方式模擬卡賬戶客戶身份（KYC）驗證的批准或拒絕。這使您能夠在無需運營團隊手動干預的情況下，即時測試您的 Webhook 處理程序和下游流程。

  ### 新增內容：

  沙盒環境中新增了端點 `POST /cardaccounts/simulate-client-identity-status`。

  <Warning>
    **僅限沙盒環境：** 此端點僅在沙盒環境中可用，在生產環境中不可用。
  </Warning>

  ### 使用方法：

  發送包含 `cardAccountId` 和所需 `action`（approve \[批准] 或 reject \[拒絕]）的請求。

  ### 請求範例：

  ```json theme={null}
  {
    "cardAccountId": "123e4567-e89b-12d3-a456-426614174000",
    "action": "reject",
    "rejectedReason": "Document expired"
  }
  ```

  模擬狀態變更會觸發與真實人工審核完全相同的領域事件和 Webhooks（例如 `ClientIdentityApproved`、`ClientIdentityRejected`），確保您的集成測試與生產行為一致。

  📚 [API 參考：模擬客戶身份狀態 →](/api-reference/card-accounts/simulate-client-identity-approval-or-rejection)
</Update>

<Update label="February 2026" description="v1.4.1">
  ## API Enhancements

  **Enhanced KYC Rejection Reasons for Supporting Documents**

  Added five new detailed rejection reasons specifically for supporting documents submitted by non-Hong Kong residents. These new rejection codes provide clearer feedback when supporting documents are rejected during KYC review:

  * `Additional Doc for Non-HK Resident (document type not accepted)` - The submitted document type is not accepted
  * `Additional Doc for Non-HK Resident (expired document)` - The submitted document has expired
  * `Additional Doc for Non-HK Resident (unclear image)` - The document image quality is insufficient
  * `Additional Doc for Non-HK Resident (document not belong to client)` - The document does not belong to the applicant
  * `Additional Doc for Non-HK Resident (potential bogus document)` - The document appears to be fraudulent

  These rejection reasons are returned in the `rejectedReason` field when the KYC `status` is `rejected`.

  📚 [API Reference: Get Client Identity →](/issuing/api-reference/card-accounts/get-client-identity-information-for-a-card-account)
</Update>

<Update label="February 2026" description="v1.4.0">
  ## Important Update

  **Travel Permit Document Submission Update**

  <Note>
    **Effective Date:** February 1, 2026, 00:00 HKT
  </Note>

  The Hong Kong Permit for Travelling to and from Hong Kong and Macao (往來港澳通行證 / 回鄉證) supporting document type has been updated to require **both front and back images** to be submitted together.

  ### What's Changing:

  The previous document type `TRAVEL_PERMIT` has been replaced with two new document types:

  * `TRAVEL_PERMIT_FRONT` - Front side of the permit
  * `TRAVEL_PERMIT_BACK` - Back side of the permit

  <Warning>
    **Important:** When submitting a travel permit as a supporting document, **both** `TRAVEL_PERMIT_FRONT` and `TRAVEL_PERMIT_BACK` must be included in the `supportingDocuments` array. Submissions with only one side will be rejected with an error.
  </Warning>

  ### Example Submission:

  ```json theme={null}
  {
    "supportingDocuments": [
      {
        "documentType": "TRAVEL_PERMIT_FRONT",
        "file": "data:image/jpeg;base64,..."
      },
      {
        "documentType": "TRAVEL_PERMIT_BACK",
        "file": "data:image/jpeg;base64,..."
      }
    ]
  }
  ```

  📖 [View complete technical details →](/issuing/guides/kyc-requirements#accepted-supporting-documents)

  📚 [API Reference: Create Card Account →](/api-reference/card-accounts/create-card-account)

  ***

  **往來港澳通行證文件提交要求更新**

  <Note>
    **生效日期：** 2026年2月1日，香港時間 00:00
  </Note>

  「往來港澳通行證 / 回鄉證」證明文件類型已更新，現在要求**同時提交正面和背面圖像**。

  ### 變更內容：

  先前的文件類型 `TRAVEL_PERMIT` 已被替換為兩個新的文件類型：

  * `TRAVEL_PERMIT_FRONT` - 通行證正面
  * `TRAVEL_PERMIT_BACK` - 通行證背面

  <Warning>
    **重要提示：** 當提交往來港澳通行證作為證明文件時，**必須**在 `supportingDocuments` 陣列中同時包含 `TRAVEL_PERMIT_FRONT` 和 `TRAVEL_PERMIT_BACK`。僅提交一面的申請將會被拒絕並返回錯誤。
  </Warning>

  ### 提交範例：

  ```json theme={null}
  {
    "supportingDocuments": [
      {
        "documentType": "TRAVEL_PERMIT_FRONT",
        "file": "data:image/jpeg;base64,..."
      },
      {
        "documentType": "TRAVEL_PERMIT_BACK",
        "file": "data:image/jpeg;base64,..."
      }
    ]
  }
  ```

  📖 [查看完整技術細節 →](/issuing/guides/kyc-requirements#accepted-supporting-documents)

  📚 [API 參考：創建卡帳戶 →](/api-reference/card-accounts/create-card-account)
</Update>

<Update label="February 2026" description="v1.3.0">
  ## Important Updates

  **New Mandatory KYC Requirements for Individual Cardholders**

  <Note>
    **Effective Date:** February 1, 2026, 00:00 HKT
  </Note>

  Starting February 1, 2026 at 00:00 HKT, the following fields will become **mandatory** when creating card accounts for individual cardholders:

  * `occupation` - Select from `/v1/occupations` endpoint
  * `position` - Select from `/v1/positions` endpoint
  * `gender` - MALE or FEMALE
  * `nationality` - ISO 3166-1 alpha-2 format (e.g., HK)
  * `supportingDocuments` - Required for non-Hong Kong (HK) nationals ([see accepted document types →](/issuing/guides/kyc-requirements#accepted-supporting-documents))

  **Action Required:** Update your integration before Feb 1, 2026 at 00:00 HKT to collect these fields.

  📖 [View detailed requirements and accepted documents →](/issuing/guides/kyc-requirements)

  📚 [API Reference: Create Card Account →](/api-reference/card-accounts/create-card-account)

  ***

  **個人持卡人強制性 KYC 要求更新**

  <Note>
    **生效日期：** 2026年2月1日，香港時間 00:00
  </Note>

  自2026年2月1日 00:00 HKT起，為個人持卡人創建卡帳戶時以下欄位將成為**強制性**要求：

  * `occupation`（職業）- 從 `/v1/occupations` 端點選擇
  * `position`（職位）- 從 `/v1/positions` 端點選擇
  * `gender`（性別）- MALE 或 FEMALE
  * `nationality`（國籍）- ISO 3166-1 alpha-2 格式（例如：HK）
  * `supportingDocuments`（證明文件）- 非香港 (HK) 國籍申請人必須提供（[查看可接受的文件類型 →](/issuing/guides/kyc-requirements#accepted-supporting-documents)）

  **需採取行動：** 請在2026年2月1日 00:00 HKT前更新您的系統以收集這些欄位。

  📖 [查看詳細要求和可接受文件 →](/issuing/guides/kyc-requirements)

  📚 [API 參考：創建卡帳戶 →](/api-reference/card-accounts/create-card-account)
</Update>

<Update label="December 2025" description="v1.2.0">
  ## New Features

  **New 3D Secure (3DS) Challenge Flow for Online Transactions**

  Enhanced security for online transactions with the new 3DS challenge flow, providing a more secure and streamlined verification experience.

  📖 [View 3D Secure Integration Guide →](/issuing/guides/3ds-integration)

  <Note>
    **Go-Live Date:** December 19, 2025, 00:00 HKT
  </Note>

  ***

  **⚠️ Deprecated Webhook:** `cardaccount.transaction.verification-code-delivered` - This webhook has been replaced by the new 3DS challenge flow. Please migrate to the new integration.
</Update>

<Update label="November 2025" description="v1.1.0">
  ## New Features

  **Webhook Auto-Recovery Mechanism**

  New automatic recovery system for suspended webhooks to reduce manual intervention and prevent webhook accumulation:

  * **Auto-Recovery:** Suspended webhooks are automatically pinged every 5 minutes for up to 24 hours
  * **Automatic Resumption:** If a ping succeeds, webhook delivery resumes automatically without manual intervention
  * **Auto-Deletion:** Webhooks are automatically deleted if they remain suspended with failed recovery pings for 24 consecutive hours

  📖 [Learn more about webhook recovery →](/issuing/guides/webhooks-1)

  <Note>
    **Go-Live Date:** November 29, 2025, 00:00 HKT
  </Note>
</Update>