收银台支付集成
指定具体支付方式集成模式下，用户下单后，跳转到指定APM钱包页面进行支付。该集成模式下，商户需开发收银台页面。
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.3 支付结果异步通知 | PayerMax -> 商户 | /collectResultNotifyUrl |
| 4.4 查询支付交易 | 商户 -> 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收银页会根据请求入参设定，选择性展示部分可用支付方式。
注意：
商户可以通过接口入参expireTime指定单笔支付的支付关单时间，单位是秒，取值须大于1800（30分钟）且小于86400（24小时）。如果传入值小于1800，则系统默认重置为最小值30min；如果传入值大于86400，则系统默认重置为最大值86400。 如果商户不指定，则具体的关单时间，根据使用的支付方式会有所不同。
4.1.1 使用非CARD支付方式
- 创建支付/orderAndPay API 接口请求示例：
{
"version": "1.4",
"keyVersion": "1",
"requestTime": "2025-05-14T17:25:39.064+08:00",
"appId": "test7e94124c208abbfc7e2792ecfa",
"merchantNo": "TEST0114787283",
"data": {
"outTradeNo": "TEST39627390559111746827473769",
"integrate": "Hosted_Checkout",
"subject": "IDR 53,000",
"totalAmount": "53000",
"currency": "IDR",
"country": "ID",
"userId": "1177295",
"frontCallbackUrl": "https://www.your.com",
"notifyUrl": "https://middlepay.your.com/api_server/v2/finance/callback/order/TEST39627390559111746827473769",
+ "paymentDetail": {
+ "paymentMethodType": "WALLET", # 指定支付方式
+ "targetOrg": "", # 不指定支付机构
}
}
}'如果只指定paymentMethodType，但不指定targetOrg，则PayerMax收银页仅会展示该支付方式下的所有支付机构，但不会展示其他支付方式。如上例中，支付国家是印度尼西亚，同时指定支付方式时电子钱包，则PayerMax收银页会展示支持的印尼电子钱包，如：DANA、OVO、GOPAY等；如果同时指定了 targetOrg为OVO，返回的链接打开会直接跳转到OVO钱包完成支付。
- 创建支付/orderAndPay API 接口响应示例：
{
"msg": "Success.",
"code": "APPLY_SUCCESS",
"data": {
"redirectUrl": "https://cashier-n.payermax.com/v2/index.html#/payments?merchantId=TEST0114787283&merchantAppId=test7e94124c208abbfc7e2792ecfa&country=ID&tradeToken=T2019051409242877928306&paymentMode=WALLET&language=id&token=3acc37542e204765a6d11b86bf0bc930&amount=53000¤cy=IDR&version=1.4&cashierId=T2019051409242877928306&frontCallbackUrl=https%3A%2F%2Fwww.your.com&pmaxLinkV=1",
"outTradeNo": "TEST39627390559111746827473769",
"tradeToken": "T2019051409242877928306",
"status": "PENDING"
}
}4.1.2 使用CARD支付方式
- 创建支付/orderAndPay API 接口请求示例：
{
"version": "1.4",
"keyVersion": 1,
"requestTime": "2025-05-14T16:30:27.174+08:00",
"appId": "test516e8ab74578be8eecd8c4803fbe",
"merchantNo": "TEST010117960578",
"data": {
"outTradeNo": "test5141630270627",
"integrate": "Hosted_Checkout",
"subject": "US $4.99 Stargem",
"totalAmount": 4.99,
"currency": "USD",
"country": "US",
"frontCallbackUrl": "https://pay.your.com/official_v2/redirect/web_payermax_web_v1",
"userId": "test_1743900006925",
"reference": "gp_huq_u",
"notifyUrl": "https://pay.your.com/official_v2/notify/web_payermax_web_v1",
"paymentDetail": {
+ "paymentMethodType": "CARD", # 指定支付方式
+ "allowedCardOrg": [ # 指定卡组，可以为空
+ "MASTERCARD"
]
}
}如果商户希望限定用户支付的卡品牌，可以通过设定请求入参paymentDetail.allowedCardOrg实现。如上例中，指定卡品牌为MASTERCARD，则当PayerMax渲染收银页时，只会展示支持MASTERCARD的支付机构；如不指定allowedCardOrg，会展示所有已签约的卡品牌。
- 创建支付/orderAndPay API 接口响应示例：
{
"msg": "Success.",
"code": "APPLY_SUCCESS",
"data": {
"redirectUrl": "https://cashier-n.payermax.com/v2/index.html#/payments?merchantId=TEST010117960578&merchantAppId=test516e8ab74578be8eecd8c4803fbe&orderNo=test5141630270627&country=US&tradeToken=T2019051408217377899667&paymentMode=CARD&targetOrg=*&token=acd8b556379140ee9a6ea067d6e68e35&amount=4.99¤cy=USD&version=1.4&cashierId=T2019051408217377899667&frontCallbackUrl=https%3A%2F%2Fpay.your.com%2Fofficial_v2%2Fredirect%2Fweb_payermax_web_v1&pmaxLinkV=1",
"outTradeNo": "test5141630270627", # 商户交易单号，与请求中outTradeNo一致
"tradeToken": "T2019051408217377899667", # PayermMax交易单号
"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 通过支付订单查询
请查看支付结果-通过支付订单查询。