常见问题
按对接主题整理常见问题。完整字段和示例请查看对应接口页面。
接入与请求
如何获取后台访问权限和测试凭证？
请联系对接团队获取后台访问权限、应用凭证及测试方式。接口地址与凭证说明见环境与凭证。
H5 和 Deeplink 有什么区别？
H5 建单使用 create_order，通过响应中的 pay_url 打开支付页面。Deeplink 建单使用 create_deeplink_order，返回 payee_account、default_open_url、wallet_options 等支付信息；两种接口的响应字段不同。见 H5 建单和 Deeplink 建单。
钱包链接为空怎么办？能指定只显示二维码吗？
H5 响应的 meta 钱包链接可以为空，请使用 pay_url。Deeplink 的钱包链接在 wallet_options 中，wallet_code 包括 paytm、phonepe、gpay；以本笔响应实际返回的选项为准。目前请求参数不支持指定只显示二维码或某个钱包。
返回的 Paytm、PhonePe 链接是否保证可以唤起？打不开怎么办？
wallet_options 表示本笔订单提供的钱包支付选项，不保证在所有设备上都能成功唤起或完成付款。实际兼容性受操作系统、浏览器、钱包安装情况和版本等影响，不能仅凭 UPI 地址后缀判断。请原样使用返回链接，不要自行替换 UPI 地址或链接格式。打不开时先确认是否已扣款；未扣款可尝试本笔返回的其他支付选项。已扣款时不要重复付款，请提供订单号、设备及钱包信息联系客服。钱包唤起不代表付款成功，结果以验签通过的成功回调或查单 status=20 为准。
哪个字段传我们的订单号？没有平台订单号还能查单吗？
建单时通过 tenant_order_no 传入商户订单号。查单时，tenant_order_no 与 platform_order_no 至少提供一个；同时提供时，两者须对应同一订单。见代收查单和代付查单。
重复提交相同商户订单号，会创建第二笔代付吗？
代付对相同商户订单号提供重复提交校验：关键参数一致，且原订单未失败、取消、过期或冲正时，返回原订单，包括已成功订单，不创建第二笔。关键参数冲突，或原订单处于上述失败、取消、过期、冲正状态时，返回 100409。代收新订单请使用唯一商户订单号。建单结果不明时，先通过原订单号查单确认。见代付建单。
请求体可以发 Base64 或 JSON 字符串吗？
请发送 JSON 对象，并设置 Content-Type: application/json。不要将整个请求编码成 Base64，也不要再次把 JSON 对象编码为带外层引号的字符串。格式见请求与响应。
timestamp 使用秒还是毫秒？日期采用什么格式？
timestamp 使用当前 Unix 秒级时间戳，不是毫秒。pay_time、created_at 等业务日期采用 YYYY-MM-DD HH:mm:ss，不是 ISO8601；业务时区说明见环境与凭证。
JSON 字段需要按固定顺序发送吗？密钥需要 Base64 解码吗？
JSON 字段顺序不影响验签，但计算签名时须按字段名 ASCII 升序排序。使用提供的 app_secret 原字符串，不做 Base64 解码；保留 0，排除空字符串和 null。完整算法见签名规则。
请求签名需要额外加入 pay_time 和 created_at 吗？
不需要在建单或查单请求中额外添加这两个字段。请求签名按该接口实际发送的非空参数计算，排除 sign。回调若包含这两个日期字段，验签时按收到的原值参与计算，排除的是 signature，不要转换日期格式。
金额与手续费
金额支持小数吗？
支持，例如 "35.44"。建议以十进制字符串发送金额，并在签名时保持同一表示方式；"200" 与 "200.00" 的签名字符串不同。
pay_sum 可以与 order_sum 不同吗？
可以。order_sum 是建单提交的金额，pay_sum 是客户应付金额。例如订单金额为 100.00，响应的应付金额可能为 100.07 或 99.97。请按返回的支付指引付款，不要自行改写应付金额；应付金额不表示已经到账。
回调的 amount 是用户实付金额吗？
代收回调的 amount 是原订单金额。应付金额通过 H5 的 payable_amount 或 Deeplink 的 pay_sum 获取；代收查单的 paid_amount 是系统已确认的付款金额，不应仅凭该字段推断玩家银行账户的实际扣款。当前回调没有专用的玩家实际扣款字段，商户净入账以最终回调的 settlement_amount 为准。见金额说明。
付款金额与 pay_sum 不同，还会自动成功吗？
请按本笔返回的 pay_sum 准确付款。金额不同不能保证自动确认，也不能只按差额大小判断成功或失败。请提供 UTR 并通过提交 UTR验证；验证通过后可能自动确认，无需所有情况都人工处理。提交后仍未确认成功的，请提供订单号、UTR 和付款凭证联系客服，不要自行将订单标为成功。
人工核对后确认成功，回调金额和结算金额如何确定？
人工核对后，代收回调的 amount 仍是原订单金额，total_fee 是该笔手续费，settlement_amount 是确认后的商户净入账金额。人工处理不代表一律按原订单金额或玩家提交的金额结算；请以核对结果及最终回调的 settlement_amount 为准，不要仅用 pay_sum 或自行计算 amount - total_fee 代替。具体订单有疑问时请提供订单号联系客服核实。
少付会按原金额入账吗？多付的差额会自动退回吗？
不要把少付视为原订单全额到账，也不要假设多付差额会自动退回。少付、多付均应提供订单号、UTR 和付款凭证核对实际收款及处理安排。系统不会仅因存在差额就自动补足付款或向玩家退回差额；是否可以入账或退回、按哪个金额处理，请联系客服确认。
amount=1000.00、total_fee=10.00 时，用户应收 1000 还是 990？
代付收款人应收本金为 1000.00，不是 990.00；商户本金及手续费合计通常为 1010.00。代收的净结算金额则可能为 990.00。total_fee 是该订单手续费，settlement_amount 在代收和代付中的含义不同，详见金额说明。
冻结余额是什么意思？与可用余额有什么区别？
冻结余额是已占用、暂不可使用的资金。例如代付建单时会冻结本金及手续费，付款完成后结算，失败等释放资金。余额接口的 balance 为可用余额，freezeBalance 为冻结余额；其他余额字段见余额查询。
付款参数
payment_type=1 表示什么？每笔都固定为 1 吗？
1 表示银行卡付款，2 表示 UPI 付款。请按本笔付款方式选择：银行卡填写收款人姓名和银行账号，UPI 填写 payee_upi。完整字段见代付建单。
payer_name 是必填字段吗？
Deeplink 建单中为选填字符串，最多 128 字符。H5 建单的请求参数不包含该字段。
payee_account_name 和 payee_account_no 如何填写？
payment_type=1 时，两者均必填，最多各 100 字符。payee_account_name 填真实收款人姓名；payee_account_no 填真实银行账号并保留前导零。请勿将姓名和账号填反。
payee_bank_name 必填吗？有完整银行名称列表吗？
payee_bank_name 为选填字符串，最多 100 字符。填写时请使用收款银行的标准名称。文档不提供银行名称枚举列表；不要填写与实际收款银行无关的名称。
IFSC 和银行账号的格式有什么区别？
payee_bank_code 表示银行支行 IFSC，标准格式为 ^[A-Za-z]{4}0[A-Za-z0-9]{6}$，例如 SBIN0001234。payee_account_no 是银行账号，不是 IFSC。请从收款人取得真实账号和支行编码；IFSC 的填写要求按已开通的付款方式确认。
收款人手机号和姓名如何填写？
payee_phone 为选填字符串，最多 20 字符，请填写真实手机号。银行卡付款的 payee_account_name 最多 100 字符，请填写与收款账户对应的真实姓名。具体字段要求见代付建单。
查单与订单状态
HTTP 200 或建单 success=true 表示付款成功吗？
不是。HTTP 状态表示请求处理情况；建单 success=true、code=200 表示建单操作成功，不表示客户已付款或收款人已到账。付款结果通过查单或回调中的订单状态确认，成功为 20。
代付查单 status=1 是什么状态？
1 表示代付订单已创建、待处理，不是成功或失败的最终结果。2、10、11、30 也不是付款成功；完整定义见订单状态。
如何区分处理中、成功、失败和退款状态？
20 表示成功；40 表示失败；41 表示取消；43 表示过期；44 表示退款／冲正。0、10、30 为非成功的处理中状态，代付还包括 1、2、11。代收过期及后续付款确认的说明见订单状态。
查单返回 203006，是否可以直接认为交易失败？
203006 表示本次查询未找到可返回的订单，不是付款失败状态。请核对订单号；两个单号同时传入时须对应同一订单。此前建单结果不明时，请使用原商户订单号核对，并提供 request_id 联系对接团队。
代收 status=43 后还会变成成功吗？会收到回调吗？
43 表示支付窗口已过期。后续付款被确认时，状态仍可能更新为 20；配置了 notify_url 的订单会发送成功通知，查单也会反映更新。自动过期本身不发送失败回调；有效期以响应中的过期时间为准。见订单状态。
43 经过多久能确定不会再成功？可以明确取消付款吗？
目前没有可承诺的统一截止时间或取消接口，能保证过期代收订单之后不会再支付成功。query_order 持续返回 43，只表示查询时订单仍为过期状态，不是确定未收款的证明。需要退款、关闭业务或重新支付同一笔款项前，请提供原订单号、付款时间及已有的 UTR 联系客服核实结果；不要仅凭 43 自动退款或重复发起付款。
代收失败后，后续确认付款会更新结果吗？
代收在后续确认付款后，可能更新此前失败或过期的结果。请通过原订单查单和支付结果回调确认当前状态，完整定义见订单状态。
44 Reversed / Refund 表示成功吗？是争议状态吗？
44 表示退款／冲正，不是成功，也不是单独的争议状态。当前状态表没有独立的争议状态，详细定义见订单状态。
回调与 UTR
Deeplink 自建支付页的手动转账，建议要求客户提供 UTR 吗？
建议对复制 UPI 地址后手动转账的付款流程要求客户在付款后提供 UTR。请提示客户使用本笔订单的支付信息，在有效期内按 pay_sum 准确付款，再由商户服务端调用提交 UTR。该接口的 platform_order_no 使用 Deeplink 建单返回的 trade_no。付款结果仍以验签通过的成功回调或查单 status=20 为准。
手动转账金额正确但没有提交 UTR，会自动匹配吗？
可能得到付款确认，但在没有订单参考信息或 UTR 时，不能保证仅凭付款金额就自动关联到正确订单。金额相同或付款截图都不能单独作为订单成功依据。请尽量收集 UTR 并提交验证；无法提供 UTR 或付款仍未确认时，请提供订单号和付款凭证联系客服。
提交 UTR 是否一定能自动入账？
不能保证。submitted_utr 用于提交付款参考号并验证，不是要求直接将订单改成成功。验证通过后可能确认付款并发送成功回调，但提交动作或 HTTP 200 本身都不是到账证明。请通过验签后的成功回调或原订单查单 status=20 确认；验证未通过或结果仍不明确时，请联系客服，不要重复付款。
有 webhook 吗？notify_url 与 return_url 有何区别？
有。请在建单时提供商户自己的 notify_url，用于接收服务端支付结果；未提供时，不发送该订单回调。H5 的 return_url 用于浏览器返回，不能替代 webhook。Deeplink 和代付建单文档不包含 return_url 参数。
订单回调是 GET 还是 POST？
订单结果回调使用 POST，正文为 JSON。请将浏览器访问与服务端回调分开处理。如实际观察到 GET，请提供订单号、请求地址及接收日志，由对接团队核对。
哪里可以找到成功回调正文和 cURL 示例？
代收回调和代付回调页面均提供字段、带签名 JSON 及 cURL 示例。
回调接口返回 HTTP 200 就算接收成功吗？
请返回 HTTP 200，正文使用纯文本 success 或 ok。只有 HTTP 200，或正文为 {"status":200}，不足以确认接收。接收应答示例见代收回调和代付回调。
status=20 但 notify_status=3，订单成功还是失败？
付款结果是成功。status 是订单状态，notify_status 是通知状态；3 表示通知失败，可能是接收地址不可达或应答未被确认。请核对建单时的 notify_url 和接收应答，并提供订单号协助排查。
同一订单为什么会收到多次成功回调？
同一订单的成功通知可能重复发送。相同订单号的重复 20 通知对应同一笔付款，不表示新增一笔交易。成功接收后，请按回调文档返回确认应答。
代收、代付回调和查单都会返回 UTR 吗？
成功回调在取得支付参考号时返回 utr，未取得时可省略。代付查单包含 utr，未取得时可为空；当前代收 query_order 不包含该字段，按参考号查询请使用UTR 查询。
错误与排查
100422 Request parameter error 应该检查什么？
请按对应接口核对必填字段、数据类型和格式。代付还应核对 payment_type 对应的收款人字段，确认姓名与账号没有填反，并确认请求体为 JSON 对象。需要协助时提供脱敏请求、响应和 request_id；不要发送真实密钥。
202003 应用程序密钥无效是什么意思？
请确认 tenant_id 与 app_key 属于同一商户应用，并使用对接团队提供的正确凭证。不要将 app_secret 当作 app_key。错误码说明见错误码。
代付余额不足返回什么错误码？
可用余额加信用额度不足以覆盖代付本金及手续费时，返回 203005。该码也用于其他建单失败情况，请结合 message 查看说明；余额字段见余额查询。
建单遇到超时、连接错误或 HTTP 500，可以标记失败吗？
这些结果不能单独确定订单是否创建或付款是否完成。请通过原 tenant_order_no 查单；仍无法确认时，提供请求时间、原订单号及 request_id 联系对接团队。处理方式见请求异常。
message 为什么有时是中文、有时是英文？
message 为说明文字，可能使用中文或英文。程序请按 code 判断接口结果，按订单 status 判断付款结果，不要依赖某个固定的消息文本。
失败原因在哪个字段？查单或回调有详细原因吗？
建单失败时查看顶层 code 和 message。当前 query_order 与普通结果回调没有统一的详细失败原因字段。需要具体原因时，请提供商户订单号、平台订单号或 request_id 联系对接团队。