目录

1. 接口功能

此接口可用于查询指定订单当前的支付状态。

2. 调用场景

用户完成支付后，有时会由于网络异常、应用异常退出、应用服务器故障、应用客户端问题等原因，应用无法获取用户实际支付结果，导致未及时发放用户购买的商品，从而出现掉单的情况。此时应用可以调用此接口查询实际支付结果。
实际支付处理时，以下场景需要调用此接口查询订单：
● 应用具备订单查询功能，用户进入订单后，应用主动查询用户的订单状态。
● 在出现掉单情况后应用将未支付成功的订单号保存，用户每次登录应用，应用需要根据订单号查询订单状态。如果已支付成功则删除本地订单号，如果仍未成功则继续定时查询。
● 支付过程中出现以下支付异常，应用需要立即查询订单的真实状态。如果订单状态仍在处理中，需要继续定时查询，直至订单成功或失败。
    − 应用在支付过程异常中断（关机、程序崩溃等），支付结果码为-1005。
    − 支付后onActivityResult回调参数resultCode不为Activity.RESULT_OK。
    − 支付结果码为30002，30005，30006，30008，30012，30013。
    − 支付结果码为0但是验签失败。

没有服务器的单机应用，只能调用getOrderDetail接口查询订单。有独立开发者服务器的应用，除了调用getOrderDetail接口，还可以直接向开发者服务器查询订单。

3. 调用方法

  1. HMSAgent.Pay.getOrderDetail(OrderRequest request, GetOrderHandler handler);

4. 请求参数

