# Direct API - CARD

::: tip  

- This document introduces the integration requirements for using bank card payments under the pure API payment model；

- For card payments, if the merchant processes card information on their own, they must possess [PCI DSS compliance certification](https://docs.payermax.com/en/202606-version/acquiring/start-integration/payment-acceptance/API/pcidss.md) and contact the PayerMax business team to provide their PCI certification materials.
:::

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

```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. 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
| Associative Interaction Timing                           | Calling direction        | Interface PATH                                                                                                                                    |
| -------------------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| 4.1 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.3.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)     |
| 4.3.2 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)   |

## 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](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderAndPay/post) interface.

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

[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:

``` json
{
    "version": "1.5",
    "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](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"
    }
}
```

To secure user transactions, PayerMax or the payment channel may initiate an extra user authentication flow. Common ones include [3DS Authentication for Card Payments](http://api-doc-ops.payermax.inner/en/202606-version/acquiring/start-integration/related-capabilities/3ds.html) 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](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderAndPay/post)) 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 Payment Result Notification

See [Get Payment Result Integration - Payment Result Notification](https://docs.payermax.com/en/doc-center/acquiring/start-integration/related-capabilities-integration/payment-result.html#_3-1-payment-result-notification).

#### 4.3.2 Payment Result Inquiry

See [Get Payment Result Integration - Payment Result Inquiry](en/doc-center/acquiring/start-integration/related-capabilities-integration/payment-result.html#_3-2-payment-result-inquiry).

## 5. Payment Elements
### 5.1 International Cards (VISA/MASTERCARD/JCB)

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

Request Example:
``` json
{
    "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.5",
    "merchantNo": "SDP01010114087896"
}
```

### 5.2 Turkey (TROY)
| data.paymentDetail | Parameter           | Required | Example           |
| ------------------ | ------------------- | -------- | ----------------- |
| paymentMethodType  | CARD                | Y        | Fixed value: CARD |
|                    | cardIdentifierNo    | Y        | 4444333322221111  |
|                    | cardExpirationMonth | Y        | 12                |
| cardInfo           | cardExpirationYear  | Y        | 25                |
|                    | cvv                 | Y        | 123               |
|                    | cardHolderFullName  | Y        | Jemy              |
| buyerInfo          | phoneNo             | Y        | 16185342424       |
|                    | phoneNoRegion       | Y        | 90                |

Request Example:

``` json
{
    "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.5",
    "merchantNo": "SDP01010114087896"
}
```

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

Request Example:
```json
{
    "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.5",
    "merchantNo": "SDP01010114087896"
}
```