Changelog - UTGL Developer Portal

v1.4.12

New Features

New Card Account Mode: program-limitCard accounts can now be created with accountType: "program-limit". A program-limit account has an assigned credit limit that is independent of collateral. Instead of a credit account per card, all of your program-limit accounts draw on one shared program facility managed by the server, which caps total exposure across the program.

What’s New

POST /cardaccounts — accepts accountType: "program-limit".

Requires a positive limit, currency, identity details, and settlementAccount. Do not pass creditAccount.
Your account must be set up for program-limit; otherwise creation fails with CREDIT_LINE_TYPE_INVALID_ERROR or PROGRAM_ASSIGNMENT_NOT_FOUND. Program assignment is handled server-side, and a request carrying programId, programCreditLineId, or program_credit_line_id fails with INVALID_REQUEST.

GET /cardaccounts — the program facility is returned as one more record with accountType: "program". Two new nullable fields appear only on that record:

programBalance — program settlement exposure including reservations
programOutstanding — captured program settlement exposure; can be negative when refunds or credits exceed captures

On the program record, available always equals limit, because the facility’s own balance stays at zero; do not use it for capacity. Use limit minus programBalance for the remaining program capacity.POST /cardaccounts/fixed-limit — now also updates the assigned limit of program-limit accounts. These updates skip the collateral check and never change the program facility limit. Do not mix program-limit and fixed-limit accounts in one request; a mixed request fails and no limit is changed.

New `400` Error Codes

Program checks fail with HTTP 400 and one of these code values. Existing validation errors are unchanged.

Code	Returned by	Meaning
`PROGRAM_ASSIGNMENT_NOT_FOUND`	`POST /cardaccounts`	No program matches your account, currency, or card product
`PROGRAM_ASSIGNMENT_AMBIGUOUS`	`POST /cardaccounts`	More than one program matched your account
`PROGRAM_ASSIGNMENT_INVALID`	`POST /cardaccounts`, `GET /cardaccounts`	The program’s configuration is invalid, for example its accounts do not share one currency
`PROGRAM_LIMIT_NOT_AVAILABLE`	`POST /cardaccounts/fixed-limit` and card operations	The target is the program record, or an ordinary account placed in a program

Example Request — `POST /cardaccounts`

{
  "name": "Alice Wong",
  "identityType": "individual",
  "accountType": "program-limit",
  "currency": "USD",
  "limit": 10000,
  "settlementAccount": "de22c824-b8bd-4825-8db5-e5bdd2371dfb",
  "phoneNumber": "+85255551234",
  "individual": { "...": "..." }
}

Example Response — `GET /cardaccounts` (program record)

{
  "id": "...",
  "accountType": "program",
  "currency": "USD",
  "limit": 100000.00,
  "balance": 0.00,
  "available": 100000.00,
  "programBalance": 12000.00,
  "programOutstanding": 11500.00
}

Action Suggested

If you switch on accountType, handle the new program-limit and program values. Treat program records as read-only and exclude them from cardholder-facing lists.
If your JSON decoder rejects unknown fields, allow programBalance and programOutstanding.
Ask your solution manager to set up program-limit for your account before relying on it.

📚 Guide: Card Account Modes → 📚 API Reference: Create Card Account → 📚 API Reference: Update Fixed Limit →

新功能

新增卡賬戶模式：program-limit現可使用 accountType: "program-limit" 建立卡賬戶。Program-limit 賬戶擁有獨立於抵押品的指定信用額度。所有 program-limit 賬戶共用一個由伺服器管理的計劃額度（program facility），而非每張卡各自綁定一個信貸賬戶；計劃額度會限制整個計劃的總風險敞口。

新增內容

POST /cardaccounts — 接受 accountType: "program-limit"。

需提供正數 limit、currency、身份資料及 settlementAccount。請勿傳入 creditAccount。
您的賬戶須先完成 program-limit 設定，否則建立時會返回 CREDIT_LINE_TYPE_INVALID_ERROR 或 PROGRAM_ASSIGNMENT_NOT_FOUND。計劃分配由伺服器處理；帶有 programId、programCreditLineId 或 program_credit_line_id 的請求會返回 INVALID_REQUEST。