参数名称必选(M)/可选(O)类型参数说明
request
M
OrderRequest
查询订单信息的请求参数信息。
handler
M
GetOrderHandler
接口调用后的回调结果，结果中包含的具体参数参见结果回调。
OrderRequest
参数名称必选(M)/可选(O类型是否参与签名参数说明
merchantId
M
string
是
商户ID，即华为开发者联盟给开发者分配的“支付ID”。
支付ID的查询方法请参见查询支付服务信息。
requestId
M
string
是

需要查询订单详情的支付订单号。支付订单号由开发者应用在支付时自行生成，用来唯一标识一次支付请求，订单号生成后开发者应用需自行维护订单号。

注意：
该字段中不能包含特殊字符，包括# " & / ? $ ^ *:) \ < > , | .并且不支持中文。
keyType
M
string
是
秘钥类型。当前请填写固定值“1”，表示商户秘钥。
time
M
string
是
当前时间的时间戳，即当前时间距离1970年的毫秒数。
sign
M
string
否
用于验签的签名字符串。
为防止请求被篡改，应用需要根据支付签名的生成方法中的方法生成签名字符串，华为服务器在收到请求后会对签名字符串进行验签，验签成功后才会进行后续处理，否则将返回失败错误码。

5.结果回调

  1. public interface GetOrderHandler { 
  2.     /** 
  3.     * 订单查询结果回调 
  4.     * @param retCode 返回码 
  5.     * @param checkPayResult 订单结果信息 
  6.     */ 
  7.     void onResult(int retCode, OrderResult checkPayResult); 
  8. }
参数名称必选(M)/可选(O)类型参数说明
retCode
M
int
回调结果中订单查询结果的返回码，应用可以根据返回码判断查询是否成功或失败后如何处理，具体返回码参见返回码。
checkPayResult
M
查询结果的对象信息。
获取checkPayResult对象中参数值时，请使用“对象名称.get参数名称()”的方式，参数名首字母大写。例如，“checkPayResult.getStatus()”为获取到的订单支付状态。
OrderResult
参数名称必选(M)/可选(O)类型是否参与验签参数说明
returnCode
M
int
是
查询结果的业务返回码，即与当前查询业务相关而非HMS SDK错误导致的错误码。
当有业务返回码时，HMS SDK会将此值赋值给retCode，具体请参见返回码中的业务错误码。
returnDesc
M
string
是
返回码描述信息。
requestId
O
string
是
应用侧生成的支付订单号，与请求参数中的requestId一致。
应用可以根据此订单号识别本次回调结果所属的订单。
此参数仅在returnCode等于0返回。
orderID
O
string
是
华为支付平台订单号，在华为支付平台中唯一标识本次支付请求。
当支付出现异常需要华为协助定位时，开发者可提供华为支付平台的订单号作为依据。
此参数仅在查询成功时，即returnCode等于0返回。
orderTime
O
string
是
下单时间，即用户点击购买后华为支付服务器收到应用订单请求的时间，格式为yyyy-MM-dd HH:mm:ss。
此参数仅在returnCode等于0返回。
tradeTime
O
string
是
支付完成时间，即用户实际完成付款后华为支付服务器处理支付成功的时间，格式为yyyy-MM-dd HH:mm:ss。
此参数仅在returnCode等于0返回。
status
O
string
是
订单的支付状态。
●0：订单支付失败。
●1：订单支付完成。
●2：未处理，订单可能在等待支付或者等待支付应答，1天之内可以再次查询，1天后仍未处理则作为支付失败处理。
●3：订单在处理中，1天之内可以再次查询，1天后仍在处理中则作为支付失败处理。
sign
O
string
否
查询响应的签名字符串。
应用可以参考对响应消息验签的方法对签名字符串进行验签，确认响应消息是否被篡改。
此参数仅在returnCode等于0时返回。

6.返回码

类型返回码常量返回码值返回码说明处理建议
通用返回码
参见通用返回码。
业务返回码
PayStatusCodes.PAY_STATE_SUCCESS
0
查询成功。

PayStatusCodes.PAY_STATE_FAILED
-1
通用失败错误码。
查询失败，查询流程结束，需重新调用接口。
PayStatusCodes.PAY_STATE_PARAM_ERROR
30001
参数错误（包含无参）。
请检查请求参数是否遗漏，参数值格式是否正确。
PayStatusCodes.PAY_STATE_TIME_OUT
30002
订单查询超时。
向用户给出提示，并定时调用getOrderDetail重新查询。
PayStatusCodes.PAY_RESULT_INVALID_REQUEST
30004
非法请求，例如：开发者服务器IP地址没有报备、请求中的签名字符串错误。
请检查请求中签名字符串是否按规定算法准确生成。
PayStatusCodes.PAY_STATE_NET_ERROR
30005
网络连接异常。
向用户给出提示，请用户检查网络后再重试。
PayStatusCodes.ORDER_STATUS_HANDLING
30012
订单正在处理中。
向用户给出提示，并定时调用getOrderDetail重新查询，1天后仍未处理则作为支付失败处理。
PayStatusCodes.ORDER_STATUS_UNTREATED
30013
订单还未处理，订单可能在等待支付或者等待支付应答。
向用户给出提示，并定时调用getOrderDetail重新查询，1天后仍在处理中则作为支付失败处理。
PayStatusCodes.PAY_OTHER_ERROR
30006
除以上错误以外的其他异常错误。
请联系华为技术支持定位。

7.调用示例

  1. HMSAgent.Pay.getOrderDetail(or, new GetOrderHandler() {
  2.   @Override
  3.   public void onResult(int retCode, OrderResult checkPayResult) {
  4.     showLog("checkPay: requId="+reqId+" retCode=" + retCode);
  5.     if (checkPayResult != null && checkPayResult.getReturnCode() == retCode) {
  6.       // 处理返回码
  7.       if (retCode == HMSAgent.AgentResultCode.HMSAGENT_SUCCESS) {
  8.         boolean checkRst = PaySignUtil.checkSign(checkPayResult, pay_pub_key);
  9.         if (checkRst) {
  10.           //TODO: 支付成功，发放对应商品
  11.           showLog("checkPay: Pay successfully, distribution of goods");
  12.         } else {
  13.            //TODO: 验签失败，当支付失败处理 
  14.           showLog("checkPay: Failed to verify signature, pay failed");
  15.         }
  16.         // 不需要再查询
  17.         removeCacheRequestId(checkPayResult.getRequestId());
  18.       } else if (retCode == PayStatusCodes.ORDER_STATUS_HANDLING
  19.               || retCode == PayStatusCodes.ORDER_STATUS_UNTREATED
  20.               || retCode == PayStatusCodes.PAY_STATE_TIME_OUT) {
  21.         //TODO: 未处理完，需要重新查询。如30分钟后再次查询。超过24小时当支付失败处理 
  22.         showLog("checkPay: Pay failed. errorCode="+retCode+" errMsg=" + checkPayResult.getReturnDesc());
  23.       } else if (retCode == PayStatusCodes.PAY_STATE_NET_ERROR) {
  24.         //TODO：网络失败，需要重新查询
  25.         showLog("checkPay: A network problem caused the payment to fail. errorCode="+retCode+" errMsg=" + checkPayResult.getReturnDesc());
  26.       } else {
  27.         //TODO： 支付失败，不需要再查询
  28.         showLog("checkPay: Pay failed. errorCode="+retCode+" errMsg=" + checkPayResult.getReturnDesc());
  29.         removeCacheRequestId(reqId);
  30.       }
  31.     } else {
  32.       //TODO: 没有结果回来，需要重新查询。如30分钟后再次查询。超过24小时当支付失败处理
  33.       showLog("checkPay: Pay failed. errorCode="+retCode);
  34.     }
  35.   }
  36. });