# Auth-Capture 纯API支付集成 ::: tip 该文档介绍纯API支付集成模式的集成流程。 ::: 纯API集成模式下，商户需要自行构建相关的支付页面，如：收银页、支付结果页等，因此，该模式需要商户投入更多的研发成本。 ## 1. 集成准备 + [注册开发者中心账号](https://docs.payermax.com/202606-version/developer/integration-guide.md#_3-2-注册成为开发者)； + [上传测试商户公钥](https://docs.payermax.com/202606-version/developer/integration-guide.md#_3-4-1-配置测试环境的密钥信息)，获取平台公钥、AppID、测试商户号等集成信息； + [配置回调地址（WebHook）](https://docs.payermax.com/202606-version/developer/integration-guide.md#_3-4-2-配置测试环境的回调地址)，包括支付结果回调地址、退款结果回调地址等； + [设置测试环境服务器IP白名单](https://docs.payermax.com/202606-version/developer/integration-guide.md#_3-5-设置测试环境的服务器ip白名单)； + [配置并开通相应支付方式](https://docs.payermax.com/202606-version/developer/integration-guide.md#_3-6-开通集成的支付方式)； + [查看不同环境的请求地址](https://docs.payermax.com/202606-version/developer/integration-guide.md#_2-环境信息)； + [理解请求报文加签和验签的原理](https://docs.payermax.com/202606-version/developer/config-settings.md)，用于生成每次HTTP请求Header的`sign`签名字符串。 ## 2. 交互流程 ```mermaid %%{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 PMServer as PayerMax服务端 participant Channel as 支付渠道 钱包/银行等 %% 1. 下单与发起支付 User->>Client: 1.1 选择商品下单 Client-->>User: 1.2 返回商户收银页 User->>Client: 1.3 填写支付信息 确认支付 Client->>MServer: 1.4 发起支付 MServer->>PMServer: 1.5 创建支付 调用纯API支付接口 PMServer->>Channel: 1.6 支付请求 Channel-->>PMServer: 1.7 返回请求结果 PMServer-->>MServer: 1.8 返回请求结果 可能含redirectURL %% 2. 触发用户认证 rect rgb(235, 245, 255) Note over User, Channel: 用户认证 MServer-->>Client: 1.9 返回请求结果 可能含redirectURL Client->>Client: 2.0 重定向到redirectURL，发起认证 如：钱包登录/3DS认证等 User->>Client: 2.1 输入认证信息 Client->>Channel: 2.2 发送认证请求 Channel->>Channel: 2.3 认证处理 Channel->>Client: 2.4 重定向到商户页面 Channel->>PMServer: 3.1 支付结果通知 end %% 3. 获取支付结果 rect rgb(235, 245, 255) Note over MServer, PMServer: 获取支付结果 Note over MServer, PMServer: 通过支付结果通知 PMServer->>MServer: 4.1 支付结果异步通知 MServer->>MServer: 4.2 更新支付结果 MServer-->>PMServer: 4.3 返回响应 Note over MServer, PMServer: 通过支付订单查询 MServer->>PMServer: 5.1 查询支付订单 PMServer-->>MServer: 5.2 返回支付订单信息 MServer->>MServer: 5.3 更新支付结果 end %% 4. 展示结果 Client->>MServer: 6.1 获取支付结果 Client->>Client: 6.2 展示支付结果 ``` ## 3. 接口列表 | 关联交互时序 | 调用方向 | 接口PATH | | --------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | 1.3 创建支付，调用纯API下单 | `商户` -> `PayerMax` | [/orderAndPay](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderAndPay/post) | | 4.1 支付结果异步通知 | `PayerMax` -> `商户` | [/collectResultNotifyUrl](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/collectResultNotifyUrl/post) | | 5.1 查询支付交易 | `商户` -> `PayerMax` | [/orderQuery](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderQuery/post) | ## 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 创建支付 通过调用[纯API支付/orderAndPay API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderAndPay/post) 接口，发起HTTP POST请求，创建支付。 ::: warning 注意： 商户可以通过接口入参`expireTime`指定单笔支付的支付关单时间，单位是秒，取值须大于1800（30分钟）且小于86400（24小时）。如果传入值小于1800，则系统默认重置为最小值30min；如果传入值小于86400，则系统默认重置为最大值86400。 如果商户不指定，则具体的关单时间，根据使用的支付方式会有所不同。 ::: **关键参数**： | 字段名称 | 字段类型 | 是否必填 | 描述 | | ------------------- | -------- | -------- | ------------------------------------------------------ | | `captureMode` | `string` | `否` | 请款模式：`MANUAL` | | `authorizationType` | `string` | `否` | 授权类型：`PRE_AUTH`，`FINAL_AUTH`；默认为`FINAL_AUTH` | [创建支付/orderAndPay API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderAndPay/post) 接口请求示例： ``` json 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-21T07:56:20.657+00:00", "appId": "test81af1bdd45c4be5318305e279061", "merchantNo": "TEST20118706753", "data": { "outTradeNo": "test598684645", "subject": "Women's Long Skirts", "integrate": "Direct_Payment", "totalAmount": "74.99", "currency": "USD", "country": "AU", "userId": "84645", "language": "en", "reference": "2476598332645", "frontCallbackURL": "https://your.com/checkout-2/order-received/84645", "notifyUrl": "https://your.com/?wc-api=wc_payermaxcallback", "terminalType": "WEB", "paymentDetail": { "paymentMethodType": "CARD", "cardInfo": { "cardIdentifierNo": "455803****0807", "cardHolderFullName": "test holder", "cardExpirationMonth": "08", "cardExpirationYear": "19", "cvv": "808" }, "buyerInfo": { "firstName": "Deborah", "lastName": "Swinstead", "email": "your@gmail.com", "phoneNo": "0609 031 114", "address": "Test Address", "city": "Holden Hill", "region": "SA", "zipCode": "5088", "clientIp": "211.52.321.225", "userAgent": "Mozilla/5.0 (iPad; CPU OS 18_4_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/22E252 [FBAN/FBIOS;FBAV/513.1.0.55.90;FBBV/735017191;FBDV/iPad13,16;FBMD/iPad;FBSN/iPadOS;FBSV/18.4.1;FBSS/2;FBID/tablet;FBLC/en_GB;FBOP/5;FBRV/737247184]" } }, "goodsDetails": [ { "goodsId": "49373", "goodsName": "Women's Long Skirts", "quantity": "2", "price": "38", "goodsCategory": "skirt", "showUrl": "https://your.com/product/womens-floral-print-elastic-high-waist-pleated-ruffle-flowy-long-skirts/" } ], "shippingInfo": { "firstName": "test", "lastName": "test", "email": "test@gmail.com", "phoneNo": "0609 031 114", "address1": "Test Address", "address2": "un", "address3": "Test Address, SA 5088", "city": "Holden Hill", "region": "SA", "state": "SA", "country": "AU", "zipCode": "5088" }, "billingInfo": { "firstName": "test", "lastName": "test", "email": "test@gmail.com", "phoneNo": "0609 031 114", "address1": "Test Address", "address2": "un", "address3": "Test Address, SA 5088", "city": "Holden Hill", "region": "SA", "state": "SA", "country": "AU", "zipCode": "5088" }, "envInfo": { "deviceLanguage": "en-AU", "screenHeight": "1180", "screenWidth": "820" } } }' ``` [创建支付/orderAndPay API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderAndPay/post) 接口响应示例： ``` json { "msg": "Success.", "code": "APPLY_SUCCESS", "data": { "outTradeNo": "test598684645", "tradeToken": "T20290323107917693601854", "status": "SUCCESS" } } ``` 为了保障用户支付安全，PayerMax或支付渠道可能会发起额外的用户认证流程，常见的有[卡支付的3DS支付](https://docs.payermax.com/202606-version/acquiring/start-integration/related-capabilities/3ds.html)、钱包支付的用户登录等。如果触发用户认证，则接口响应中会额外返回`redirectUrl`且`data.status=PENDING`，用户可使用`redirectUrl`重定向跳转到相应页面，用户可在该页面完成认证。 ### 5.2 跳转用户认证 [创建支付/orderAndPay API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderAndPay/post) 接口响应`redirectUrl`表示用户认证页URL，商户接收到响应后，可重定向跳转，用户在该页面完成认证信息填写和提交。 ### 5.3 获取支付结果 #### 5.3.1 支付结果通知 请查看[支付结果-支付结果通知](https://docs.payermax.com/202606-version/acquiring/start-integration/related-capabilities-integration/payment-result.md#_3-1-支付结果通知)。 #### 5.3.2 支付结果查询 请查看[支付结果-支付结果查询](https://docs.payermax.com/202606-version/acquiring/start-integration/related-capabilities-integration/payment-result.md#_3-2-支付结果查询)。 ## 6. 测试上线 在商户完成上述集成步骤后，可以发起实际支付请求进行初步测试验证，具体步骤请查看[集成测试-发起测试](https://docs.payermax.com/202606-version/acquiring/integration-testing-and-troubleshooting/start-a-test.md)。 在测试通过后，最终发布上线前，须联系PayerMax技术支持，提交测试的订单信息，以便于PayerMax检查请求日志和数据，确认您已经正确集成相关能力，具体步骤请查看[集成测试-发起验收](https://docs.payermax.com/202606-version/acquiring/start-integration/golive-confirmation.md)。 验收通过后，商户可以[配置生产环境的集成信息](https://docs.payermax.com/202606-version/developer/integration-guide.md#_7-3-配置生产环境的集成信息)，并准备开量事宜。 另外，在**收单产品集成**下有PayerMax支持的各类支付方式的集成文档，其中包含每种支付方式的测试上线说明。 ## 7. 错误排除 测试或验收过程中的响应错误，可以查看[错误排查-错误码](https://docs.payermax.com/202606-version/acquiring/integration-testing-and-troubleshooting/troubleshooting/error-code.md)。同时，在[常见问题](https://docs.payermax.com/202606-version/appendix/faq/collection/cashier-direct-api.md)中，总结列举各类常见的问题及其处理方式。 您还可以直接联系PayerMax技术支持团队，咨询集成、测试、验收过程中的任何问题。