全量收银台集成

收银台集成模式下，用户下单后，跳转到PayerMax构建的H5收银页面支付。PayerMax H5收银页面展示可选的支付方式列表，同时支持自适应设备屏幕大小、多语言等特性。该集成模式下，商户无需开发收银台页面，可极大简化商户集成，缩短上线周期。

1. 交互流程

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#e6f0ff',
    'primaryTextColor': '#333',
    'primaryBorderColor': '#5b9bd5',
    'lineColor': '#888',
    'actorMargin': 40,
    'noteBkgColor': '#0056b3',
    'noteTextColor': '#ffffff',
    'noteBorderColor': '#004a99'
  }
}}%%
sequenceDiagram
    participant User as 用户
    participant Client as 商户客户端
    participant MServer as 商户服务端
    participant Checkout as PayerMax收银页
    participant PMServer as PayerMax服务器
    participant Channel as 支付渠道
钱包/银行等

    %% 1. 下单阶段
    User->>Client: 1.1 选择商品下单
    Client->>MServer: 1.2 下单
    MServer->>PMServer: 1.3 创建支付
调用收银台下单接口
    PMServer->>PMServer: 创建交易
    PMServer-->>MServer: 1.4 返回创建支付响应
含PayerMax收银页URL
    MServer-->>Client: 1.4 返回响应
    Client->>Checkout: 2.1 重定向，打开PayerMax收银页

    %% 2. 支付阶段
    User->>Checkout: 3.1 选择支付方式
并提交支付
    Checkout->>PMServer: 3.2 支付请求
    PMServer->>Channel: 3.3 支付请求
    PMServer-->>Checkout: 3.4 响应
含PayerMax支付结果页URL
    Checkout->>Checkout: 3.5 重定向，跳转至PayerMax支付结果页

    %% 3. 返回商户
    User->>Checkout: 4.1 用户点击【返回商户】
    Checkout-->>Client: 4.2 重定向，跳转至商户指定页面

    %% 4. 获取支付结果
    rect rgb(235, 245, 255)
        Note over MServer, PMServer: 获取支付结果
        
        Note over MServer, PMServer: 通过支付结果通知
        PMServer->>MServer: 5.1 支付结果异步通知
        MServer->>MServer: 5.2 更新支付结果
        MServer-->>PMServer: 5.3 返回响应

        Note over MServer, PMServer: 通过支付订单查询
        MServer->>PMServer: 6.1 查询支付交易单
        PMServer-->>MServer: 6.2 交易详情，含支付结果
        MServer->>MServer: 6.3 更新支付结果
    end

2. 接口列表

关联交互时序	调用方向	接口PATH
4.1 创建支付，调用收银台下单接口	商户 -> PayerMax	/orderAndPay
4.4 支付结果异步通知	PayerMax -> 商户	/collectResultNotifyUrl
6.1 查询支付交易	商户 -> PayerMax	/orderQuery

3. 环境信息

• 测试环境：https:// pay-gate-uat.payermax.com/aggregate-pay/api/gateway/ <接口PATH>

• 集成环境：https:// pay-gate.payermax.com/aggregate-pay/api/gateway/ <接口PATH>

4. 集成步骤

4.1 创建支付

通过调用创建支付/orderAndPay API 接口，发起HTTP POST请求，创建支付。PayerMax收银台集成模式下，支持商户自定义供用户选择的可用支付方式。如果商户不指定paymentDetail参数，默认展示已经签约的所有支付方式。

注意：

商户可以通过接口入参expireTime指定单笔支付的支付关单时间，单位是秒，取值须大于1800（30分钟）且小于86400（24小时）。如果传入值小于1800，则系统默认重置为最小值30min；如果传入值大于86400，则系统默认重置为最大值86400。

如果商户不指定，则具体的关单时间，根据使用的支付方式会有所不同。

创建支付/orderAndPay API 接口请求示例：

