支付失败错误码接口文档

1. 响应字段

下单失败时的响应示例（省略无关字段）：

{
  "code": "0",
  "msg": "success",
  "success": true,
  "data": {
    "resultCode": "FAILED",
    "refusalReason": "Your card was declined.",
    "refusalReasonCode": "FP-32",
    "merchantReference": "B7B53455CBE749F58ABED6844D4721BD",
    "pspReference": "2101556997748031488",
    "amount": { "currency": "USD", "value": 200 }
  }
}

字段	类型	说明
`resultCode`	String	交易结果。失败为 `FAILED`，处理中为 `PENDING`，成功为 `SUCCEED`
`refusalReasonCode`	String	统一错误码，形如 `FP-32`。失败时返回，覆盖范围见第 8 节
`refusalReason`	String	失败原因文案，仅供展示或记录日志

注意：外层 code / success 表示的是接口调用是否成功，与交易结果无关。
下单被拒时外层仍是 code: "0"、success: true，交易结果要看 data.resultCode。

请以 refusalReasonCode 做程序判断。
refusalReason 的文案内容可能随时调整，请勿对其做字符串匹配。

2. 号段规则

看号段即可决定处理方式，无需查全表：

号段	含义	处理方式
`FP-01` ~ `FP-29`	硬拒：卡或账户本身的问题	不要重试，引导用户更换支付方式
`FP-30` ~ `FP-59`	软拒：可重试，或修正信息后重试	提示用户重试或修正卡信息
`FP-60` ~ `FP-79`	风控与受理拦截	逐条判断，多数不应重试
`FP-80` ~ `FP-89`	请求参数或配置错误	不要重试，属于对接问题，请联系我们
`FP-90` ~ `FP-99`	系统异常	退避后重试

各号段留有预留空位，后续新增原因取新号；已发布的码不会改变含义，可放心硬编码。

3. 硬拒 `FP-01` ~ `FP-29`

卡或账户本身的问题，同一张卡重试无意义。

码	英文	中文	建议动作
FP-01	Card reported stolen	卡被举报盗刷	引导更换支付方式。不要向持卡人透露具体原因
FP-02	Card reported lost	卡被举报遗失	引导更换支付方式。不要向持卡人透露具体原因
FP-03	Card must be retained by issuer	发卡行要求没收该卡	引导更换支付方式
FP-04	Payment flagged as fraudulent	被判定为欺诈交易	引导更换支付方式。不要向持卡人透露具体原因
FP-05	Blocked by block list	命中拦截名单	引导更换支付方式。不要向持卡人透露具体原因
FP-06	Card or account invalid	卡或关联账户无效	提示核对卡号，或联系发卡行
FP-07	Card replaced, update card details	卡已换号，需更新卡信息	提示使用新卡重新绑定
FP-08	Authorization revoked by cardholder	持卡人已撤销本商户授权	停止对该卡发起扣款
FP-09	All authorizations revoked	持卡人已撤销全部授权	停止对该卡发起扣款
FP-10	Stop payment order placed	持卡人已止付	停止对该卡发起扣款
FP-11	Security violation	安全违规	引导更换支付方式
FP-12	Card restricted	受限卡，不可用于本次支付	引导更换支付方式
FP-13	Card does not support this purchase type	该卡不支持此类交易	提示联系发卡行或换卡
FP-14	Card does not support this currency	该卡不支持此币种	更换币种或换卡
FP-15	Transaction type not allowed	该交易类型不被允许	引导更换支付方式
FP-16	Payment not permitted	该笔支付不被允许	引导更换支付方式
FP-17	Service not allowed	该服务不被允许	引导更换支付方式
FP-18	PIN attempts exceeded	PIN 错误次数超限	引导更换支付方式
FP-19	Test card used in production	生产环境使用了测试卡号	使用真实卡号
FP-20	Issuer requests no retry	发卡行要求勿重试	停止对该卡发起扣款
FP-21	Payment method restricted	支付方式被限制	引导更换支付方式