GET /cardaccounts — 計劃額度會以 accountType: "program" 的形式作為一筆額外記錄返回。以下兩個可為 null 的新欄位僅出現於該記錄：

programBalance — 計劃結算風險敞口（包括預留金額）
programOutstanding — 已入賬的計劃結算風險敞口

計劃記錄上的 available 恆等於 limit（計劃額度本身的 balance 維持為零），請勿用作容量判斷。估算計劃剩餘容量時，請使用 limit 減 programBalance。POST /cardaccounts/fixed-limit — 現亦可更新 program-limit 賬戶的指定額度。此類更新會跳過抵押品檢查，且不會更改計劃額度上限。請勿在同一請求內混合 program-limit 與 fixed-limit 賬戶；混合請求會失敗，且不會更改任何額度。

新增 `400` 錯誤碼

計劃檢查失敗時會返回 HTTP 400 及以下其中一個 code 值。現有的驗證錯誤維持不變。

錯誤碼	返回端點	含義
`PROGRAM_ASSIGNMENT_NOT_FOUND`	`POST /cardaccounts`	沒有與您的賬戶、幣種或卡產品匹配的計劃
`PROGRAM_ASSIGNMENT_AMBIGUOUS`	`POST /cardaccounts`	您的賬戶匹配多於一個計劃
`PROGRAM_ASSIGNMENT_INVALID`	`POST /cardaccounts`、`GET /cardaccounts`	計劃設定無效，例如計劃內的賬戶幣種不一致
`PROGRAM_LIMIT_NOT_AVAILABLE`	`POST /cardaccounts/fixed-limit` 及卡片操作	操作對象為計劃記錄本身，或已納入計劃的普通賬戶

請求範例 — `POST /cardaccounts`

{
  "name": "Alice Wong",
  "identityType": "individual",
  "accountType": "program-limit",
  "currency": "USD",
  "limit": 10000,
  "settlementAccount": "de22c824-b8bd-4825-8db5-e5bdd2371dfb",
  "phoneNumber": "+85255551234",
  "individual": { "...": "..." }
}

響應範例 — `GET /cardaccounts`（計劃記錄）

{
  "id": "...",
  "accountType": "program",
  "currency": "USD",
  "limit": 100000.00,
  "balance": 0.00,
  "available": 100000.00,
  "programBalance": 12000.00,
  "programOutstanding": 11500.00
}

建議行動

如果您的程式會根據 accountType 分支處理，請加入新的 program-limit 及 program 值。將 program 記錄視為唯讀，並從持卡人介面的列表中排除。
如果您的 JSON 解析器會拒絕未知欄位，請允許 programBalance 及 programOutstanding。
在正式使用前，請聯絡您的方案經理為您的賬戶完成 program-limit 設定。

📚 指南：卡賬戶模式 → 📚 API 參考：建立卡賬戶 → 📚 API 參考：更新固定額度 →

v1.4.11

API Enhancements

New KYC Rejection Reasons for CardsAdded three new detailed rejection reasons for card KYC review:ID Document Rejections:

ID failed authenticity check – clear photo of original requested - The ID failed an authenticity check; the cardholder should resubmit a clear photo of the original document
ID failed authenticity check – reject application - The ID failed an authenticity check and the application is declined

Supporting Document Rejections (Non-HK Residents):

Additional Doc for Non-HK Resident (travel agency info invalid) - The travel agency information provided in the supporting document is invalid

These rejection reasons are returned in the rejectedReason field when the KYC status is rejected, and in the cardaccount.client-identity.rejected webhook. The two authenticity reasons use an en dash (–) rather than parentheses, so match on the category prefix (ID failed authenticity check) rather than the full string.📚 API Reference: Get Client Identity →

API 增強

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

ID failed authenticity check – clear photo of original requested - 身份證件未通過真偽檢查；持卡人須重新提交正本的清晰照片
ID failed authenticity check – reject application - 身份證件未通過真偽檢查，申請被拒絕

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

Additional Doc for Non-HK Resident (travel agency info invalid) - 證明文件中提供的旅行社資料無效

當 KYC status 為 rejected 時，這些拒絕原因會在 rejectedReason 欄位及 cardaccount.client-identity.rejected Webhook 中返回。兩項真偽檢查原因使用連接號（–）而非括號，請以類別前綴（ID failed authenticity check）而非完整字串進行匹配。📚 API 參考：取得客戶身份資訊 →