{
    "version": "1.4",
    "keyVersion": "1",
    "requestTime": "2025-05-14T06:29:50.085+00:00",
    "appId": "testb427ca0ef77d19bd25c83",
    "merchantNo": "TEST081764",
    "data": {
        "outTradeNo": "PTEST93137249",
        "subject": "diamond 700",
        "totalAmount": 3.99,
        "currency": "USD",
        "country": "US",
        "userId": "1800110891",
        "language": "en", #指定PayerMax收银页展示语言
        "frontCallbackUrl": "https://your-payment.33t8y678tyy6rt.top/payment/front_callback?flag=ipaMbjQuest", # 用户支付完成后，跳转的商户页面
        "notifyUrl": "https://your-payment.33t8y678tyy6rt.top/payment/payment_callback", # 支付结果回调通知URL，如果不指定，则默认使用商户在PayerMax商户平台配置的支付结果回调通知地址。
        "reference": "your special info", # 自定义附加数据，在支付结果回调时，PayerMax会将该信息返回给商户。       
        "integrate": "Hosted_Checkout",
        "expireTime": "1200" # 设定该笔支付的过期时间为1200秒，即用户20分钟内未完成支付，则PayerMax系统关单，判定支付失败。
    }
}'

如果商户不希望每次支付时都传递notifyUrl，则可以通过PayerMax商户平台，配置统一的支付回调结果地址。

• 创建支付/orderAndPay API 接口响应示例：

{
    "msg": "Success.",
    "code": "APPLY_SUCCESS",
    "data": {
        "redirectUrl": "https://cashier-n.payermax.com/v2/index.html#/payments?merchantId=TEST081764&merchantAppId=testb427ca0ef77d19bd25c83&country=US&tradeToken=T2019051406423972799219&language=en&token=358746abf4754e1cba682d1391336734&amount=3.99&currency=USD&version=1.4&cashierId=T2019051406423972799219&frontCallbackUrl=https%3A%2F%2Fyour-payment.33t8y678tyy6rt.top%2Fpayment%2Ffront_callback%3Fflag%3DipaMbjQuest&pmaxLinkV=1",
        "outTradeNo": "PTEST93137249",
        "tradeToken": "T2019051406423972799219",
        "status": "PENDING"
    }
}

4.2 跳转PayerMax收银页

创建支付/orderAndPay API 接口响应redirectUrl表示PayerMax收银页URL，商户接收到响应后，可重定向跳转PayerMax收银页，用户在该页面完成支付。

4.3 跳转支付结果页

用户完成支付后，PayerMax收银页会重定向跳转至PayerMax支付结果页。PayerMax支付结果页会展示支付结果（如下图所示），页面中包含 关闭 或 返回 按钮，用户点击后，跳转到商户指定的页面frontCallBackUrl。

商户应该保证自己传入的frontCallBackUrl在外部浏览器上可用。不同frontCallBackUrl形式的跳转差异如下：

frontCallBackUrl形式	支付完成后跳转流程	是否推荐	优点	缺点
普通h5 (http/https)	停留在系统浏览器，展示该H5页面	否	/	不具备唤起APP能力
内置主动唤起 APP逻辑h5 (http/https)	展示该H5页面，同时由页面内逻辑主动识别场景进行商户APP唤起操作，或停留在本页面	是	逻辑灵活、流程可控	开发复杂，要唤起APP仍需搭配 URL Scheme 或 AppLink/Universal Link 使用
URL Scheme (自定义scheme://)	展系统自动尝试唤起Scheme指定APP。 若APP存在且具备权限，可打开对应APP； 若APP不存在或无权限，停留在系统浏览器，展示空白页	否	简单易开发	无降级逻辑，未唤起 APP 时将展示空白页
AppLink/Universal Link (http/https)	系统自动尝试唤起Scheme指定APP。 若APP存在且具备权限，可打开对应APP； 若APP不存在或无权限，停留在系统浏览器，展示降级H5页面内容	是	开发逻辑相对简单、可降级使用H5处理业务逻辑

返回商户的URL由两部分组成，第一部分是创建支付/orderAndPay API 接口请求的frontCallbackUrl，第二部分是PayerMax附加的额外参数。如下是一个完整的跳转URL示例：

其中PayerMax附加的额外参数包括：

• outTradeNo：商户订单号；

• tradeToken：PayerMax订单号；

• status：订单状态。特别注意的是，请勿直接使用该值更新商户订单状态，应按照步骤4：获取支付结果，作为处理依据，以此确保交易状态的准确性。

4.4 获取支付结果

4.4.1 通过支付结果通知

请查看支付结果-通过支付结果通知。

4.4.2 通过支付订单查询

请查看支付结果-通过支付订单查询。