Card Payment - Drop In Integration

This document describes the integration requirements for using card payments under drop in payments.

When integrating card payments through the drop in, merchants do not need to be qualified for PCI authentication because sensitive information such as user information (e.g., user name, card number, CVV, etc.) during the payment process is collected and hosted by the PayerMax component.

1. Integration Preparation

View the Drop In payment-integration preparation .

2. Interactive Process

The main difference compared to the general payment process of Drop In is that when paying by card, users 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 Page as Merchant Page
    participant Component as PayerMax
Pre-built Component
    participant MServer as Merchant Server
    participant PMServer as PayerMax Server
    participant Channel as Payment Channel
Wallet/Bank, etc.

    %% 1. Initialization Flow
    User->>Page: 1.1 Select products and place order
    Page->>MServer: 1.2 Send order info
e.g., Country, Currency, etc.
    MServer->>PMServer: 1.3 Get component initialization info
clientKey and sessionKey
    PMServer-->>MServer: 1.4 Return results
clientKey and sessionKey
    MServer-->>Page: 1.5 Return results
incl. clientKey and sessionKey
    Page->>Component: 1.6 Create and mount PayerMax component

    %% 2. Token Acquisition Flow
    User->>Page: 2.1 User enters payment info
    Page->>Component: 2.2 Obtain paymentToken
    Component->>PMServer: 2.3 Request paymentToken
    PMServer-->>Component: 2.4 Return result
incl. paymentToken
    Component-->>Page: Return paymentToken

    %% 3. Payment & 3DS Authentication
    User->>Page: 3.1 Confirm payment
    Page->>Component: 3.2 Submit payment
incl. paymentToken
    Component->>MServer: 3.3 Submit order
incl. paymentToken
    MServer->>PMServer: 3.4 Create Payment
Call Component Order API
    PMServer->>Channel: 3.5 Payment Request
    PMServer->>Channel: 3.6 3DS Authentication Request
    Channel-->>PMServer: 3.7 Return 3DS request result
    PMServer-->>MServer: 3.8 Request result
incl. 3DS Auth URL
    MServer-->>Component: 3.9 Return result
incl. 3DS Auth URL
    Component-->>Page: 3.10 Return result
    Page->>Page: 3.11 Render 3DS Auth Page
    User->>Page: 3.12 Enter 3DS Auth info

    %% 4. Backend Processing
    Channel-->>PMServer: 3.13 3DS Auth Result
    PMServer->>Channel: 3.14 Proceed with payment
    Channel-->>PMServer: 3.15 Payment Result

    %% --- Obtain 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->>MServer: 4.2 Update payment status
        MServer-->>PMServer: 4.3 Return response
        
        Note over MServer, PMServer: Via Order Query
        MServer->>PMServer: 5.1 Query payment transaction
        PMServer-->>MServer: 5.2 Transaction details, incl. payment result
        MServer->>MServer: 5.3 Update payment status
    end

3. Interface List

View the Drop in 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 Get Drop in Initialization Information

View the Drop in payment - Get Drop in Initialization Information .

5.2 Render the Drop in

View the Drop in payment - Render the Drop in。

5.3 Create Payment

View the Drop in payment - Create Payment.

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.

Under the drop in, payment based on referral card is supported.

5.4 Complete 3DS Authentication

Under the drop in, Directly use PayerMax 3DS service ,PayerMax decides whether to initiate the 3DS authentication process based on internal risk control results, and merchants do not need to perform additional integration work.

5.5 Get Payment Results

View the Drop in 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.