API - CARD

::: This document introduces the integration workflow for using Card payments in pure API mode. :::

In pure API integration mode, merchants need to build relevant payment pages themselves, such as the checkout page, payment result page, etc. Therefore, this mode requires merchants to invest more R&D costs.

1. Interaction Flow

%%{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. Order Placement & Initiating Payment
    User->>Client: 1.1 Select product and place order
    Client-->>User: 1.2 Return to 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 & invoke pure 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. Triggering 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 to initiate authentication
e.g., Wallet Login / 3DS Authentication, etc.
        User->>Client: 2.1 Enter authentication information
        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 Result
    rect rgb(235, 245, 255)
        Note over MServer, PMServer: Obtain Payment Result
        
        Note over MServer, PMServer: Via Payment Result Notification
        PMServer->>MServer: 4.1 Asynchronous payment result notification
        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 details
        MServer->>MServer: 5.3 Update payment result
    end

    %% 4. Display Result
    Client->>MServer: 6.1 Get payment result
    Client->>Client: 6.2 Display payment result

2. API List

Related Interaction Sequence	Direction	API PATH
4.1 Create payment, invoke pure API order creation	Merchant -> PayerMax	/orderAndPay
4.3.1 Asynchronous payment result notification	PayerMax -> Merchant	/collectResultNotifyUrl
4.3.2 Query payment transaction	Merchant -> PayerMax	/orderQuery

3. Environment Information

• Sandbox Environment: https:// pay-gate-uat.payermax.com/aggregate-pay/api/gateway/ <API PATH>

• Production Environment: https:// pay-gate.payermax.com/aggregate-pay/api/gateway/ <API PATH>

4. Integration Steps

4.1 Create Payment

Create a payment by initiating an HTTP POST request to invoke the Pure API Payment /orderAndPay API interface.

Note:

Merchants can specify the expiration/close time for a single payment transaction through the input parameter expireTime (in seconds). The value must be greater than 1800 (30 minutes) and less than 86400 (24 hours). If the passed value is less than 1800, the system defaults to resetting it to the minimum value of 30 minutes; if the passed value is greater than 86400, the system defaults to resetting it to the maximum value of 86400. If the merchant does not specify it, the specific close time will vary based on the payment method used.

• Request Example for Create Payment /orderAndPay API:

{
    "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]"
            }
        },
        "nodeInfo": {
            "deviceLanguage": "en-AU",
            "screenHeight": "1180",
            "screenWidth": "820"
        }
    }
}

• Response Example for Create Payment /orderAndPay API:

{
    "msg": "Success.",
    "code": "APPLY_SUCCESS",
    "data": {
        "outTradeNo": "test598684645",
        "tradeToken": "T20290323107917693601854",
        "status": "SUCCESS"
    }
}

To secure user transactions, PayerMax or the payment channel may initiate an extra user authentication flow. Common ones include 3DS Authentication for Card Payments and user login for wallet payments. If user authentication is triggered, the interface response will additionally return redirectUrl and data.status=PENDING. Users can utilize this redirectUrl to redirect to the corresponding page and complete the authentication process.

4.2 Redirecting to User Authentication

The redirectUrl returned from the Create Payment /orderAndPay API interface represents the user authentication page URL. Upon receiving the response, the merchant can perform a redirection, allowing the user to fill out and submit their verification info on that page.

4.3 Obtaining Payment Result

4.3.1 Via Payment Result Notification

Please refer to Payment Result - Via Payment Result Notification.

4.3.2 Via Payment Order Query

Please refer to Payment Result - Via Payment Order Query.

5. Payment Elements

5.1 International Cards (VISA/MASTERCARD/JCB)

data.paymentDetail	Parameter	Required	Example
paymentMethodType	CARD	Y	Fixed value: CARD
cardInfo	cardIdentifierNo	Y	4444333322221111
	cardExpirationMonth	Y	12
	cardExpirationYear	Y	25
	cvv	Y	123
	cardHolderFullName	Y	Jemy Cheung

Request Example:

