获取支付结果集成

该文档介绍获取支付结果的集成流程。

1. 集成准备

• 注册开发者中心账号；

• 上传测试商户公钥，获取平台公钥、AppID、测试商户号等集成信息；

• 配置回调地址（WebHook），包括支付结果回调地址、退款结果回调地址等；

• 设置测试环境服务器IP白名单；

• 配置并开通相应支付方式；

• 查看不同环境的请求地址；

• 理解请求报文加签和验签的原理，用于生成每次HTTP请求Header的sign签名字符串；

• 如果商户服务器对外部IP地址访问有限制，则需要将PayerMax服务器IP地址添加到商户服务器的白名单中，生产环境和测试环境IP地址请咨询PayerMax技术支持。

2. 交互流程

3. 接口列表

关联交互时序	调用方向	接口PATH
1.1 支付结果通知	PayerMax -> 商户	/collectResultNotifyUrl
2.1 查询支付交易	商户 -> PayerMax	/orderQuery

4. 集成步骤

PayerMax支持两种方式获取支付结果。支付的结果状态包括如下：

状态	描述	备注
SUCCESS	交易成功	用户支付成功
PENDING	交易处理中	等待用户完成支付
FAILED	交易失败	支付失败
CLOSED	交易关单	用户在有效期内未完成支付

4.1 通过支付结果通知

支付完成后，PayerMax会主动回调商户指定的回调地址，发起支付结果通知 API。PayerMax可能会多次回调通知商户，直到接收到商户的成功响应。

商户可以通过两种方式设置支付结果回调地址：

1. 通过接口参数指定：创建支付时，设置/orderAndPay API 请求入参notifyUrl。该配置仅对单笔支付生效，可覆盖全局配置。

2. 通过商户平台配置：通过PayerMax商户平台，配置统一的支付回调结果地址。该配置对所有支付交易生效。

支付结果通知 API 请求示例：

curl --request POST \
  --url https://pay-gate-uat.payermax.com/collectResultNotifyUrl \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'sign: FPFVT3o227JrFRbqu19boZCpVVTF9KznxyRawUmxpfXilHV/0yK46haPhAjNu1hPUMy7Vw/ILXhfzffNm4Fj0apWknlTY9OJxnSoQxS9BTFtc61tn5yV1q69x/kkBl82/qwg+XTJ4fOzy7Mar3VaC1E2PlDA6RkkKBUyNE6RYgsdB+Su7an4+4HVTNAnoe74WyvBgxTLMNg28igBTdqxaO3w/UBY6ObVp7vkqkQGdL1Y+HgmMYaAVwrM3+ALWGId0sJ+YqTY4WJ+0xCRGhaSnybiIjZsQEYyID68WNUfuavDLDsEhaMm/HfQvf5p0R1Ltovp3wwJnEbQcjY458iX5A==' \
  --data '{
  "code": "APPLY_SUCCESS",
  "msg": "",
  "keyVersion": "1",
  "appId": "3b242b56a8b64274bcc37dac281120e3",
  "merchantNo": "020213827212251",
  "notifyTime": "2022-01-17T09:33:54.540+00:00",
  "notifyType": "PAYMENT",
  "data": {
    "outTradeNo": "P1642410680681",
    "tradeToken": "T2024062702289232000001",
    "totalAmount": 10000,
    "currency": "IDR",
    "country": "ID",
    "status": "SUCCESS",
    "completeTime": "2023-10-20T03:28:23.092Z",
    "paymentDetails": [
      {
        "paymentMethodType": "WALLET",
        "targetOrg": "DANA",
        "paymentTokenID": "PMTOKEN20230710080439571142400031000"
      }
    ],
    "reference": "020213827524152"
  }
}'

商户可以通过data.status判定退款状态。

支付结果通知 API 响应示例：

-- 响应成功
{
  "msg": "Success",
  "code": "SUCCESS" # PayerMax依赖code判定是否通知成功，如果非SUCCESS，则判定通知失败，PayerMax重发。
}

商户接收到支付结果通知后，可返回成功或失败。如果商户未响应或响应失败，则PayerMax会尝试重发支付结果通知，通知频率为0s/30s/300s/600s/3600s/43200s，最多重试6次。

