Changelog

​

API Enhancements

​

What’s New

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

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

​

Webhook Behavior

​

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 增強

​

新增內容

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

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

​

Webhook 行為

​

響應範例 — 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 進行分支處理，以對爭議生命週期作出回應（例如在爭議完成時通知使用者）。

​

Important Update

​

Affected Endpoints and Error Codes

​

Action Required

• 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

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);
}

​

重要更新

​

受影響的端點與錯誤碼

​

需要採取的行動

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

​

響應範例（修正後）

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

​

建議的客戶端處理方式

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);
}

​

API Enhancements

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

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

​

API Enhancements

• 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

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

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

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

​

API Enhancements

• 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

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

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

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

​

New Features

​

What’s New:

​

Usage:

​

Example Request:

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

​

新增內容：

​

使用方法：

​

請求範例：

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

​

API Enhancements

• 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

​

Important Update

​

What’s Changing:

• TRAVEL_PERMIT_FRONT - Front side of the permit
• TRAVEL_PERMIT_BACK - Back side of the permit

​

Example Submission:

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

​

變更內容：

• 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,..."
    }
  ]
}

​

Important Updates

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

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

​

New Features

​

New Features

• 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