交易状态/错误码
1. 交易状态
当PayerMax受理您的付款请求后，通过查询API或通知均可感知到付款状态。您可以通过获取交易状态，从而制定业务流程。付款交易状态枚举如下：
| 状态 | 描述 | 使用指引 |
| SUCCESS | 交易成功 | / |
| FAILED | 交易失败 | 在发起付款申请后，订单会进入PENDING状态，当订单到达终态（SUCCESS/FAILED/BOUNCEBACK）时，PayerMax会通过【付款结果通知】发送支付结果； 您也可以通过【付款查询】来确认订单最新状态，当订单状态为PENDING时，请参考到账时效后进行查询 |
| PENDING | 交易处理中 | 当付款请求失败时，PayerMax会返回错误码，以便您分析失败原因。详情请参考下方【错误码列表】 |
| BOUNCEBACK | 出款退票 | 部分国家的金融系统可能存在接收付款申请后返回成功状态但不为最终结果，可能存在以下情况： - 收款账号被冻结或不正确 - 银行、清算网络系统问题或其他不可用场景 基于上述情况，PayerMax会将该笔订单的状态由成功变更为退票，并将支付款项返还至商户的对应账户中 |
2. 错误码
该页列出了通过PayerMax付款申请API/商户平台付款时，付款请求失败时可能返回的所有错误信息。
2.1 错误码分类
2.2 错误示例
PayerMax对外API提供了稳定的服务，若出现异常则会在http接口响应的body中告知您错误信息，例如：
json
{
"msg":"Invalid account or not active",
"code":"INVALID_ACCOUNT"
}同样，在异步的回调中，也会响应失败信息，例如：
json
{
"appId":"4701b0a908a14312b3c8452b448256dw",
"code":"APPLY_SUCCESS",
"data":{
"transactionUtcTime":"2024-08-29T12:50:38 +0000",
"trade":{
"amount":"12.00",
"currency":"IDR"
},
"tradeNo":"20240829125038ED1229154469502120T05",
"fundsFreezeTime":"2024-08-29T12:50:46 +0000",
"outTradeNo":"Test1724935838415867",
"payFinishTime":"2024-08-29T12:50:46 +0000",
"destination":{
"amount":"12.00",
"taxCurrency":"IDR",
"exchangeRate":"1",
"fee":"0.00",
"feeCurrency":"IDR",
"currency":"IDR",
"tax":"0.00"
},
"source":{
"amount":"13.00",
"taxCurrency":"IDR",
"exchangeRate":"1",
"fee":"1.00",
"feeCurrency":"IDR",
"currency":"IDR",
"tax":"0.00"
},
"responseCode":"INVALID_ACCOUNT",
"responseMsg":"Invalid account or not active",
"status":"FAILD"
},
"keyVersion":"1",
"merchantNo":"010113827355079",
"msg":"Success.",
"notifyTime":"2024-08-29T12:50:46.458Z",
"notifyType":"PAYOUT"
}2.3 错误码列表
2.3.1 服务端请求限制
在发起付款申请时，您可能遇到的「服务端请求限制」类的错误码如下：
| 分类 | 错误码 | 错误描述 | 备注 |
| 服务端请求限制 | REQ_TIME_OVER_TIME | requestTime effective in two minutes | 请求时间与服务端偏差超过2分钟，请检查requestTime后重新发起 |
| ILLEGAL_IP_REQUEST | illegal ip request | 请求IP需要加入白名单，请联系PayerMax | |
| TOO_MANY_REQUEST | Exceed request limitation, please retry later | 触发接口并发限流,请稍后重试 |
2.3.2 商户配置校验
在发起付款申请时，您可能遇到的「商户配置校验」类的错误码如下：
| 分类 | 子分类 | 错误码 | 错误描述 | 备注 |
| 商户配置校验 | 签名/密钥配置校验 | MERCHANT_APP_INVALID | Signature key is not configured. | 密钥未配置，请尽快配置秘钥 |
| SIGN_VERIFY_FAILED | The signature verify failed. | 验签失败，请检查秘钥或签名逻辑 | ||
| 合约可用性校验 | CONTRACT_INVALID | Merchant has not signed the contract or payment methods. | 未签约或未开通该支付方式，请检查合约开通情况 | |
| MERCHANT_INVALID | The merchant has been offline. | 商户已下线，如有疑问请联系PayerMax |
2.3.3 订单信息接收
在发起付款申请时，您可能遇到的「订单信息接收」类的错误码如下：
| 分类 | 子分类 | 错误码 | 错误描述 | 备注 |
| 订单信息接收 | 请求参数校验 | PARAMS_INVALID | The {field} is incorrect. | 【字段】校验不符合规则，请参考《付款申请模板及填写规范》查看对应支付方式下的字段规则 |
| PARAMS_INVALID | The {field} is incorrect，you should fill {?} | 【字段】校验不符合规则，请根据提示并参考《付款申请模板及填写规范》查看对应支付方式下的字段规则 | ||
| ORDER_REPEAT | The order number repeat. | 订单号重复，请修改后重新发起 | ||
| 其他异常 | SYSTEM_ERROR | System is busy, Please try again later. | 系统异常，请检查订单状态，如落单失败则重新发起 |
2.3.4 订单信息校验
在发起付款申请时，您可能遇到的「订单信息校验」类的错误码如下：
| 分类 | 子分类 | 错误码 | 错误描述 | 备注 |
| 订单信息校验 | 支付方式可用性 | PAYMENT_METHOD_NOT_AVAILABLE | The payment method is not available, plz try other payment methods. | 该支付方式不可用，请尝试其他支付方式或联系PayerMax |
| UNSUPPORTED_ACCOUNT_TYPE | Unsupported account type | 账户类型不支持，请修改后重新发起 | ||
| UNSUPPORTED_BANK | Bank account invalid or bank not supported | 不支持的银行或账号无效,请检查后重新发起 | ||
| 发起金额不符合规则 | AMOUNT_LIMIT_UNMATCHED | The single transfer amount does not meet the limit requirements | 该笔交易金额不满足限额要求,请修改后重新发起 | |
| TRANSACTION_MINIMUM_LIMIT | The transaction amount is below the minimum limit. | 该笔交易金额低于最低限额,请修改后重新发起 | ||
| TRANSACTION_MAXIMUM_LIMIT | The transaction amount exceeds the maximum limit. | 该笔交易金额高于最大限额,请修改后重新发起 | ||
| AMOUNT_NOT_ENOUGH | Insufficient balance | 余额不足，请确保余额充足后重新发起 | ||
| ZERO_DEDUCTION_AMOUNT | Too small transaction amount, the actual deduction amount is 0. | 当扣款币种与付款币种不一致时，请保证预计扣款金额大于0 | ||
| ZERO_CREDITED_AMOUNT | Too small transaction amount, the actual payment amount is 0 after fees deduction. | 请保证预计付款金额大于手续费 | ||
| 收款方交易金额限制 | PAYEE_AMOUNT_EXCEED_LIMIT | Exceed user amount limit | 达到收款方金额限制，请联系收款方确认 | |
| PAYEE_DAILY_AMOUNT_EXCEED_LIMIT | Exceed payee daily cumulative amount limit. | 达到收款方日累计限额，请联系收款方确认 | ||
| PAYEE_MONTHLY_AMOUNT_EXCEED_LIMIT | Exceed payee monthly cumulative amount limit. | 达到收款方月累计限额，请联系收款方确认 | ||
| PAYEE_CUMULATIVE_AMOUNT_EXCEED_LIMIT | Exceed payee cumulative amount limit. | 达到收款方累计限额，请联系收款方确认 | ||
| 收款方交易次数限制 | TRANSACTION_EXCEED_LIMIT | Transaction exceed limit, please retry later. | 达到累计交易次数限制，请联系收款方确认 | |
| EXCEED_DAILY_TIME_LIMIT | The payee account has exceeded the daily transaction times limit | 达到每日交易次数限制，请联系收款方确认 | ||
| EXCEED_MONTHLY_TIME_LIMIT | The payee account has exceeded the monthly transaction times limit | 达到每月交易次数限制，请联系收款方确认 | ||
| 收款方账号校验 | ACCOUNT_BLOCKED | Account blocked or frozen | 账号关闭或者冻结，请联系收款方确认 | |
| INVALID_ACCOUNT | Invalid account or not active | 收款账号无效或不可用，请联系收款方确认 | ||
| INVALID_ACCOUNT_FORMAT | Invalid account format | 账号格式错误，请修改后重新发起 | ||
| NONEXISTENT_ACCOUNT | Account does not exist. | 账号不存在，请联系收款方确认 | ||
| ACCOUNT_NOT_ACTIVATED | Account not activated. | 账号未激活，请联系收款方确认 | ||
| 二级商户信息校验 | SUBMERCHANT_NOT_REGISTERED | The subMerchantNo is not registered | 未能查到二级商户信息，请核实二级商户信息或联系PayerMax平台协助处理 | |
| SUBMERCHANT_REGISTRATION_FAILED | The subMerchantNo registration failed | 二级商户信息报备未通过，请重新报备二级商户信息后重试 | ||
| 收款方其他参数校验 | INVALID_BANK_BRANCH | Invalid bank branch | 银行分行号码无效，请联系收款方确认 | |
| INVALID_BANKCODE | Invalid bankCode | 银行代码无效，请联系收款方确认 | ||
| INVALID_PAYEE_NAME | Invalid payee name | 姓名格式无效，请修改后重新提交 | ||
| INVALID_PHONE_NO | Invalid mobile number | 无效手机号，请联系收款方确认 | ||
| INVALID_ADDRESS | Invalid Address | 无效地址，请修改后重新发起 | ||
| INVALID_EMAIL | Email address is incorrect. | 无效邮箱，请联系收款方确认 | ||
| INVALID_IDENTIFICATION | Invalid identification | 收款方证件信息有误，请修改后重新发起 | ||
| INVALID_IFSC_CODE | Invalid IFSC Code | 无效IFSC Code，请联系收款方确认 | ||
| INVALID_OPERATOR | Invalid operator | 手机号无法匹配到运营商，请确认手机号无误后重新发起 | ||
| PROVIDER_REFUSED_PROCESS | Provider refused to process, please recheck the payee information. | 收款方信息有误，请修改后重新发起 | ||
| 付款失效 | REDEEMCODE_EXPIRED | RedeemCode has expired | 收款方未在约定时间内完成取款，请联系收款方后重新发起 | |
| 付款要素匹配校验 | MISMATCHED_BANK | Account does not match the bank. | 账号和银行不匹配，请联系收款方确认 | |
| MISMATCHED_IDENTIFICATION | The identification type does not match the document number. | 证件类型和证件不匹配，请联系收款方确认 | ||
| MISMATCHED_ACCOUNT | Account type does not match the account number. | 账号类型和账号不匹配，请联系收款方确认 | ||
| MISMATCHED_CURRENCY | The specified currency does not match the payee account. | 收款账号不支持该币种，请联系收款方提供新的收款账号 | ||
| MISMATCHED_NAME | Payee name does not match the payee account. | 姓名和账号不匹配，请联系收款方确认 | ||
| 风控拦截 | RFI_BLACKLIST | Rejected due to failure of beneficiary to submit request information | 未能提交RFI材料,交易拒绝 | |
| DECLINED_BY_RISK | Beneficiary bank rejected credit for a reason. Eg:Declined by risk | 风控拒绝 | ||
| 其他异常 | PAYMENT_FAILED | Payment failed | 交易失败，请联系PayerMax | |
| PROVIDER_FAILED_PROCESS | Provider failed to process, please retry later | 交易失败，请稍后重新发起 |
2.3.5 订单交易查询
在发起付款申请后，您可以通过【付款查询】查询相应的订单信息；可能遇到的「订单信息校验」类的错误码如下：
| 分类 | 错误码 | 错误描述 | 备注 |
| 订单交易查询 | ORDER_NOT_EXIST | The order does not exist. | 该订单不存在或正在处理中，请检查后重新发起 |