上线后常见问题

责任划分提示：在 DeCard 托管模式下，授权决策在 DCS 系统内部完成，每个终端用户持有独立余额（可用 free / 冻结 freeze）。因此「为什么这笔被拒」「余额够不够」这类问题，应先查该用户的独立账户余额与卡片状态，再结合风控/MCC 规则判断；这与合作伙伴自管（池账户）模式下「由接入机构自管额度与授权」不同。

​

把卡加入数字钱包（Apple Pay 与 Google Pay）失败

1. 换一张卡试试：先确认问题是「这张卡」还是「这个钱包/这部手机」。
2. 常见失败原因：
   • 手机所在国家/地区与卡的发行地区不一致；
   • 手机被 Apple / Google 标记为高风险设备；
   • 短时间内反复添加多张卡，触发了钱包侧的频率限制。
3. 处理建议：通常一部设备在 24 小时内只能成功添加一张卡，请引导用户间隔 24 小时后重试。

DeCard 托管支持应用内一键绑卡（In-App Provisioning），对应 POST /card/v1/apple-bind-wallet 与 /card/v1/google-bind-wallet（Google 另有 V2 同名接口）。接入方式与字段见 Apple Pay 与 Google Pay 绑卡。

​

把卡添加到商户（绑卡支付）失败

• 部分商户对账单地址（Billing Address）校验较严，可建议用户在结账时尝试填写卡片发行地对应的地址信息；
• 若仍失败，请记录该笔交易标识后按上报路径上报 DCS 协查。可用 POST /card/v1/transaction/id/resolve 解析交易明细以定位该笔记录。

​

交易被拒怎么排查

0. 先从 Webhook 定位是否被拒：接入机构配置的回调地址会收到 CARD_TRANSACTION 类型 Webhook，其中 data.response = "A" 表示授权批准、"D" 表示授权拒绝。该字段仅区分批准 / 拒绝二值，不附带详细拒绝原因码，拒绝原因需通过以下步骤人工判断。
1. 查用户独立余额：调用 GET /user-asset/v1/balance 查该用户钱包余额——free（可用）是否足够覆盖本笔消费、freeze（冻结）是否占用过多。余额不足是最常见的拒绝原因。
   GET /user-asset/v1/balance?externalUserId=<external-user-id>
   

   响应 data 为数组，逐币种返回 {asset, free, freeze, total}。字段与用法见用户余额。

2. 查卡片状态：通过 GET /card/v2/detail 查 cardStatus（虚拟卡：NORMAL/FROZEN/CANCELLED）与 physicalCardStatus（实体卡：UN_APPLY/INACTIVE/ACTIVE/REPLACE/FROZEN/CANCELLED）。若卡处于 FROZEN 或 CANCELLED，授权不会成功。
   GET /card/v2/detail?externalUserId=<external-user-id>&cardId=<card-id>
   

   cardId 在开卡成功响应中返回，也可通过 GET /card/v2/detail 留空 cardId 返回该用户全部卡。实体卡冻结/销户见 physicalCardStatus 字段。详见下节「卡被冻结」。

3. 查风控 / MCC：是否命中受限商户类别（MCC）或风控规则。若余额充足、卡状态正常仍被拒，请联系 DCS 按上报路径确认该笔交易是否命中风控/MCC 规则。
4. 告知用户：根据上述判定，向用户说明被拒原因。

授权字段（direction、authType 等）说明见实时授权；账户资产与冻结/扣款模型见基础概念 › 账户与资产模型。

​

卡被冻结，如何区分与处理

• 解冻：调用 POST /card/v2/block，请求体含 externalUserId、cardId、block（布尔，false=解冻 / true=冻结），并传 smsCode（短信验证码）或 emailCode（邮箱验证码）二选一（解冻需要验证码）。该接口以布尔字段 block 区分冻结/解冻，并非两个独立接口。

POST /card/v2/block

{
  "externalUserId": "user_xxxxxxxx",
  "block": false,
  "cardId": "card_xxxxxxxx",
  "smsCode": "",
  "emailCode": ""
}

smsCode 通过 POST /captcha/v1/send-mobile-code（behavioral=CARD_UNFROZEN）获取；emailCode 通过 POST /captcha/v1/send-email-code 获取。smsCode 与 emailCode 二选一即可。

该接口以 cardId 精确标识卡片。卡状态机与各状态可执行操作详见卡管理 › 概述。

​

退款 / 撤销迟迟未到账

• 商户发起退款/撤销后，到账存在客观时延，请先告知用户耐心等待。
• 可用 GET /card/v2/statements（账单）与 POST /card/v1/transaction/id/resolve（解析单笔交易明细）核对该笔记录的状态与方向。
  POST /card/v1/transaction/id/resolve
  
  {
    "ids": ["<outstanding-id-or-posted-transaction-id>"]
  }
  

  请求体 ids 传入一笔或多笔交易 ID（outstandingTransactionId 或 postedTransactionId）。响应区分 posted（是否已入账）、outstandingTransactionId（未入账时为 null）与 postedTransactionId（已入账时赋值）。

• 若长时间（明显超出合理周期）仍未到账，请带上该笔原始交易标识按上报路径上报 DCS 协查。

退款/撤销的具体到账时效以实际渠道处理为准。退款/冲正（authType=REFUND / REVERSAL，direction=CREDIT）的字段与场景见实时授权。

​

持卡人对某笔交易有异议（争议 / 盗刷）

• 先用 GET /card/v2/statements / POST /card/v1/transaction/id/resolve 核对交易明细（商户名、金额、时间），排除本人遗忘或家庭成员消费；
• 确属争议/盗刷的，请按上报路径联系 DCS 跟进。

​

已发卡用户的 KYC 长时间处于审核中

1. 先查证件质量与标注：确认提交的证件清晰、未截图、且类型/正反面标注正确（如身份证正面、自拍是否标注无误）。可接受证件清单见 KYC 证件说明。
2. 查当前状态：确认当前处于哪一阶段；若需补件，引导用户补充。
3. 等待合理时间后上报：若证件无误仍长时间停留在审核中，请带上 externalUserId / KYC 工单标识按上报路径上报 DCS。

拒绝原因见KYC 拒绝与补件。

​

修改实体卡寄送地址

1. 按上报路径联系 DCS 注销该用户当前卡片；
2. 引导用户以正确地址重新申请新卡。

当前寄送地址更正的标准做法为注销当前卡片后以正确地址重新申请。寄送信息与实体卡流程见卡管理 › 概述。

​

屏蔽可疑商户

• DeCard 托管模式下，授权在 DCS 系统内决策，商户/MCC 级屏蔽需在 DCS 风控侧配置；
• 请按上报路径上报，并提供商户标识与屏蔽原因，由 DCS 在风控/卡组织层面处理。

​

下一步

• 需要把问题上报给 DCS、或想了解各类问题的响应路径，请前往问题上报与支持路径。
• 上线前的准备类问题见客户成功 › 概述（上线前常见问题）。