在订单状态不明或者没有收到PayerMax支付结果通知的情况下，商户主动通过支付订单查询，获取支付结果。

4.2 通过支付订单查询

商户还可以通过调用交易查询/orderQuery API 接口，获取支付结果。

交易查询/orderQuery API 接口请求示例：

curl --request POST \
  --url https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/orderQuery \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'sign: FPFVT3o227JrFRbqu19boZCpVVTF9KznxyRawUmxpfXilHV/0yK46haPhAjNu1hPUMy7Vw/ILXhfzffNm4Fj0apWknlTY9OJxnSoQxS9BTFtc61tn5yV1q69x/kkBl82/qwg+XTJ4fOzy7Mar3VaC1E2PlDA6RkkKBUyNE6RYgsdB+Su7an4+4HVTNAnoe74WyvBgxTLMNg28igBTdqxaO3w/UBY6ObVp7vkqkQGdL1Y+HgmMYaAVwrM3+ALWGId0sJ+YqTY4WJ+0xCRGhaSnybiIjZsQEYyID68WNUfuavDLDsEhaMm/HfQvf5p0R1Ltovp3wwJnEbQcjY458iX5A==' \
  --data '{
  "version": "1.4",
  "keyVersion": "1",
  "requestTime": "2022-01-17T07:51:15.597+00:00",
  "appId": "a0dddd1f622243cb9aa1b676e808b5f8",
  "merchantNo": "02021382719993",
  "data": {
    "outTradeNo": "P1642410680681" # 商户单号
  }
}'

交易查询/orderQuery API 接口响应示例：

{
  "msg": "Success.",
  "code": "APPLY_SUCCESS",
  "data": {
    "reference": "reference查询和回调返回",
    "country": "SA",
    "totalAmount": 10,
    "outTradeNo": "DEVTest1669616467952",
    "currency": "SAR",
    "channelNo": "DMCP000000000177005",
    "thirdChannelNo": "4ikqJ6ktEqyRawE1dvqb9c",
    "paymentCode": "2312121212",
    "tradeToken": "T2024062702289232000001",
    "completeTime": "2023-10-20T03:28:23.092Z",
    "paymentDetails": [
      {
        "targetOrg": "*",
        "cardInfo": {
          "cardOrg": "VISA",
          "country": "SA",
          "cardIdentifierNo": "400555******0001",
          "cardIdentifierName": "**ngwei"
        },
        "payAmount": 10,
        "exchangeRate": "1",
        "paymentMethod": "CARD",
        "payCurrency": "SAR",
        "paymentMethodType": "CARD"
      }
    ],
    "fees": {
      "merFee": {
        "url": "https://cashier-n-test-new.payermax.com/static/invoice.html?country=AE&merchantNo=P01010113843429&timestamp=1687769788704&version=1.0&orderTaxToken=XWXFKKBOPExplK4aX0r7wgiMtiAMLBKObPFdCMpM9HmCq3AAOob%252BcAZOkP27Kh3W",
        "amount": "100",
        "currency": "SAR"
      }
    },
    "status": "SUCCESS",
    "resultMsg": ""
  }
}

商户可以通过请求响应中的code判定本次查询请求是否成功，通过data.status进一步判定退款状态，请勿使用code或msg或data.resultMsg判定退款状态。

5. 测试上线

在商户完成上述集成步骤后，可以发起实际支付请求进行初步测试验证，具体步骤请查看集成测试-发起测试。

在测试通过后，最终发布上线前，须联系PayerMax技术支持，提交测试的订单信息，以便于PayerMax检查请求日志和数据，确认您已经正确集成相关能力，具体步骤请查看集成测试-发起验收。

验收通过后，商户可以配置生产环境的集成信息，并准备开量事宜。

另外，在收单产品集成下有PayerMax支持的各类支付方式的集成文档，其中包含每种支付方式的测试上线说明。

6. 错误排除

测试或验收过程中的响应错误，可以查看错误排查-错误码。同时，在常见问题中，总结列举各类常见的问题及其处理方式。

您还可以直接联系PayerMax技术支持团队，咨询集成、测试、验收过程中的任何问题。