Card Payment - Cashier Mode Integration

This document describes the integration requirements for using card payments under Cashier Payments.

1. Integration Preparation

View the cashier-payment-integration-preparation .

2. Interactive Process

The main difference when it comes to integrated card payments compared to the common process for cashier payments is that the user may need to complete an additional 3DS authentication process.

%%{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 Checkout as PayerMax Cashier
    participant PMServer as PayerMax Server
    participant Channel as Payment Channel

    %% 1. Order Flow
    User->>Client: 1.1 Select products and place order
    Client->>MServer: 1.2 Select products and place order
    MServer->>PMServer: 1.3 Create Payment
Call Cashier Order API
    PMServer-->>MServer: 1.4 Return Payment Response
(Includes PayerMax Cashier URL)
    MServer-->>Client: 1.4 Return Response
    Client->>Checkout: 2.1 Redirect to PayerMax Cashier

    %% 2. Payment & 3DS Authentication
    User->>Checkout: 3.1 Select payment method
and submit payment
    Checkout->>PMServer: 3.2 Payment Request
    PMServer->>Channel: 3.3 Create Transaction
& Proceed with payment
    PMServer->>Channel: 3.4 3DS Authentication Request
    Channel-->>PMServer: 3.5 Return 3DS request result
    PMServer-->>Checkout: 3.6 Request Result
(Includes 3DS Auth URL)

    Checkout->>Checkout: 3.7 Redirect to 3DS Auth Page
    User->>Checkout: 3.8 Complete 3DS Authentication
    Checkout->>Checkout: 3.9 Redirect to PayerMax Payment Result Page
    User->>Checkout: 3.10 Click "Back to Merchant"
    Checkout-->>Client: 3.11 Redirect to Merchant Specified Page

    %% Backend Result Processing
    Channel-->>PMServer: 3.12 3DS Authentication Result
    PMServer->>Channel: 3.13 Proceed with Payment
    Channel-->>PMServer: 3.14 Payment Result

    %% --- Get Payment Result Section ---
    rect rgb(235, 245, 255)
        Note over MServer, PMServer: Obtain Payment Result
        
        Note over MServer, PMServer: Via Payment Notification
        PMServer->>MServer: 4.1 Asynchronous Payment Notification (Webhook)
        MServer-->>PMServer: 4.2 Acknowledge Receipt
        
        Note over MServer, PMServer: Via Order Query
        MServer->>PMServer: 5.1 Query Payment Transaction
        PMServer-->>MServer: 5.2 Transaction Details (Includes Result)
    end

3. Interface List

View the cashier-payment-interface list.

4. Environmental Information

• Test Environment：https:// pay-gate-uat.payermax.com/aggregate-pay/api/gateway/ <Interface PATH>

• Integrated Environment：https:// pay-gate.payermax.com/aggregate-pay/api/gateway/ <Interface PATH>

5. Integration Steps

5.1 Create Payment

View the Cashier Payment - Create Payment - Use CARD Payment Methods ; Payment based on referral card is supported.

You can specify the card group using the data.paymentDetail.allowedCardOrg request parameter. For information on card groups for payment in different countries, please see the Payment Method List.

5.2 Jump to PayerMax Checkout Page

View the Cashier Payment - Jump to PayerMax Cashier Page .

5.3 Completion of 3DS Certification

Under cashier payment, Using PayerMax 3DS service directly, and PayerMax decides whether to initiate the 3DS authentication process based on the results of internal risk control, with no additional integration work required for merchants.

5.4 Jump to Payment Result Page

View the Cashier Payment - Jump to Payment Result Page .

5.5 Get Payment Results

View the Cashier Payment - Get Payment Results .

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 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.

After passing the acceptance test, the merchant can configure 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. Meanwhile, in FAQs, 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.