v1.4.10

Important Update

Card Transaction Notifications: SMS and WhatsApp No Longer Supported

Effective since 2026-07-01 00:00 (Asia/Hong_Kong). Through the Access API, purchase and ATM transaction notifications can no longer be delivered by SMS or WhatsApp.

The change applies to two fields only: purchaseNotification and atmNotification.

POST /cards/notification-settings still accepts sms, whatsapp, and auto for these two fields, for backward compatibility. None of them has any effect, and the response returns off.
auto means WhatsApp with SMS fallback, so it is turned off along with sms and whatsapp.
GET /cards/notification-settings returns off for these two fields, including on cards whose settings were made before the cutoff.
onlinePurchaseVerification and fraudAlert are not affected. They still accept and return sms, whatsapp, auto, and off.
3DS, OTP, Google Pay binding, and other authentication or approval flows are not affected.

Action Suggested

Remove the SMS, WhatsApp, and Auto choices for purchase and ATM notifications from your cardholder UI, since setting them has no effect.
Expect off for purchaseNotification and atmNotification in every response, and don’t treat it as an error.

📚 API Reference: Update Card Notification Settings →

重要更新

卡片交易通知：不再支援 SMS 及 WhatsApp

自 2026-07-01 00:00（Asia/Hong_Kong） 起生效。透過 Access API 設定的消費及 ATM 交易通知，已不能再經 SMS 或 WhatsApp 發送。

此變更只適用於兩個欄位：purchaseNotification 及 atmNotification。

為向後兼容，POST /cards/notification-settings 仍接受這兩個欄位的 sms、whatsapp 及 auto，但全部不會生效，響應會返回 off。
auto 代表 WhatsApp 並以 SMS 作後備，因此會與 sms 及 whatsapp 一同被關閉。
GET /cards/notification-settings 對這兩個欄位會返回 off，包括於截止時間前已設定的卡片。
onlinePurchaseVerification 及 fraudAlert 不受影響，仍接受並返回 sms、whatsapp、auto 及 off。
3DS、OTP、Google Pay 綁定及其他認證或批核流程不受影響。

建議行動

由於設定不會生效，請從持卡人介面中移除消費及 ATM 通知的 SMS、WhatsApp 及 Auto 選項。
預期所有響應中的 purchaseNotification 及 atmNotification 均為 off，並且不要將其視為錯誤。

📚 API 參考：更新卡片通知設定 →

v1.4.9

Important Update

UnionPay Payouts: Chinese Name ValidationUnionPay payout destinations now have their Chinese name fields checked when you submit the request. Before this change, these fields were not checked until the payout processor handled the payout, so an invalid name only failed later.

Chinese characters only. firstNameCN and surnameCN must match ^[\u4e00-\u9fa5]+$. A romanized name such as XU is rejected.
Combined length limit. firstNameCN, a space, and surnameCN together must be at most 10 characters. Because the space counts, the two names can total at most 9 Chinese characters.

POST /payouts and POST /payouts/validate both reject an invalid name with HTTP 400. For the length limit, POST /payouts/validate returns UNIONPAY_INVALID_CHINESE_NAME_LENGTH. POST /payouts returns UNIONPAY_INVALID_FIELDS, and its message names the limit.📚 API Reference: Create Payout → 📚 API Reference: Validate Payout Parameters →

重要更新

銀聯匯款：中文姓名驗證提交銀聯匯款請求時，系統現會檢查收款人的中文姓名欄位。此變更前，這些欄位要到匯款處理商處理時才會檢查，因此無效姓名會在較後階段才失敗。

只限中文字元。 firstNameCN 及 surnameCN 必須符合 ^[\u4e00-\u9fa5]+$。拼音或英文姓名（例如 XU）會被拒絕。
合併長度上限。 firstNameCN、一個空格及 surnameCN 合計不得超過 10 個字元。由於空格亦計算在內，兩個姓名合計最多 9 個中文字。

POST /payouts 及 POST /payouts/validate 均會以 HTTP 400 拒絕無效姓名。超出長度上限時，POST /payouts/validate 返回 UNIONPAY_INVALID_CHINESE_NAME_LENGTH；POST /payouts 返回 UNIONPAY_INVALID_FIELDS，其 message 會註明該上限。📚 API 參考：建立匯款 → 📚 API 參考：驗證匯款參數 →

