# 纯API - CARD

::: tip  
- 该文档介绍纯API支付下，使用银行卡支付的集成要求；
- 在卡支付下，如果商户自行处理卡信息，须具备[PCI DSS认证资质](https://docs.payermax.com/202606-version/acquiring/start-integration/payment-acceptance/API/pcidss.md)，并联系PayerMax商务团队，提供PCI认证材料。
:::

纯API集成模式下，商户需要自行构建相关的支付页面，如：收银页、支付结果页等，因此，该模式需要商户投入更多的研发成本。

## 1. 交互流程

```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 用户
    participant Client as 商户客户端
    participant MServer as 商户服务端
    participant PMServer as PayerMax服务端
    participant Channel as 支付渠道
钱包/银行等

    %% 1. 下单与发起支付
    User->>Client: 1.1 选择商品下单
    Client-->>User: 1.2 返回商户收银页
    User->>Client: 1.3 填写支付信息
确认支付
    Client->>MServer: 1.4 发起支付
    MServer->>PMServer: 1.5 创建支付
调用纯API支付接口
    PMServer->>Channel: 1.6 支付请求
    Channel-->>PMServer: 1.7 返回请求结果
    PMServer-->>MServer: 1.8 返回请求结果
可能含redirectURL

    %% 2. 触发用户认证
    rect rgb(235, 245, 255)
        Note over User, Channel: 用户认证
        MServer-->>Client: 1.9 返回请求结果
可能含redirectURL
        Client->>Client: 2.0 重定向到redirectURL，发起认证
如：钱包登录/3DS认证等
        User->>Client: 2.1 输入认证信息
        Client->>Channel: 2.2 发送认证请求
        Channel->>Channel: 2.3 认证处理
        Channel->>Client: 2.4 重定向到商户页面
        Channel->>PMServer: 3.1 支付结果通知
    end

    %% 3. 获取支付结果
    rect rgb(235, 245, 255)
        Note over MServer, PMServer: 获取支付结果
        
        Note over MServer, PMServer: 通过支付结果通知
        PMServer->>MServer: 4.1 支付结果异步通知
        MServer->>MServer: 4.2 更新支付结果
        MServer-->>PMServer: 4.3 返回响应

        Note over MServer, PMServer: 通过支付订单查询
        MServer->>PMServer: 5.1 查询支付订单
        PMServer-->>MServer: 5.2 返回支付订单信息
        MServer->>MServer: 5.3 更新支付结果
    end

    %% 4. 展示结果
    Client->>MServer: 6.1 获取支付结果
    Client->>Client: 6.2 展示支付结果
```

## 2. 接口列表

| 关联交互时序                | 调用方向             | 接口PATH                                                                                                                                          |
| --------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| 4.1 创建支付，调用纯API下单 | `商户` -> `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 支付结果异步通知      | `PayerMax` -> `商户` | [/collectResultNotifyUrl](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/collectResultNotifyUrl/post)     |
| 4.3.2 查询支付交易          | `商户` -> `PayerMax` | [/orderQuery](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderQuery/post)   |

## 3. 环境信息

- **测试环境**：https:// `pay-gate-uat.payermax.com`/aggregate-pay/api/gateway/ `<接口PATH>`

- **集成环境**：https:// `pay-gate.payermax.com`/aggregate-pay/api/gateway/ `<接口PATH>`

## 4. 集成步骤

### 4.1 创建支付

通过调用[纯API支付/orderAndPay API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderAndPay/post) 接口，发起HTTP POST请求，创建支付。

::: warning 注意：
商户可以通过接口入参`expireTime`指定单笔支付的支付关单时间，单位是秒，取值须大于1800（30分钟）且小于86400（24小时）。如果传入值小于1800，则系统默认重置为最小值30min；如果传入值大于86400，则系统默认重置为最大值86400。
如果商户不指定，则具体的关单时间，根据使用的支付方式会有所不同。
:::

- [创建支付/orderAndPay API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderAndPay/post) 接口请求示例：

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

- [创建支付/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"
    }
}
```

为了保障用户支付安全，PayerMax或支付渠道可能会发起额外的用户认证流程，常见的有[卡支付的3DS支付](https://docs.payermax.com/202606-version/acquiring/start-integration/related-capabilities/3ds.html)、钱包支付的用户登录等。如果触发用户认证，则接口响应中会额外返回`redirectUrl`且`data.status=PENDING`，用户可使用`redirectUrl`重定向跳转到相应页面，用户可在该页面完成认证。

### 4.2 跳转用户认证

[创建支付/orderAndPay API](https://docs.payermax.com/api.html?docName=New%20Version&docVer=v1.0&docLang=cn#/paths/aggregate-pay-api-gateway-orderAndPay/post) 接口响应`redirectUrl`表示用户认证页URL，商户接收到响应后，可重定向跳转，用户在该页面完成认证信息填写和提交。

### 4.3 获取支付结果

#### 4.3.1 支付结果通知

请查看[支付结果-支付结果通知](https://docs.payermax.com/doc-center/acquiring/start-integration/related-capabilities-integration/payment-result.html#_3-1-支付结果通知)。

#### 4.3.2 支付结果查询

请查看[支付结果-支付结果查询](https://docs.payermax.com/doc-center/acquiring/start-integration/related-capabilities-integration/payment-result.html#_3-2-支付结果查询)。

## 5. 支付要素
### 5.1 国际卡（VISA/MASTERCARD/JCB）

| data.paymentDetail | 参数                | 是否必传 | 示例             |
| ------------------ | ------------------- | -------- | ---------------- |
| paymentMethodType  | CARD                | Y        | 固定：CARD       |
|                    | cardIdentifierNo    | Y        | 4444333322221111 |
|                    | cardExpirationMonth | Y        | 12               |
| cardInfo           | cardExpirationYear  | Y        | 25               |
|                    | cvv                 | Y        | 123              |
|                    | cardHolderFullName  | Y        | Jemy Cheung      |

请求示例
``` 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 土耳其（TROY）
| data.paymentDetail | 参数                | 是否必传 | 示例             |
| ------------------ | ------------------- | -------- | ---------------- |
| paymentMethodType  | CARD                | Y        | 固定：CARD       |
|                    | cardIdentifierNo    | Y        | 4444333322221111 |
|                    | cardExpirationMonth | Y        | 12               |
| cardInfo           | cardExpirationYear  | Y        | 25               |
|                    | cvv                 | Y        | 123              |
|                    | cardHolderFullName  | Y        | Jemy             |
| buyerInfo          | phoneNo             | Y        | 16185342424      |
|                    | phoneNoRegion       | Y        | 90               |

请求示例

``` 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"
}
```

### 6.3 巴西（HIPERCACAR/ELO）
| data.paymentDetail | 参数                | 是否必传 | 示例             |
| ------------------ | ------------------- | -------- | ---------------- |
| paymentMethodType  | CARD                | Y        | 固定：CARD       |
|                    | cardIdentifierNo    | Y        | 4444333322221111 |
|                    | cardExpirationMonth | Y        | 12               |
| cardInfo           | cardExpirationYear  | Y        | 25               |
|                    | cvv                 | Y        | 123              |
|                    | cardHolderFullName  | Y        | Jemy             |
|                    | email               | Y        | test@gmail.com   |
|                    | taxType             | Y        | 固定：CPF        |
| buyerInfo          | taxNo               | Y        | 巴西身份证       |
|                    | firstName           | Y        | 用户名           |
|                    | lastName            | Y        | 用户姓           |

请求示例
```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"
}
```