收银台支付集成

本文介绍收银台集成模式的集成流程。

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

关于收银台集成模式的更多信息，参看【产品介绍 - 集成模式】。

1. 集成准备

接口注册开发者中心账号；
上传测试商户公钥，获取平台公钥、AppID、测试商户号等集成信息；
配置回调地址（WebHook），包括支付结果回调地址、退款结果回调地址等；
设置测试环境服务器IP白名单；
配置并开通相应支付方式；
查看不同环境的请求地址；
理解请求报文加签和验签的原理，用于生成每次HTTP请求Header的sign签名字符串。

2. 交互流程

3. 接口列表

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

4. 环境信息

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

5. 集成步骤

5.1 创建支付

通过调用创建支付/orderAndPay API 接口，发起HTTP POST请求，创建支付。PayerMax收银台集成模式下，支持商户自定义供用户选择的可用支付方式。如果商户不指定支付方式，默认展示全量支付方式，用户交互界面展示参看【链接】；如果商户指定支付方式，PayerMax收银页会根据请求入参设定，选择性展示部分可用支付方式，用户交互界面展示参看【链接】。

注意：

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

5.1.1 使用所有支付方式

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

curl --request POST \
  --url https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/orderAndPay \
  --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": "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 接口响应示例：

json

{
    "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"
    }
}

5.1.2 使用非CARD支付方式

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

curl --request POST \
  --url https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/orderAndPay \
  --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": "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": "", # 不指定支付机构
        }
    }
}'

如果只指定支付方式，但不指定支付机构，则PayerMax收银页仅会展示该支付方式下的所有支付机构，但不会展示其他支付方式。如上例中，支付国家是印度尼西亚，同时指定支付方式时电子钱包，则PayerMax收银页会展示支持的印尼电子钱包，如：DANA、OVO、GOPAY等。

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

json

{
    "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&currency=IDR&version=1.4&cashierId=T2019051409242877928306&frontCallbackUrl=https%3A%2F%2Fwww.your.com&pmaxLinkV=1",
        "outTradeNo": "TEST39627390559111746827473769",
        "tradeToken": "T2019051409242877928306",
        "status": "PENDING"
    }
}

5.1.3 使用非CARD支付机构

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

curl --request POST \
  --url https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/orderAndPay \
  --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 '{
    "merchantNo": "TEST894366",
    "version": "1.4",
    "keyVersion": "1",
    "requestTime": "2025-05-14T06:30:02.844Z",
    "appId": "testf64019bf1e63ee3fb364c5",
    "data": {
        "outTradeNo": "test_3934784",
        "integrate": "Hosted_Checkout",
        "userId": "test34784",
        "subject": "Number of Coins8200",
        "country": "PH",
        "currency": "USD",
        "totalAmount": "1.00",
        "frontCallbackUrl": "https://your-pay.vshowapi.com/payUrl/return/1747204201786_3934784",
        "expireTime": "1800",
        "reference": "payermax",
        "language": "en",
        "paymentDetail": {
            "paymentMethodType": "WALLET", # 指定支付方式
            "targetOrg": "GCASH" # 指定支付机构
        },
        "notifyUrl": "https://your-pay.vshowapi.com/callback/payermax",
        "terminalType": "WAP"
    }
}'

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

json

{
    "msg": "Success.",
    "code": "APPLY_SUCCESS",
    "data": {
        "redirectUrl": "https://cashier-n.payermax.com/static/processing.html?merchantId=TEST894366&merchantAppId=testf64019bf1e63ee3fb364c5&tradeToken=T2019051406661275799086&country=PH&language=tl&token=0f5444f8f4b045a38f20632575498637&version=1.4&paymentMode=WALLET&targetOrg=GCASH&cashierRequestNo=T202505140666127579908620250514063002952415488&cashierId=T2019051406661275799086&orderLan=tl&countryLan=tl&strategyLan=LUBCO&pmaxLinkV=1",
        "outTradeNo": "test_3934784",
        "tradeToken": "T2019051406661275799086",
        "status": "PENDING"
    }
}

5.1.4 使用CARD支付方式

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

curl --request POST \
  --url https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/orderAndPay \
  --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": "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的支付机构。

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

json

{
    "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&currency=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"
    }
}

5.2 跳转PayerMax收银页

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

5.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：获取支付结果，作为处理依据，以此确保交易状态的准确性。

5.4 获取支付结果

创建支付/orderAndPay API 接口响应的data.status并非支付终态，因此，商户不应直接使用其更新支付结果。

5.4.1 通过支付结果通知

参看【支付结果-通过支付结果查询】。

5.4.2 通过支付订单查询

参看【支付结果-通过支付订单查询】。

6. 测试上线

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

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

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

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

7. 错误排除

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

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

8. 关联文档

【按照支付方式集成】

收银台支付

支付方式列表

纯API支付

前置组件

卡支付

ApplePay

GooglePay

订阅代扣

Tokenization支付

链接支付

交易结果

争议

业务风险管控

API付款

支付方式列表

欧洲

收银台支付集成 ​

1. 集成准备 ​

2. 交互流程 ​

3. 接口列表 ​

4. 环境信息 ​

5. 集成步骤 ​

5.1 创建支付 ​

5.1.1 使用所有支付方式 ​

5.1.2 使用非CARD支付方式 ​

5.1.3 使用非CARD支付机构 ​

5.1.4 使用CARD支付方式 ​

5.2 跳转PayerMax收银页 ​

5.3 跳转支付结果页 ​

5.4 获取支付结果 ​

5.4.1 通过支付结果通知 ​

5.4.2 通过支付订单查询 ​

6. 测试上线 ​

7. 错误排除 ​

8. 关联文档 ​

收银台支付集成

1. 集成准备

2. 交互流程

3. 接口列表

4. 环境信息

5. 集成步骤

5.1 创建支付

5.1.1 使用所有支付方式

5.1.2 使用非CARD支付方式

5.1.3 使用非CARD支付机构

5.1.4 使用CARD支付方式

5.2 跳转PayerMax收银页

5.3 跳转支付结果页

5.4 获取支付结果

5.4.1 通过支付结果通知

5.4.2 通过支付订单查询

6. 测试上线

7. 错误排除

8. 关联文档