{
    "requestTime": "2025-01-08T20:51:00.802+08:00",
    "keyVersion": "1",
    "data": {
        "totalAmount": "225",
        "currency": "SAR",
        "country": "SA",
        "expireTime": "3600",
        "paymentDetail": {
            "paymentMethodType": "CARD",
            "cardInfo": {
                "cardIdentifierNo": "4444333322221111",
                "cardExpirationMonth": "12",
                "cardExpirationYear": "25",
                "cvv": "123",
                "cardHolderFullName": "Jemy Chueng"
            },
            "buyerInfo": {
                "clientIp": "146.75.136.237",
                "userAgent": "Chrome"
            }
        },
        "frontCallbackUrl": "https://www.baidu.com",
        "subject": "River Game HK Limited",
        "outTradeNo": "ov1_5b89ced71d764ed9994e6882d88082f0",
        "notifyUrl": "https://www.baidu.com",
        "userId": "1447410849000200",
        "integrate": "Direct_Payment",
        "terminalType": "WEB"
    },
    "appId": "8eef820ecbd443b7a608c2e0863750eb",
    "version": "1.4",
    "merchantNo": "SDP01010114087896"
}

5.2 Turkey (TROY)

data.paymentDetail	Parameter	Required	Example
paymentMethodType	CARD	Y	Fixed value: CARD
cardInfo	cardIdentifierNo	Y	4444333322221111
	cardExpirationMonth	Y	12
	cardExpirationYear	Y	25
	cvv	Y	123
	cardHolderFullName	Y	Jemy
buyerInfo	phoneNo	Y	16185342424
	phoneNoRegion	Y	90

Request Example:

{
    "requestTime": "2025-01-15T16:59:00.802+08:00",
    "keyVersion": "1",
    "data": {
        "totalAmount": "225",
        "currency": "TRY",
        "country": "TR",
        "expireTime": "3600",
        "paymentDetail": {
            "paymentMethodType": "CARD",
            "cardInfo": {
                "cardIdentifierNo": "9792063322221111",
                "cardExpirationMonth": "12",
                "cardExpirationYear": "25",
                "cvv": "123",
                "cardHolderFullName": "Bai Li"
            },
            "buyerInfo": {
                "clientIp": "146.75.136.237",
                "userAgent": "Chrome",
                "phoneNo":"16185342424",
                "phoneNoRegion":"90"
            }
        },
        "frontCallbackUrl": "https://www.baidu.com",
        "subject": "River Game HK Limited",
        "outTradeNo": "ov1_5b89ced71d764ed9994e6882d88082f3",
        "notifyUrl": "https://www.baidu.com",
        "userId": "1447410849000200",
        "integrate": "Direct_Payment",
        "terminalType": "WEB"
    },
    "appId": "8eef820ecbd443b7a608c2e0863750eb",
    "version": "1.4",
    "merchantNo": "SDP01010114087896"
}

5.3 Brazil (HIPERCARD/ELO)

data.paymentDetail	Parameter	Required	Example
paymentMethodType	CARD	Y	Fixed value: CARD
cardInfo	cardIdentifierNo	Y	4444333322221111
	cardExpirationMonth	Y	12
	cardExpirationYear	Y	25
	cvv	Y	123
	cardHolderFullName	Y	Jemy
buyerInfo	email	Y	test@gmail.com
	taxType	Y	Fixed value: CPF
	taxNo	Y	Brazilian ID Tax Number (CPF)
	firstName	Y	First Name
	lastName	Y	Last Name

Request Example:

{
    "requestTime": "2025-01-15T17:13:00.802+08:00",
    "keyVersion": "1",
    "data": {
        "totalAmount": "225",
        "currency": "BRL",
        "country": "BR",
        "expireTime": "3600",
        "paymentDetail": {
            "paymentMethodType": "CARD",
            "cardInfo": {
                "cardIdentifierNo": "4573933322221111",
                "cardExpirationMonth": "12",
                "cardExpirationYear": "25",
                "cvv": "123",
                "cardHolderFullName": "Bai Li"
            },
            "buyerInfo": {
                "clientIp": "146.75.136.237",
                "userAgent": "Chrome",
                "email":"payermaxtest@gmail.com",
                "taxType":"CPF",
                "taxNo":"123.456.789-00",
                "firstName":"jemy",
                "lastName":"Cheung"
            }
        },
        "frontCallbackUrl": "https://www.baidu.com",
        "subject": "River Game HK Limited",
        "outTradeNo": "ov1_5b89ced71d764ed9994e6882d88082f5",
        "notifyUrl": "https://www.baidu.com",
        "userId": "1447410849000200",
        "integrate": "Direct_Payment",
        "terminalType": "WEB"
    },
    "appId": "8eef820ecbd443b7a608c2e0863750eb",
    "version": "1.4",
    "merchantNo": "SDP01010114087896"
}