4. 软拒 `FP-30` ~ `FP-59`

可重试，或用户修正信息后重试。

4.1 发卡行原因 `FP-30` ~ `FP-39`

码	英文	中文	建议动作
FP-30	Insufficient funds	余额不足	提示换卡或充值后重试
FP-31	Declined by issuer	发卡行拒绝，未给出具体原因	提示联系发卡行
FP-32	Generic decline	通用拒绝	提示联系发卡行或换卡
FP-33	Processing error	处理过程中出错	可稍后重试
FP-34	Issuer unavailable	发卡行暂时不可达	可稍后重试
FP-35	Re-enter transaction	请重新发起该笔交易	可立即重试一次
FP-36	Cannot authorize, retry	无法授权，可重试	可重试；仍失败则提示联系发卡行
FP-37	Contact card issuer	需持卡人联系发卡行	提示联系发卡行
FP-38	No action taken by issuer	发卡行未做处理	提示联系发卡行
FP-39	Try again later	稍后再试	退避后重试

4.2 限额相关 `FP-40` ~ `FP-44`

码	英文	中文	建议动作
FP-40	Card velocity or limit exceeded	超出卡的额度或交易频次限制	提示换卡或联系发卡行
FP-41	Withdrawal count limit exceeded	超出取现或交易次数限制	提示换卡
FP-42	Invalid amount	金额无效或超出该卡允许范围	核对金额，或提示联系发卡行
FP-43	Card decline rate limit exceeded	该卡被拒次数过多	24 小时内不要再用该卡重试
FP-44	Duplicate transaction	短时间内重复的同额交易	先查证是否已有成功订单，避免重复扣款

4.3 卡信息填写 `FP-45` ~ `FP-53`

这一组均为用户输入问题，修正后即可成功。

码	英文	中文	建议动作
FP-45	Incorrect card number	卡号错误	提示核对卡号
FP-46	Incorrect CVC	安全码（CVC）错误	提示核对安全码
FP-47	Invalid expiry month	有效期月份错误	提示核对有效期
FP-48	Invalid expiry year	有效期年份错误	提示核对有效期
FP-49	Card expired	卡已过期	提示更换有效的卡
FP-50	Incorrect postal code	账单邮编不匹配	提示核对账单邮编
FP-51	Incorrect billing address	账单地址不匹配	提示核对账单地址
FP-52	Incorrect PIN	PIN 错误	提示重新输入 PIN
FP-53	PIN required	需要输入 PIN	引导按终端提示输入 PIN

4.4 认证相关 `FP-55` ~ `FP-59`

码	英文	中文	建议动作
FP-55	Authentication required	需完成 3DS 认证	引导完成 3DS 认证
FP-56	Authentication not handled	未执行必需的认证流程	走完整 3DS 流程后重试
FP-57	Authentication failed	3DS 认证失败	提示重新认证或换卡
FP-58	Mobile device authentication required	需在移动设备上重新完成认证	引导在移动设备上重新操作
FP-59	Customer declined the payment	用户放弃或拒绝授权	提示重新发起支付

5. 风控与受理拦截 `FP-60` ~ `FP-79`

这类失败在受理阶段被拦下。

码	英文	中文	可重试	建议动作
FP-60	Card temporarily blocked	该卡已被风控锁定	否	引导更换支付方式
FP-61	Card BIN not accepted	卡 BIN 不在允许范围内	否	引导更换支付方式
FP-62	Too many failed attempts with this card	该卡连续失败次数超限	否	引导更换支付方式，或稍后再试
FP-63	No available acquiring channel	无可用受理通道	是	稍后重试；持续出现请联系我们
FP-64	Daily limit exceeded	超出单日限额	是	次日重试，或联系我们调整额度
FP-65	Payment method not enabled	未开通该支付方式	否	联系我们开通
FP-66	Amount exceeds merchant limit	订单金额超出单笔限额	否	调整金额，或联系我们调整额度

