# 支付结果

## 1. 交互流程

```mermaid
%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#e6f0ff',
    'primaryTextColor': '#333',
    'primaryBorderColor': '#5b9bd5',
    'lineColor': '#888',
    'actorMargin': 40,
    'noteBkgColor': '#0056b3',
    'noteTextColor': '#ffffff',
    'noteBorderColor': '#004a99'
  }
}}%%
sequenceDiagram
    participant Client as 商户端
    participant PM as PayerMax

    %% 1. 首次通知
    PM->>Client: 1.1 支付结果通知
    Client->>PM: 1.2 响应结果

    %% 2. 重发支付结果逻辑
    rect rgb(235, 245, 255)
        Note over Client, PM: 重发支付结果
        Note right of Client: 如果商户响应结果Code不等于SUCCESS
        PM->>Client: 1.3 重发支付结果
    end

    %% 3. 主动查询
    Client->>PM: 2.1 查询支付订单
    PM-->>Client: 2.2 返回支付订单详情
```

## 2. 接口列表

| 关联交互时序     | 调用方向             | 接口PATH                                                                                                                                        |
| ---------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| 1.1 支付结果通知 | `PayerMax` -> `商户` | [/collectResultNotifyUrl](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/collectResultNotifyUrl/post)   |
| 2.1 查询支付交易 | `商户` -> `PayerMax` | [/orderQuery](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderQuery/post) |

## 3. 获取支付结果

当订单到达终态，PayerMax会通过 [支付结果通知](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/collectResultNotifyUrl/post) 同步商户支付状态，商户也可主动查询获取支付状态。
支付状态如下：

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

### 3.1 支付结果通知

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

  - 通过接口参数指定：创建支付时，设置[/orderAndPay API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderAndPay/post) 请求入参`notifyUrl`。该配置仅对单笔支付生效，可覆盖商户平台配置。

  - 通过商户平台配置：通过PayerMax商户平台 **设置服务** → **开发参数**，配置统一的支付回调结果地址。该配置对所有支付交易生效。

  [支付结果通知 API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/collectResultNotifyUrl/post) 请求示例：

``` json
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", //通过data.status判定支付状态
    "completeTime": "2023-10-20T03:28:23.092Z",
    "paymentDetails": [
      {
        "paymentMethodType": "WALLET",
        "targetOrg": "DANA",
        "paymentTokenID": "PMTOKEN20230710080439571142400031000"
      }
    ],
    "reference": "020213827524152"
  }
}'
```

[支付结果通知 API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/collectResultNotifyUrl/post) 响应示例：
>收到通知请按照示例响应，不响应或响应有误，PayerMax均会重试6次；  
>因对响应有误会触发线上异常告警，若长期响应有误，系统可能静默您的告警功能，届时告警将全面失效。

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

### 3.2 支付结果查询

[交易查询/orderQuery API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderQuery/post) 接口请求示例：

``` json
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](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderQuery/post) 接口响应示例：

``` json
{
  "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": ""
  }
}
```

## 4. FAQ

**1. 重复收到通知**

如商户未响应或响应失败（code非SUCCESS），PayerMax会重发支付结果通知，通知频率为`0s/30s/300s/600s/3600s/43200s`，最多重试`6次`。

**2. PayerMax什么情况下会发送回调**

当支付到达终态（成功/失败/关单）时会发送回调