# 获取付款状态 ::: tip 您在成功创建付款后，可通过以下两种方式获取交易状态： - **付款查询接口**：适用于主动轮询，可以获取交易最新状态； - **结果通知回调**：用于异步接收交易最终状态，PayerMax一旦获取了交易的终态，将通过回调通知。 在收到查询响应/结果通知时，可以依据`status`更新交易结果；若交易失败，可以对应`responseCode`和`responseMsg`中的错误信息来提示用户修改。 ::: | 场景 | 推荐方式 | 说明 | | ------------------------ | -------- | -------------------------------- | | 交易状态结果写入核心系统 | 通知回调 | 推送最终态，稳定性高 | | 前端页面实时反馈 | 查询接口 | 可轮询，适用于用户等待场景 | | 回调未收到、异常补偿 | 查询接口 | 定时补偿任务 | | 日常对账、状态归档 | 查询接口 | 支持批量调用、适合清算与核对场景 | ## 1. 付款查询接口 ``` // 接口路径 POST https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/paymentOrderQry ``` [付款查询 API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-paymentOrderQry/post) 支持同步返回交易状态及部分交易信息，便于商户侧流程控制和展示，适用于商户在需要主动掌握交易状态时使用，特别是在以下场景： - 前端用户等待状态确认（如提现后提示到账进度）； - 回调通知失败、延迟或未配置时的补偿方案； - 运营场景中，业务系统需主动拉取交易最新状态以处理用户问询。 ::: warning 注意： 按照API文档中要求的格式进行请求后，当查询响应中`code` = `APPLY_SUCCESS`、`msg` = `Success.`时，代表请求成功，并不代表交易成功。 ::: 需要根据返回`data`体中的`status`字段来判断交易的状态。交易状态的取值包括： | status | 含义 | 说明 | | ------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `PENDING` | 处理中 | 交易仍在处理中，未完成 | | `SUCCESS` | 成功 | 款项已被付款行/钱包成功付出 | | `FAILED` | 失败 | 当付款请求失败时，PayerMax会返回错误码，以便您分析失败原因。详情请参考下方[交易状态/错误码](https://docs.payermax.com/202606-version/appendix/disbursement/transaction-status.md#_3-交易状态-错误码) | | `BOUNCEBACK` | 退票 | 部分国家的金融系统可能存在接收付款后返回成功状态但不为最终结果，可能存在以下情况： - 收款账号被冻结、不正确 - 收款人未向收款行提交相应材料，被收款行拒绝入账 - 银行、清算网络系统问题或其他不可用场景 基于上述情况，PayerMax会将该笔订单的状态由成功变更为退票，并将支付款项返还至商户的对应账户中 | 当返回`status` = `PENDING`时，可结合`subStatus`字段了解交易处理进度。以下为官方定义的子状态： | subStatus | 描述 | 使用指引 | | ----------------- | ---------- | ------------------------------------------------------------------------ | | PEND_RFI_MATERIAL | 待补充材料 | 当进入该状态时，商户需根据邮件或商户后台的提示上传交易补充材料以继续处理 | | REVIEW | 材料审核中 | 材料已上传，等待审核结果（通常为 0-3 工作日） | | TRANSMIT | 交易处理中 | 交易正常处理进行中，无需操作 | ::: warning 注意： 子状态仅在`status` = `PENDING`时返回，用于辅助判断处理中交易的进度。 若返回`code` = `ORDER_NOT_EXIST`，建议延迟`5分钟`重试`2次`以上确认状态。 ::: ## 2. 付款结果回调通知 ``` // 接口路径 POST https://pay-gate-uat.payermax.com/disbursementResultNotifyUrl ``` 平台在交易进入终态时，PayerMax会通过[付款结果通知 API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/disbursementResultNotifyUrl/post) 向商户配置的`notifyUrl`推送状态信息。通知内容结构包含`订单号`、`状态`、`交易金额`、`币种`、`时间`、`收款人信息`、`扣款`和`费用信息`等。 ::: warning 注意： 回调请求中的`code`和`msg`仅代表请求信息，并不代表交易状态信息。不可以根据`code`和`message`更新交易结果，需要根据返回`data`体中的`status`字段来判断交易的状态。 ::: `status`的取值包括： | status | 含义 | 说明 | | ------------ | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `SUCCESS` | 成功 | 款项已被付款行/钱包成功付出 | | `FAILED` | 失败 | 当付款请求失败时，PayerMax会返回错误码，以便您分析失败原因。详情请参考下方[交易状态/错误码](https://docs.payermax.com/202606-version/appendix/disbursement/transaction-status.md#_3-交易状态-错误码) | | `BOUNCEBACK` | 退票 | 部分国家的金融系统可能存在接收付款后返回成功状态但不为最终结果，可能存在以下情况： - 收款账号被冻结、不正确 - 收款人未向收款行提交相应材料，被收款行拒绝入账 - 银行、清算网络系统问题或其他不可用场景 基于上述情况，PayerMax会将该笔订单的状态由成功变更为退票，并将支付款项返还至商户的对应账户中 | 商户收到通知后需正确响应。格式为： ```json { "msg": "Success", "code": "SUCCESS" } ``` ::: danger 特别提醒： - PayerMax可能会因网络异常重发通知，您需要确保接口的幂等性（即同一笔订单的多次通知，您的系统应返回相同且成功的结果，避免重复处理）。 - 在收到PayerMax结果通知时，您需要正确响应；若未正确响应，PayerMax系统将判定本次通知失败，并按照以下时间间隔发起重试：`0s`/`30s`/`300s`/`600s`/`3600s`/`43200s （12小时）`，直到成功送达或已重试6次。请注意，在极端情况下，即使完成全部重试，仍可能无法成功送达通知。 - 在订单状态不明或者没有收到PayerMax付款结果通知的情况下，建议您主动调用PayerMax的付款查询接口确认订单状态。 ::: ## 3. 交易状态/错误码 交易返回失败或退票的终态时，能够通过[付款结果通知 API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/disbursementResultNotifyUrl/post) 和 [付款查询 API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-paymentOrderQry/post) 获取订单失败或被退回的原因，可参考如下的错误码和错误描述： | 分类 | 子分类 | 错误码 | 错误描述 | 备注 | | ------------ | ------------------ | ------------------------------------ | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------ | | | | 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_CANCELED | Payment canceled. | 付款已被付款方撤销 | | | 其他异常 | PAYMENT_FAILED | Payment failed | 交易失败，请联系PayerMax | | | | PROVIDER_FAILED_PROCESS | Provider failed to process, please retry later | 交易失败，请稍后重新发起 |