响应码
Quick Reference
WhatAPI 响应码
Why理解并处理每个 API 响应
API 返回结构化的错误和状态载荷。许多值由收单机构或卡网络的返回码映射而来。这些映射会归一为一组稳定代码。您可以在集成中据此做分支处理。
快速搜索
使用浏览器的查找功能（Ctrl+F / Cmd+F）在本页搜索代码或描述列。
映射差异
具体映射可能因服务商和卡产品而异。将收单机构特定的字符串作为诊断信息；基于下方标准化代码实现重试和客户消息。
响应码参考
| 代码 | 描述 | 建议操作 |
|---|---|---|
CARD_DECLINED | 发卡行或卡网络拒绝了交易。 | 请客户使用其他卡片或联系银行。 |
INVALID_CARD | 卡号或 PAN（主账号）验证失败（格式或校验和）。 | 重新采集卡片信息；在输入更正前阻止重试。 |
EXPIRED_CARD | 卡片已过期。 | 提示使用有效期内的卡片或更换卡片。 |
INSUFFICIENT_FUNDS | 发卡行因余额或额度不足而拒绝。 | 建议使用其他支付方式或稍后重试。 |
INVALID_CVC | 安全码不匹配或在需要时缺失。 | 重新输入 CVV；对于已保存的卡片，刷新凭证。 |
3DS_REQUIRED | 授权前必须完成身份验证。 | 继续或发起 3DS 流程；暂不视为硬拒绝。 |
3DS_FAILED | 3DS 身份验证失败或被放弃。 | 重试 3DS 或提供其他卡片或支付方式。 |
3DS_UNAVAILABLE | ACS 或目录服务器不可用。 | 重试一次；如持续不可用，按您的风控策略回退。 |
PROCESSING_ERROR | 收单机构或平台的暂时性错误。 | 使用幂等键重试；如反复出现则升级处理。 |
TIMEOUT | 服务商或网络超时。 | 在重复发起金融调用前先查询扣款状态。 |
DUPLICATE_REQUEST | 检测到幂等重放但请求体冲突。 | 使请求载荷与原始请求一致，或使用新的幂等键。 |
FRAUD_SUSPECTED | 被欺诈或风控规则拦截。 | 转入人工审核或使用其他方式；不要暴力重试。 |
AMOUNT_INVALID | 金额低于最低限额、超过最高限额或小数精度错误 | CLP 和 COP 是零小数货币——发送整数。BRL、MXN、USD、EUR、PEN、ARS 使用 2 位小数 |
amount_below_minimum | 金额低于收单方或支付方式最低限额 | 增加金额。Boleto 最低 R$5.00 |
amount_exceeds_maximum | 金额超过方式或收单方最高限额 | 减少金额或拆分为多笔。OXXO 最高 MXN $10,000 |
amount_too_low | 交易金额低于最低要求 | 增加金额以继续 |
amount_too_high | 交易金额超过允许的最大值 | 尝试较低金额 |
CURRENCY_NOT_SUPPORTED | 钱包或路由不支持该币种 | 更改货币或钱包配置 |
MERCHANT_NOT_ALLOWED | MCC、区域或商户配置阻止了交易。 | 联系支持调整路由或权限。 |
ACQUIRER_ERROR | 下游收单机构返回了未映射的错误。 | 稍后重试；在支持工单中附带关联 ID。 |
分类速查
安全提醒
记录错误响应用于支持时，切勿记录完整卡号或敏感身份验证数据——这存在严重安全风险。
| 场景 | 典型代码 |
|---|---|
| 卡片被拒（通用） | CARD_DECLINED、INSUFFICIENT_FUNDS |
| 卡片数据问题 | INVALID_CARD、EXPIRED_CARD、INVALID_CVC |
| 3DS（3D Secure 验证） | 3DS_REQUIRED、3DS_FAILED、3DS_UNAVAILABLE |
| 金额/货币 | AMOUNT_INVALID、amount_below_minimum、amount_exceeds_maximum、amount_too_low、amount_too_high、CURRENCY_NOT_SUPPORTED |
| 基础设施 | PROCESSING_ERROR、TIMEOUT、ACQUIRER_ERROR |