API - CARD

该文档介绍纯API支付集成模式的集成流程。

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

1. 交互流程

%%{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
4.3.1 支付结果异步通知	`PayerMax` -> `商户`	/collectResultNotifyUrl
4.3.2 查询支付交易	`商户` -> `PayerMax`	/orderQuery

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 接口，发起HTTP POST请求，创建支付。

注意：

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

创建支付/orderAndPay API 接口请求示例：

json

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

创建支付/orderAndPay API 接口响应示例：

json

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

为了保障用户支付安全，PayerMax或支付渠道可能会发起额外的用户认证流程，常见的有卡支付的3DS支付、钱包支付的用户登录等。如果触发用户认证，则接口响应中会额外返回redirectUrl且data.status=PENDING，用户可使用redirectUrl重定向跳转到相应页面，用户可在该页面完成认证。

4.2 跳转用户认证

创建支付/orderAndPay API 接口响应redirectUrl表示用户认证页URL，商户接收到响应后，可重定向跳转，用户在该页面完成认证信息填写和提交。

4.3 获取支付结果

4.3.1 通过支付结果通知

请查看支付结果-通过支付结果通知。

4.3.2 通过支付订单查询

请查看支付结果-通过支付订单查询。

5. 支付要素

5.1 国际卡（VISA/MASTERCARD/JCB）

data.paymentDetail	参数	是否必传	示例
paymentMethodType	CARD	Y	固定：CARD
cardInfo	cardIdentifierNo	Y	4444333322221111
	cardExpirationMonth	Y	12
	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.4",
    "merchantNo": "SDP01010114087896"
}

5.2 土耳其（TROY）

data.paymentDetail	参数	是否必传	示例
paymentMethodType	CARD	Y	固定：CARD
cardInfo	cardIdentifierNo	Y	4444333322221111
	cardExpirationMonth	Y	12
	cardExpirationYear	Y	25
	cvv	Y	123
	cardHolderFullName	Y	Jemy
buyerInfo	phoneNo	Y	16185342424
buyerInfo	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.4",
    "merchantNo": "SDP01010114087896"
}

6.3 巴西（HIPERCACAR/ELO）

data.paymentDetail	参数	是否必传	示例
paymentMethodType	CARD	Y	固定：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	固定：CPF
	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.4",
    "merchantNo": "SDP01010114087896"
}

集成模式详细介绍

收单基础产品

CARD

GOOGLEPAY

APPLEPAY

订阅代扣

PayerMax管理订阅计划

商户管理订阅计划

非周期性代扣

前置组件

Tokenization

Auth-Capture

争议

业务风险管控

错误排查

支付方式分类介绍

国家支付方式详情

亚太

中亚

中东及非洲

欧洲

北美拉美

全球

API - CARD ​

1. 交互流程 ​

2. 接口列表 ​

3. 环境信息 ​

4. 集成步骤 ​

4.1 创建支付 ​

4.2 跳转用户认证 ​

4.3 获取支付结果 ​

4.3.1 通过支付结果通知 ​

4.3.2 通过支付订单查询 ​

5. 支付要素 ​

5.1 国际卡（VISA/MASTERCARD/JCB） ​

5.2 土耳其（TROY） ​

6.3 巴西（HIPERCACAR/ELO） ​

API - CARD

1. 交互流程

2. 接口列表

3. 环境信息

4. 集成步骤

4.1 创建支付

4.2 跳转用户认证

4.3 获取支付结果

4.3.1 通过支付结果通知

4.3.2 通过支付订单查询

5. 支付要素

5.1 国际卡（VISA/MASTERCARD/JCB）

5.2 土耳其（TROY）

6.3 巴西（HIPERCACAR/ELO）