v1.4.8

API Enhancements

Card Account xid Now Included in Client Identity WebhooksThe 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`

{
  "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`

{
  "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 →

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`

{
  "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`

{
  "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 事件 →

v1.4.7

API Enhancements

Card Dispute Fields Now ExposedCard 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=...`

{
  "id": "...",
  "description": "UBER * PENDING Amsterdam NLD",
  "disputeStatus": "pending",
  "grossAmount": 1000
}

Example Response — `GET /cardaccounts`

{
  "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 → 📚 Guide: Webhook Events →

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=...`

{
  "id": "...",
  "description": "UBER * PENDING Amsterdam NLD",
  "disputeStatus": "pending",
  "grossAmount": 1000
}

響應範例 — `GET /cardaccounts`

{
  "id": "...",
  "balance": 10000.25,
  "outstanding": 7500.50,
  "disputeAmount": 250.00,
  "available": 825.30
}

建議行動

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

📚 API 參考：卡賬戶交易列表 → 📚 指南：Webhook 事件 →

v1.4.6

Important Update

Card Endpoints: Business Errors Now Return HTTP 400Seven 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

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).

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)

{
  "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.

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 →

重要更新

卡片端點：業務錯誤現在返回 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 配合通用錯誤主體返回。

需要採取的行動

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

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

響應範例（修正後）

{
  "statusCode": 400,
  "code": "CARD_ALREADY_LOCKED",
  "message": "Card is already locked"
}

建議的客戶端處理方式

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

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 參考：卡片 →

v1.4.5

API Enhancements

New KYC Rejection Reason for CardsAdded 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 →

新增卡片 KYC 拒絕原因新增一項卡片 KYC 審核的詳細拒絕原因：證明文件拒絕（非香港居民）：

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

當 KYC status 為 rejected 時，此拒絕原因會在 rejectedReason 欄位中返回。📚 API 參考：取得客戶身份資訊 →

v1.4.4

API Enhancements

New KYC Rejection Reasons for CardsAdded 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 →

新增卡片 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 參考：取得客戶身份資訊 →

v1.4.3

API Enhancements

Enhanced Transaction Intent DescriptionsThe 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 →

New KYC Rejection ReasonAdded 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 →

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

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

intent 查詢篩選器現在也支援數組值，可同時按多種意圖類型進行篩選。📚 API 參考：列出交易 →

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

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

當 KYC status 為 rejected 時，此拒絕原因會在 rejectedReason 欄位中返回。📚 API 參考：取得客戶身份資訊 →

v1.4.2

New Features

Sandbox Simulation for Client Identity VerificationProgrammatically 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.

Sandbox Only: This endpoint is only available in the Sandbox environment and is not available in Production.

Usage:

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

Example Request:

{
  "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 →

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

新增內容：

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

僅限沙盒環境： 此端點僅在沙盒環境中可用，在生產環境中不可用。

使用方法：

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

請求範例：

{
  "cardAccountId": "123e4567-e89b-12d3-a456-426614174000",
  "action": "reject",
  "rejectedReason": "Document expired"
}

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

v1.4.1

API Enhancements

Enhanced KYC Rejection Reasons for Supporting DocumentsAdded 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 →

v1.4.0

Important Update

Travel Permit Document Submission Update

Effective Date: February 1, 2026, 00:00 HKT

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

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.

Example Submission:

{
  "supportingDocuments": [
    {
      "documentType": "TRAVEL_PERMIT_FRONT",
      "file": "data:image/jpeg;base64,..."
    },
    {
      "documentType": "TRAVEL_PERMIT_BACK",
      "file": "data:image/jpeg;base64,..."
    }
  ]
}

📖 View complete technical details →📚 API Reference: Create Card Account →

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

生效日期： 2026年2月1日，香港時間 00:00

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

變更內容：

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

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

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

提交範例：

{
  "supportingDocuments": [
    {
      "documentType": "TRAVEL_PERMIT_FRONT",
      "file": "data:image/jpeg;base64,..."
    },
    {
      "documentType": "TRAVEL_PERMIT_BACK",
      "file": "data:image/jpeg;base64,..."
    }
  ]
}

📖 查看完整技術細節 →📚 API 參考：創建卡帳戶 →

v1.3.0

Important Updates

New Mandatory KYC Requirements for Individual Cardholders

Effective Date: February 1, 2026, 00:00 HKT

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 →)

Action Required: Update your integration before Feb 1, 2026 at 00:00 HKT to collect these fields.📖 View detailed requirements and accepted documents →📚 API Reference: Create Card Account →

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

生效日期： 2026年2月1日，香港時間 00:00

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

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

需採取行動： 請在2026年2月1日 00:00 HKT前更新您的系統以收集這些欄位。📖 查看詳細要求和可接受文件 →📚 API 參考：創建卡帳戶 →

v1.2.0

New Features

New 3D Secure (3DS) Challenge Flow for Online TransactionsEnhanced security for online transactions with the new 3DS challenge flow, providing a more secure and streamlined verification experience.📖 View 3D Secure Integration Guide →

Go-Live Date: December 19, 2025, 00:00 HKT

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

v1.1.0

New Features

Webhook Auto-Recovery MechanismNew 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 →

Go-Live Date: November 29, 2025, 00:00 HKT

​New Features

​What’s New

​New 400 Error Codes

​Example Request — POST /cardaccounts

​Example Response — GET /cardaccounts (program record)

​Action Suggested

​新功能

​新增內容

​新增 400 錯誤碼

​請求範例 — POST /cardaccounts

​響應範例 — GET /cardaccounts（計劃記錄）

​建議行動

​API Enhancements

​API 增強

​Important Update

​Action Suggested

​重要更新

​建議行動

​Important Update

​重要更新

​API Enhancements

​What’s New

​Example Payload — cardaccount.client-identity.approved

​Example Payload — cardaccount.client-identity.rejected

​Action Suggested

​API 增強

​新增內容

​載荷範例 — cardaccount.client-identity.approved

​載荷範例 — cardaccount.client-identity.rejected

​建議行動

​API Enhancements

​What’s New

​Webhook Behavior

​Example Response — GET /cardaccounts/transactions?cardAccountId=...

​Example Response — GET /cardaccounts

​Action Suggested

​API 增強

​新增內容

​Webhook 行為

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

​響應範例 — GET /cardaccounts

​建議行動

​Important Update

​Affected Endpoints and Error Codes

​Action Required

​Example Response (After)

​Recommended Client Handling

​重要更新

​受影響的端點與錯誤碼

​需要採取的行動

​響應範例（修正後）

​建議的客戶端處理方式

​API Enhancements

​API Enhancements

​API Enhancements

​New Features

​What’s New:

​Usage:

​Example Request:

​新增內容：

​使用方法：

​請求範例：

​API Enhancements

​Important Update

​What’s Changing:

​Example Submission:

​變更內容：

​提交範例：

​Important Updates

​New Features

​New Features

New Features

What’s New

New `400` Error Codes

Example Request — `POST /cardaccounts`

Example Response — `GET /cardaccounts` (program record)

Action Suggested

新功能

新增內容

新增 `400` 錯誤碼

請求範例 — `POST /cardaccounts`

響應範例 — `GET /cardaccounts`（計劃記錄）

建議行動

API Enhancements

API 增強

Important Update

Action Suggested

重要更新

建議行動

Important Update

重要更新

API Enhancements

What’s New

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

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

Action Suggested

API 增強

新增內容

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

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

建議行動

API Enhancements

What’s New

Webhook Behavior

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

Example Response — `GET /cardaccounts`

Action Suggested

API 增強

新增內容

Webhook 行為

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

響應範例 — `GET /cardaccounts`

建議行動

Important Update

Affected Endpoints and Error Codes

Action Required

Example Response (After)

Recommended Client Handling

重要更新

受影響的端點與錯誤碼

需要採取的行動

響應範例（修正後）

建議的客戶端處理方式

API Enhancements

API Enhancements

API Enhancements

New Features

What’s New:

Usage:

Example Request:

新增內容：

使用方法：

請求範例：

API Enhancements

Important Update

What’s Changing:

Example Submission:

變更內容：

提交範例：

Important Updates

New Features

New Features