# Auth-Capture Direct API Payment Integration ::: tip This document introduces the integration process of direct API payment integration mode. ::: This document introduces the integration process of direct API payment integration mode. In direct API integration mode, merchants need to build their own payment pages, such as cashier page, payment result page, etc. Therefore, this mode requires merchants to invest more R&D costs. ## 1. Integration Preparation + [Register developer center account](https://docs.payermax.com/en/202606-version/developer/integration-guide.md#_3-2-register-as-a-developer)； + [Upload test merchant public key](https://docs.payermax.com/en/202606-version/developer/integration-guide.md#_3-4-1-configure-key-information-for-the-test-environment)，get the platform public key, AppID, test merchant number and other integration information； + [Configure the callback address (WebHook)](https://docs.payermax.com/en/202606-version/developer/integration-guide.md#_3-4-2-configure-the-callback-address-for-the-test-environment), including the payment result callback address, refund result callback address, and so on; + [Setting up a test environment server IP whitelist](https://docs.payermax.com/en/202606-version/developer/integration-guide.md#_3-5-setting-up-a-whitelist-of-server-ips-for-the-test-environment)； + [Configure and enable the appropriate payment methods](https://docs.payermax.com/en/202606-version/developer/integration-guide.md#_3-6-open-integrated-payment-methods)； + [View request addresses for different environments](https://docs.payermax.com/en/202606-version/developer/integration-guide.md#_2-environmental-information)； + [Understand the principles of request message signing and verification](https://docs.payermax.com/en/202606-version/developer/config-settings.md), for generating a `sign` signature string for each HTTP request Header. ## 2. Interaction Process ```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 User participant Client as Merchant Client participant MServer as Merchant Server participant PMServer as PayerMax Server participant Channel as Payment Channel Wallet/Bank, etc. %% 1. Ordering and Initiating Payment User->>Client: 1.1 Select product and place order Client-->>User: 1.2 Return merchant checkout page User->>Client: 1.3 Fill in payment info Confirm payment Client->>MServer: 1.4 Initiate payment MServer->>PMServer: 1.5 Create payment Call Direct API payment interface PMServer->>Channel: 1.6 Payment request Channel-->>PMServer: 1.7 Return request result PMServer-->>MServer: 1.8 Return request result May include redirectURL %% 2. Trigger User Authentication rect rgb(235, 245, 255) Note over User, Channel: User Authentication MServer-->>Client: 1.9 Return request result May include redirectURL Client->>Client: 2.0 Redirect to redirectURL, initiate authentication e.g., Wallet login / 3DS authentication, etc. User->>Client: 2.1 Enter authentication info Client->>Channel: 2.2 Send authentication request Channel->>Channel: 2.3 Authentication processing Channel->>Client: 2.4 Redirect to merchant page Channel->>PMServer: 3.1 Payment result notification end %% 3. Obtaining Payment Results rect rgb(235, 245, 255) Note over MServer, PMServer: Obtaining Payment Results Note over MServer, PMServer: Via Payment Result Notification PMServer->>MServer: 4.1 Asynchronous notification of payment result MServer->>MServer: 4.2 Update payment result MServer-->>PMServer: 4.3 Return response Note over MServer, PMServer: Via Payment Order Query MServer->>PMServer: 5.1 Query payment order PMServer-->>MServer: 5.2 Return payment order info MServer->>MServer: 5.3 Update payment result end %% 4. Displaying Results Client->>MServer: 6.1 Get payment result Client->>Client: 6.2 Display payment result ``` ## 3. Interface List | Associative Interaction Timing | Calling direction | Interface PATH | | -------------------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | | 1.3 Create a payment, call the cashier's order interface | `Merchant` -> `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 Asynchronous notification of payment results | `PayerMax` -> `Merchant` | [/collectResultNotifyUrl](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/collectResultNotifyUrl/post) | | 5.1 Querying Payment Transactions | `Merchant` -> `PayerMax` | [/orderQuery](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderQuery/post) | ## 4. Environmental Information - **Test environment request address**：https:// `pay-gate-uat.payermax.com`/aggregate-pay/api/gateway/ `` - **Integrated Environment**：https:// `pay-gate.payermax.com`/aggregate-pay/api/gateway/ `` ## 5. Integration Steps ### 5.1 Create Payment Create a payment by calling[Direct API Payment/orderAndPay API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderAndPay/post) interface, initiating an HTTP POST request. ::: warning Note: Merchants can specify the payment close time in seconds for a single payment via the interface entry `expireTime`, the value must be greater than 1800 (30 minutes) and less than 86400 (24 hours). If the value passed in is less than 1800, the system will reset to the minimum value of 30min; if the value passed in is less than 86400, the system will reset to the maximum value of 86400. If the merchant does not specify it, the exact time to close the payment will be different depending on the payment method used. ::: [Create Payment/orderAndPay API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderAndPay/post) Example of an interface request: **Key Parameters** | Field Name | Field Type | Required or Not | Description | | ------------------- | ---------- | --------------- | ------------------------------------------------------------------------- | | `captureMode` | `string` | `No` | Payment mode: `MANUAL` | | `authorizationType` | `string` | `No` | Authorization type: `PRE_AUTH`，`FINAL_AUTH`; the default is `FINAL_AUTH` | ``` 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" } } }' ``` [Create Payment/orderAndPay API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderAndPay/post) Example of an interface response: ``` json { "msg": "Success.", "code": "APPLY_SUCCESS", "data": { "outTradeNo": "test598684645", "tradeToken": "T20290323107917693601854", "status": "SUCCESS" } } ``` In order to protect the security of user payment, PayerMax or payment channels may initiate additional user authentication process, common ones are [3DS in card payment](https://docs.payermax.com/en/202606-version/acquiring/start-integration/related-capabilities/3ds.html), user login for wallet payment and so on. If the user authentication is initiated, the interface response will additionally return `redirectUrl` and `data.status=PENDING`, and the user can use `redirectUrl` to redirect to the corresponding page, where the user can complete the authentication. ### 5.2 Jump to User Authentication [Create Payment/orderAndPay API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderAndPay/post) The interface response `redirectUrl` indicates the user authentication page URL, after the merchant receives the response, it can redirect the jump, and the user completes the authentication information filling and submitting in this page. ### 5.3 Get Payment Result #### 5.3.1 Payment Result Notification See [Get Payment Result Integration - Payment Result Notification](https://docs.payermax.com/en/202606-version/acquiring/start-integration/related-capabilities-integration/payment-result.md#_3-1-payment-result-notification). #### 5.3.2 Payment Result Inquiry See [Get Payment Result Integration - Payment Result Inquiry](https://docs.payermax.com/en/202606-version/acquiring/start-integration/related-capabilities-integration/payment-result.md#_3-2-payment-result-inquiry). ## 6. Test Go Live After the merchant has completed the above integration steps, he/she can initiate the actual payment request for preliminary testing and validation, please refer to [Integration Testing - Start a test](https://docs.payermax.com/en/202606-version/acquiring/integration-testing-and-troubleshooting/start-a-test.md) for the specific steps. After the test is passed and before the final release, the merchant must contact PayerMax technical support to submit the order information for the test so that PayerMax can check the request logs and data to confirm that you have correctly integrated the relevant capabilities, as described in [Integration Testing - Initiate Acceptance](https://docs.payermax.com/en/202606-version/acquiring/start-integration/golive-confirmation.md). After passing the acceptance test, the merchant can [configure integration information for production environments](https://docs.payermax.com/en/202606-version/developer/integration-guide.md#_7-3-configuring-integration-information-for-production-environments) and prepare for the opening of the volume. In addition, under **Acquiring Product Integration**, there are integration documents for the various payment methods supported by PayerMax, which contain instructions for testing each payment method. ## 7. Troubleshooting For response errors during testing or acceptance, you can refer to [Troubleshooting - Error Code](https://docs.payermax.com/en/202606-version/acquiring/integration-testing-and-troubleshooting/troubleshooting/error-code.md). Meanwhile, in [FAQs](https://docs.payermax.com/en/202606-version/appendix/faq/collection/cashier-direct-api.md), we summarize and list all kinds of common problems and how to deal with them. You can also contact PayerMax technical support team directly for any questions during integration, testing and acceptance. You can also contact PayerMax technical support team directly for any questions during integration, testing and acceptance.