6. 请求参数或配置错误 `FP-80` ~ `FP-89`

这一组不是持卡人的问题，重试无用。请检查对接实现或联系我们。

码	英文	中文	说明
FP-80	Amount below minimum	金额低于下限	调整金额
FP-81	Amount above maximum	金额高于上限	调整金额
FP-82	Invalid or missing parameter	请求参数缺失或非法	检查请求报文
FP-83	Payment method not supported	不支持此支付方式	联系我们确认支持范围
FP-84	Currency does not match payment method	币种与支付方式不匹配	核对币种
FP-85	Account configuration error	受理账户配置错误	联系我们处理
FP-86	Order state does not allow this operation	订单状态不允许该操作	先查单确认当前状态
FP-87	Resource missing or duplicated	资源不存在或已存在	核对订单号与请求幂等性

7. 系统异常 `FP-90` ~ `FP-99`

码	英文	中文	建议动作
FP-90	System error	系统异常	退避后重试
FP-91	Rate limited	请求过于频繁	退避后重试
FP-92	Request timed out	请求超时	先查单确认最终状态，再决定是否重试，避免重复扣款
FP-93	Concurrent request conflict	并发冲突	稍后重试
FP-99	Unclassified failure	未识别的失败原因	持续出现请联系我们

8. 覆盖范围

并非所有失败场景都会返回 refusalReasonCode。请按下表编写代码，不要假设该字段一定存在。

场景	是否返回错误码
未开启 3DS 的卡支付，当场被拒	✅
代扣 / 订阅扣款失败	✅
绑卡（零元授权）失败	✅
风控或参数拦截	✅
请求参数、配置错误	✅
3DS 认证流程中失败	❌
查单接口	❌
异步通知	❌

开启 3DS 时，下单接口先返回跳转指引，最终结果由查单与异步通知给出，这两条链路当前版本尚未携带错误码，将在后续版本补齐。

9. 接入示例

建议按号段处理，并兼容字段缺失：

String code = response.getRefusalReasonCode();

if (code == null) {
    // 当前版本尚未覆盖的场景，退回按 refusalReason 展示
    showMessage(response.getRefusalReason());
} else if (code.compareTo("FP-30") < 0) {
    // FP-01 ~ FP-29 硬拒：不要重试，引导更换支付方式
    promptChangePaymentMethod();
} else if (code.compareTo("FP-60") < 0) {
    // FP-30 ~ FP-59 软拒：提示重试或修正卡信息
    promptRetryOrFixCardInfo(code);
} else if (code.compareTo("FP-80") < 0) {
    // FP-60 ~ FP-79 风控与受理拦截：多数不应重试
    promptChangePaymentMethod();
} else if (code.compareTo("FP-90") < 0) {
    // FP-80 ~ FP-89 对接或配置问题：不要重试，记录并告警
    alertIntegrationIssue(code);
} else {
    // FP-90 ~ FP-99 系统异常：退避后重试；FP-92 需先查单
    retryWithBackoff(code);
}

FP-xx 按字符串比较即可，号段边界与第 2 节一致。

10. 变更记录

日期	版本	变更
2026-09-20	v1.0	首版。新增 `refusalReasonCode` 字段

1. 响应字段

2. 号段规则

3. 硬拒 FP-01 ~ FP-29

4. 软拒 FP-30 ~ FP-59

4.1 发卡行原因 FP-30 ~ FP-39

4.2 限额相关 FP-40 ~ FP-44

4.3 卡信息填写 FP-45 ~ FP-53

4.4 认证相关 FP-55 ~ FP-59

5. 风控与受理拦截 FP-60 ~ FP-79

6. 请求参数或配置错误 FP-80 ~ FP-89

7. 系统异常 FP-90 ~ FP-99