ApplePay-非周期性代扣集成

该文档介绍了非周期性代扣集成ApplePay的相关集成步骤，具体包含：绑定支付方式、获取绑定支付方式结果、发起代扣、获取代扣结果等。

1. 前端交互

2. 准备事项

根据配置与签名引导，获取商户自助平台账号、获取商户appId和密钥、配置异步通知地址、配置公钥和私钥。

3. 绑定支付方式

核心参数说明：

totalAmount：交易金额，支持传0或者大于0的金额；
paymentDetail.mitType：代扣类型，SCHEDULED标识为周期性订阅，UNSCHEDULED标识为非周期性代扣；
paymentDetail.tokenForFutureUse：true/false，是否需要生成token用于后续代扣；首次绑定支付方式时，该值传true；
paymentDetail.merchantInitiated：true/false，是否是商户发起的交易；首次绑定支付方式时，需要用户参与完成认证或授权，传值为false；
mitManagementUrl：商户管理代扣产品的地址，用户可通过访问该地址操作订阅计划，如取消代扣等。

3.1 使用PayerMax收银台绑定支付方式

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#e6f0ff',
    'primaryTextColor': '#333',
    'primaryBorderColor': '#5b9bd5',
    'lineColor': '#888',
    'actorMargin': 40,
    'noteBkgColor': '#0056b3',
    'noteTextColor': '#ffffff',
    'noteBorderColor': '#004a99'
  }
}}%%
sequenceDiagram
    participant Client as 商户客户端
    participant MServer as 商户服务端
    participant Checkout as PayerMax 收银台
    participant PMServer as PayerMax 服务端
    participant Apple as Apple

    %% 1. 绑定流程初始化
    Client->>MServer: 1.1 用户选择订阅产品下单
    MServer->>MServer: 1.2 创建订阅计划
    MServer->>PMServer: 1.3 绑定支付方式
调用orderAndPay
    PMServer-->>MServer: 1.4 返回PayerMax收银台地址
    MServer-->>Client: 1.5 返回PayerMax收银台地址

    %% 2. Apple Pay 授权支付
    Client->>Checkout: 2.1 重定向到PayerMax收银台
    Checkout->>Checkout: 2.2 用户选择ApplePay进行支付
    Checkout->>Apple: 2.3 拉起Apple钱包
    Apple->>Apple: 2.4 显示代扣信息
    Apple->>Apple: 2.5 用户确认后，完成人脸/指纹认证
    Apple-->>Checkout: 2.6 返回Apple支付要素
    Checkout->>PMServer: 2.7 发起支付
    PMServer-->>Checkout: 2.8 返回绑定结果
    Checkout-->>Client: 2.9 支付完成后跳转商户收银台结果页

    %% 3. 结果通知
    PMServer->>MServer: 3.1 异步通知商户绑定结果
&paymentTokenID
    MServer-->>PMServer: 3.2 返回是否接受到通知结果

收银台模式绑定支付方式接口文档，请参阅收银台-下单 API。不同环境的请求地址如下。

Prod请求地址：https://pay-gate.payermax.com/aggregate-pay/api/gateway/orderAndPay
Test请求地址：https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/orderAndPay

交易金额大于0元时，请求参数示例:

json

{
  "version": "1.5",
  "keyVersion": "1",
  "requestTime": "2022-01-17T09:05:52.194+00:00",
  "appId": "bbd8d2639a7c4dfd8df7d005294390df",
  "merchantNo": "020113838535952",
  "data": {
    "outTradeNo": "APIFOXDEV1745388079422", // 商户下单唯一单号
    "subject": "代扣标题", // 标题
    "totalAmount": 10, // 代扣金额
    "country": "US",
    "currency": "USD", // 代扣币种
    "userId": "test1111", // 用户号
    "language": "en",
    "reference": "test subscription",
    "frontCallbackUrl": "https://[your domain name]/[your callback URL]",
    "notifyUrl": "https://[your domain name]/[your notify URL]",
    "integrate": "Hosted_Checkout", // 固定值：Hosted_Checkout
    "expireTime": "1800",
    "mitManagementUrl": "https://[your domain name]/[your subscription management URL]", //必填
    "paymentDetail": {
      "paymentMethodType": "APPLEPAY", //必传，值为APPLEPAY
      "mitType": "UNSCHEDULED", // 必传，MIT类型，非周期性代扣时为UNSCHEDULED
      "tokenForFutureUse": true, // 必传，值为true，生成paymentTokenID，用于后续代扣
      "merchantInitiated": false, // 必传，false标识不是商户主动发起，有用户参与；true标识商户主动发起，不需要用户参与
      "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]"
      }
    }
  }
}

交易金额为0时，请求参数示例:

json

{
  "version": "1.5",
  "keyVersion": "1",
  "requestTime": "2022-01-17T09:05:52.194+00:00",
  "appId": "bbd8d2639a7c4dfd8df7d005294390df",
  "merchantNo": "020113838535952",
  "data": {
    "outTradeNo": "APIFOXDEV1745388079422", // 商户下单唯一单号
    "subject": "代扣标题", // 标题
    "totalAmount": 0, // 代扣金额
    "country": "US",
    "currency": "USD", // 代扣币种
    "userId": "test1111", // 用户号
    "language": "en",
    "reference": "test subscription",
    "frontCallbackUrl": "https://[your domain name]/[your callback URL]",
    "notifyUrl": "https://[your domain name]/[your notify URL]",
    "integrate": "Hosted_Checkout", // 固定值：Hosted_Checkout
    "expireTime": "1800",
    "mitManagementUrl": "https://[your domain name]/[your subscription management URL]", //必填
    "paymentDetail": {
      "paymentMethodType": "APPLEPAY", //必传，值为APPLEPAY
      "mitType": "UNSCHEDULED", // 必传，MIT类型，非周期性代扣时为UNSCHEDULED
      "tokenForFutureUse": true, // 必传，值为true，生成paymentTokenID，用于后续代扣
      "merchantInitiated": false, // 必传，false标识不是商户主动发起，有用户参与；true标识商户主动发起，不需要用户参与
      "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]"
      }
    }
  }
}

响应示例:

json

{
    "msg": "Success.",
    "code": "APPLY_SUCCESS",
    "data": {
        // PayerMax 收银台地址
        "redirectUrl": "https://cashier-n-uat.payermax.com/static/processApiV2.html?tradeToken=T2025042306527802000033&integrate=DIRECT_API&country=UN&payRequestNo=20250423060120EP4366527897000250005&merchantId=010213834784554&merchantAppId=6666c8b036a24579974497c2f9a33333&token=902170aeaadb4621af8d9530398d0efa&orderLan=en&countryLan=en&strategyLan=LUBCO&pmaxLinkV=1",
        "outTradeNo": "APIFOXDEV1745388079422",
        "tradeToken": "T2025042306527802000033",
        "status": "PENDING"
    }
}

3.2 API模式绑定支付方式

商户需要在商户的收银台上，从Apple获取支付要素，调用PayerMax绑定支付方式时，需要将支付要素解密后，上送给PayerMax完成绑定。

商户如何自行集成ApplePay请参考：ApplePay-纯API模式集成。

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#e6f0ff',
    'primaryTextColor': '#333',
    'primaryBorderColor': '#5b9bd5',
    'lineColor': '#888',
    'actorMargin': 40,
    'noteBkgColor': '#0056b3',
    'noteTextColor': '#ffffff',
    'noteBorderColor': '#004a99'
  }
}}%%
sequenceDiagram
    participant Client as 商户客户端
    participant Apple as Apple
    participant MServer as 商户服务端
    participant PMServer as PayerMax服务端

    %% 1. 客户端交互与 Apple 认证
    Client->>Client: 1.1 用户进入商户订阅产品页，选购产品
    Client->>Client: 1.2 用户进入商户收银台，选择ApplePay支付
    Client->>Apple: 1.3 用户点击ApplePay
拉起Apple钱包
需要将订阅计划和
订阅管理地址传给Apple
    Apple->>Apple: 1.4 用户确认信息，并选择卡完成认证
    Apple-->>Client: 1.5 Apple返回支付要素

    %% 2. 后端处理与绑定
    Client->>MServer: 2.1 发起支付
带上用户选择的订阅产品信息和Apple支付要素
    MServer->>MServer: 2.2 保存订阅计划
    MServer->>MServer: 2.3 解密Apple支付要素
    MServer->>PMServer: 2.4 绑定支付方式
带上Apple解密后的支付信息
    PMServer-->>MServer: 2.5 返回绑定结果
    MServer-->>Client: 2.6 返回绑定结果
    Client->>Client: 2.7 跳转代扣结果页

    %% 3. 结果通知
    PMServer->>MServer: 3.1 异步通知商户绑定结果
&paymentTokenID
    MServer-->>PMServer: 3.2 商户响应成功接收结果

API模式绑定支付方式API文档，请参阅纯API支付 API。不同环境的请求地址如下：

Prod请求地址：https://pay-gate.payermax.com/aggregate-pay/api/gateway/orderAndPay
Test请求地址：https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/orderAndPay

请求参数示例:

json

{
  "version": "1.5",
  "keyVersion": "1",
  "requestTime": "2022-01-17T09:05:52.194+00:00",
  "appId": "bbd8d2639a7c4dfd8df7d005294390df",
  "merchantNo": "020113838535952",
  "data": {
    "outTradeNo": "APIFOXDEV1745388079422", // 商户下单唯一单号
    "subject": "代扣标题", // 标题
    "totalAmount": 10, // 代扣金额
    "country": "US",
    "currency": "USD", // 代扣币种
    "userId": "test1111", // 用户号
    "language": "en",
    "reference": "test subscription",
    "frontCallbackUrl": "https://[your domain name]/[your callback URL]",
    "notifyUrl": "https://[your domain name]/[your notify URL]",
    "integrate": "Direct_Payment", // 固定值：Direct_Payment
    "expireTime": "1800",
    "terminalType": "WEB", // 终端类型，WEB、WAP or APP
    "osType": "ANDROID", // 操作系统类型 ANDROID or IOS
    "mitManagementUrl": "https://[your domain name]/[your subscription management URL]", //非必填
    "paymentDetail": {
      "paymentMethodType": "APPLEPAY", //必传，值为APPLEPAY
      "mitType": "UNSCHEDULED", // 必传，非周期性代扣时为UNSCHEDULED
      "tokenForFutureUse": true, // 必传，值为true，生成paymentTokenID，用于后续代扣
      "merchantInitiated": false, // false表示是需要用户参数；true表示商户发起的代扣，无需用户参与
      "applePayPaymentData": { // 必传，apple支付要素解密后的参数
        "applicationExpirationDate": "231231",
        "applicationPrimaryAccountNumber": "1234209400123456",
        "currencyCode": "344",
        "deviceManufacturerIdentifier": "040010030273",
        "paymentData": {
            "eciIndicator": "7",
            "onlinePaymentCryptogram": "AqhVFUwAAuM69WEZxe+OMAACAAA="
        },
        "paymentDataType": "3DSecure",
        "transactionAmount": "100",
        "network": "Visa",
        "type": "credit",
        "displayName": "VISA 5743"
      },
      "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]"
      }
    }
  }
}

响应示例:

json

{
    "msg": "Success.",
    "code": "APPLY_SUCCESS",
    "data": {
        "outTradeNo": "APIFOXDEV1745388079422",
        "tradeToken": "T2025042306527802000033",
        "status": "SUCCESS"
    }
}

3.3 使用前置组件绑定支付方式

前置组件绑定支付方式，商户需要通过两个步骤完成集成，具体请参考：集成步骤。

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#e6f0ff',
    'primaryTextColor': '#333',
    'primaryBorderColor': '#5b9bd5',
    'lineColor': '#888',
    'actorMargin': 40,
    'noteBkgColor': '#0056b3',
    'noteTextColor': '#ffffff',
    'noteBorderColor': '#004a99'
  }
}}%%
sequenceDiagram
    participant Client as 商户客户端
    participant MServer as 商户服务端
    participant Checkout as PayerMax收银台
    participant Apple as Apple
    participant PMServer as PayerMax服务端

    %% 1. 初始化阶段
    Client->>Client: 1.1 用户进入商户订阅产品页
    Client->>MServer: 1.2 获取组件信息
    MServer->>PMServer: 1.3 请求applyDropinSession
    PMServer-->>MServer: 1.4 返回clientKey和sessionKey
    MServer-->>Client: 1.5 返回clientKey和sessionKey
    Client->>Client: 1.6 渲染PayerMax组件

    %% 2. 发起支付过程
    rect rgb(235, 245, 255)
    Note over Client, PMServer: 发起支付过程
    Client->>Client: 2.1 用户选择订阅产品，选择ApplePay发起支付
    Client->>MServer: 2.2 保存订阅计划
    MServer-->>Client: 2.3 返回订阅计划信息

    Client->>Checkout: 2.4 调用组件canMakePayment接口，拉起Apple钱包
将订阅信息和mitManagementUrl传入PayerMax组件
    Checkout->>Apple: 2.5 拉起Apple钱包
    Apple->>Apple: 2.6 显示代扣信息
    Apple->>Apple: 2.7 用户选择卡，并完成认证
    Apple-->>Checkout: 2.8 返回Apple支付要素
    Checkout->>Checkout: 2.9 生成paymentToken
    Checkout-->>Client: 2.10 返回paymentToken

    Client->>MServer: 2.11 上送
paymentToken和sessionKey
    MServer->>PMServer: 2.12 调用orderAndPay绑定支付方式
上送paymentToken、sessionKey
    PMServer-->>MServer: 2.13 返回绑定结果
    MServer-->>Client: 2.14 返回绑定结果
    end
    Client->>Client: 2.15 跳转代扣结果页

    %% 3. 通知阶段
    PMServer->>MServer: 3.1 异步通知绑定结果&paymentTokenID
    MServer-->>PMServer: 3.2 商户响应成功接收结果

前置组件绑定支付方式时，商户服务端需要调用PayerMax提供的2个API接口：Apply Drop-in Session API 和前置组件支付 API。Apply Drop-in Session接口不同环境请求地址如下：

Prod请求地址：https://pay-gate.payermax.com/aggregate-pay/api/gateway/applyDropinSession
Test请求地址：https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/applyDropinSession

商户客户端集成示例：

// 获取 clientKey和sessionKey
const data = await post("applyDropinSession", {
    // 告诉服务端是订阅支付？
    ...params
})
// 创建applepay视图
applePay = PMdropin.create('applepay', {
  clientKey: data.clientKey,
  sessionKey: data.sessionKey,
  theme: yourTheme,
  payButtonStyle: data.yourPayButtonStyle,
  sandbox: data.yourFrameEnv
})
// 挂载dom
applePay.mount('.frame-applepay')
// load 加载事件 判断是否成功加载
applePay.on('load', (res = {}) => {
      const { code, msg } = res || {};
      if(code === "SUCCESS"){
        console.log('[merchant][load]success:', res)
      }else{
        console.log('[merchant][load]fail:', res)
      }
})
// 监听点击applepay按钮的事件，用户选择完代扣产品后，点击applepay按钮的时候可以通过这个事件来监听
applePay.on('payButtonClick', (res) => {
    // 禁用applepay按钮点击状态
     applePay.emit('setDisabled', true)
     // 需传入代扣管理地址mitManagementUrl；
     applePay.emit('canMakePayment', { 
        // mitManagementUrl必传
        mitManagementUrl: "http://www.xxx.com"
     })
      .then(res => {
        console.log('canMakePayment', res)
        const paymentToken = res?.data?.paymentToken 
        data.paymentToken = paymentToken// 加密token
        if(paymentToken){
          // 调用PayerMax orderAndPay接口发起支付
          orderAndPay()
        }else{
            // 如果入参不符合格式 这里会抛出错误信息 
            // 错误res示例：{ code: "MIT_PARAMS_VALIDATION_ERROR", message: "xxx  is required" }
          _payLog(JSON.stringify(res))  
          applePay.emit('setDisabled', false)
        }
      })
      .catch(err => {
         // 如果校验不通过 报明确的错。TODO
        console.log('canMakePayment catch', err)
        applePay.emit('payFail')
        applePay.emit('setDisabled', false)
        _payLog(JSON.stringify(err))      
      })
})

Apply Drop-in Session请求入参示例：

json

{
  "version": "1.5",
  "keyVersion": "1",
  "requestTime": "2022-01-17T09:05:52.194+00:00",
  "appId": "3b242b56a8b64274bcc37dac281120e3",
  "merchantNo": "020213827212251",
  "data": {
    "totalAmount": "10", // 代扣金额
    "mitType": "UNSCHEDULED", // 必填，值为SCHEDULED
    "currency": "USD", // 必填
    "country": "SA", // 非必填
    "userId": "U10001", // 必填，用户id
    "componentList": [ // 必填，组件支持的支付方式
      "APPLEPAY"
    ]
  }
}

响应示例:

json

{
  "code": "APPLY_SUCCESS",
  "msg": "Success.",
  "data": {
    "clientKey": "37114858239eur2384237r810482390",
    "sessionKey": "bdsf8982348974hhf82934bf8239424"
  }
}

前置组件支付接口不同环境的请求地址如下：

Prod请求地址：https://pay-gate.payermax.com/aggregate-pay/api/gateway/orderAndPay
Test请求地址：https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/orderAndPay

请求参数示例：

json

{
  "version": "1.5",
  "keyVersion": "1",
  "requestTime": "2022-01-17T09:05:52.194+00:00",
  "appId": "bbd8d2639a7c4dfd8df7d005294390df",
  "merchantNo": "020113838535952",
  "data": {
    "outTradeNo": "APIFOXDEV1745388079422", // 商户下单唯一单号
    "subject": "代扣标题", // 标题
    "totalAmount": 10, // 代扣金额
    "country": "US",
    "currency": "USD", // 代扣币种
    "userId": "test1111", // 用户号
    "language": "en",
    "reference": "test mit",
    "frontCallbackUrl": "https://[your domain name]/[your callback URL]",
    "notifyUrl": "https://[your domain name]/[your notify URL]",
    "integrate": "Direct_Payment", // 固定值：Direct_Payment
    "expireTime": "1800",
    "terminalType": "WEB", // 终端类型，WEB、WAP or APP
    "osType": "ANDROID", // 操作系统类型 ANDROID or IOS
    "mitManagementUrl": "https://[your domain name]/[your subscription management URL]", //非必填
    "paymentDetail": {
      "paymentToken": "CPT4f200d278f3a454b9e91c81edc641e2b", // 必传
      "sessionKey": "bdsf8982348974hhf82934bf8239424", // 必传
      "mitType": "UNSCHEDULED", // 必传，MIT类型，非周期性代扣时为UNSCHEDULED
      "tokenForFutureUse": true, // 必传，值为true，生成paymentTokenID，用于后续代扣
      "merchantInitiated": false, // 必传，false标识不是商户主动发起，有用户参与；true标识商户主动发起，不需要用户参与
      "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]"
      }
    }
  }
}

响应示例:

json

{
  "code": "APPLY_SUCCESS",
  "msg": "",
  "data": {
    "outTradeNo": "P1642410680681",
    "tradeToken": "T2024062702289232000001",
    "status": "SUCCESS"
  }
}

4. 获取绑定支付方式结果

商户可以通过绑定支付方式时上送的notifyUrl地址来接收绑定支付方式结果，详细结果报文请参考：支付结果通知 API。

绑定支付方式成功通知参数示例：

json

{
    "appId": "d68f5da6a0174388821a64114c6b322c",
    "code": "APPLY_SUCCESS",
    "data": {
        "channelNo": "TPC425300174064927201759000685",
        "completeTime": "2025-02-27T09:41:12.267Z",
        "country": "UN",
        "currency": "USD",
        "outTradeNo": "20250227174104451122388",
        "paymentDetails": [
            {
                "applePayInfo": {
                    "cardOrg": "VISA",
                    "cardIdentifierNo": "123456****1234"
                },
                "paymentMethodType": "APPLEPAY",
                "paymentTokenID": "PMTOKEN20250227071843552050007000094"
            }
        ],
        "reference": "reference",
        "status": "SUCCESS",
        "thirdChannelNo": "mtjxuvedrz58345",
        "totalAmount": 10,
        "tradeToken": "T2025022709425329000091"
    },
    "keyVersion": "1",
    "merchantNo": "P01010118267336",
    "msg": "Success.",
    "notifyTime": "2025-02-27T09:41:12 +0000",
    "notifyType": "PAYMENT"
}

绑定支付方式成功后，PayerMax会生成paymentTokenID，后续代扣时需使用该paymentTokenID来进行代扣。

绑定支付方式失败通知参数示例：

json

{
    "appId": "d68f5da6a0174388821a64114c6b322c",
    "code": "PAYMENT_FAILED",
    "data": {
        "channelNo": "TPC462800174064934688659000687",
        "completeTime": "2025-02-27T09:44:00.216Z",
        "country": "UN",
        "currency": "USD",
        "outTradeNo": "20250227174218727122389",
        "paymentDetails": [
            {
                "applePayInfo": {
                    "cardOrg": "VISA",
                    "cardIdentifierNo": "123456****1234"
                },
                "paymentMethodType": "APPLEPAY",
            }
        ],
        "reference": "reference",
        "status": "FAILED",
        "thirdChannelNo": "dycbhzfsmz69480",
        "totalAmount": 10,
        "tradeToken": "T2025022709462829000092"
    },
    "keyVersion": "1",
    "merchantNo": "P01010118267336",
    "msg": "Provider failed to process.",
    "notifyTime": "2025-02-27T09:44:00 +0000",
    "notifyType": "PAYMENT"
}

5. 发起代扣

参数说明：

totalAmount：交易金额必须大于0；
integrate：传固定值Direct_Payment；
paymentDetail.mitType：代扣类型，SCHEDULED为周期性订阅，UNSCHEDULED为非周期性代扣；
paymentDetail.tokenForFutureUse：true/false，是否需要生成token用于后续代扣；后续扣款，传false或不传；
paymentDetail.merchantInitiated：true/false，是否是商户发起的交易；后续扣款，由商户发起，无需用户参与，传值为true；
paymentDetail.paymentTokenID：绑定方式成功后PayerMax返回的Token。

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#e6f0ff',
    'primaryTextColor': '#333',
    'primaryBorderColor': '#5b9bd5',
    'lineColor': '#888',
    'actorMargin': 40,
    'noteBkgColor': '#0056b3',
    'noteTextColor': '#ffffff',
    'noteBorderColor': '#004a99'
  }
}}%%
sequenceDiagram
    participant MServer as 商户服务端
    participant PMServer as PayerMax服务器

    %% 扣款流程
    MServer->>PMServer: 1. 后续扣款:paymentTokenID支付
    PMServer->>PMServer: 2. 完成支付
    PMServer-->>MServer: 3. 同步返回扣款支付结果
    PMServer->>MServer: 4. 异步通知扣款支付结果和
paymentTokenID
    MServer-->>PMServer: 5. 响应消息接口结果

后续代扣API文档，请参阅纯API支付 API。不同环境的请求地址如下：

Prod请求地址：https://pay-gate.payermax.com/aggregate-pay/api/gateway/orderAndPay
Test请求地址：https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/orderAndPay

请求参数示例：

json

{
  "version": "1.5",
  "keyVersion": "1",
  "requestTime": "2022-01-17T09:05:52.194+00:00",
  "appId": "bbd8d2639a7c4dfd8df7d005294390df",
  "merchantNo": "020113838535952",
  "data": {
    "outTradeNo": "APIFOXDEV1745388079422", // 商户下单唯一单号
    "subject": "代扣标题", // 标题
    "totalAmount": 10, // 代扣金额
    "currency": "USD", // 代扣币种
    "country": "SA", // 必传
    "userId": "test1111", // 用户号
    "language": "en",
    "reference": "test subscription",
    "frontCallbackUrl": "http://www.frontCallbackUrl.com",
    "notifyUrl": "http://www.notifyUrl.com",
    "integrate": "Direct_Payment", // 固定值：Direct_Payment
    "expireTime": "1800",
    "terminalType": "WEB", // 终端类型，WEB、WAP or APP
    "osType": "ANDROID", // 操作系统类型 ANDROID or IOS
    "subscriptionPlan": { 
        "deductNo": "xxxx" // 本期扣款唯一单号，同一期多次重试扣款，单号保持一致
    },
    "paymentDetail": {
      "paymentMethodType": "APPLEPAY", //必传，值为APPLEPAY
      "mitType": "UNSCHEDULED", // 必传，MIT类型，非周期性代扣时为UNSCHEDULED
      "tokenForFutureUse": false, // 非必传，值为true，生成paymentTokenID，用于后续代扣
      "merchantInitiated": true, // 必传，false表示是需要用户参数；true表示商户发起的代扣，无需用户参与
      "paymentTokenID": "PMTOKEN20230424072005899168200035002", // 首笔代扣成功后PayerMax返回给商户的Token值
      "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]"
      }
    }
  }
}

商户响应参数示例：

json

{
    "msg": "Success.",
    "code": "APPLY_SUCCESS",
    "data": {
        "outTradeNo": "APIFOXDEV1745388079422",
        "tradeToken": "T2025042306527802000033",
        "status": "SUCCESS"
    }
}

6. 获取代扣结果

无论绑定支付方式还是后续代扣，扣款成功或失败以后，PayerMax会将扣款结果通知给商户，商户也可主动查询代扣结果。

6.1 使用callback获取支付结果

商户可以通过支付时上送的notifyUrl地址来接收支付结果，详细通知报文请参考：支付结果通知 API。

代扣成功通知参数示例：

json

{
    "appId": "d68f5da6a0174388821a64114c6b322c",
    "code": "APPLY_SUCCESS",
    "data": {
        "channelNo": "TPC425300174064927201759000685",
        "completeTime": "2025-02-27T09:41:12.267Z",
        "country": "US",
        "currency": "USD",
        "outTradeNo": "20250227174104451122388",
        "paymentDetails": [
            {
                "applePayInfo": {
                    "cardOrg": "VISA",
                    "cardIdentifierNo": "123456****1234"
                },
                "paymentMethodType": "APPLEPAY",
                "paymentTokenID": "PMTOKEN20250227071843552050007000094"
            }
        ],
        "reference": "reference",
        "status": "SUCCESS",
        "thirdChannelNo": "mtjxuvedrz58345",
        "totalAmount": 10,
        "tradeToken": "T2025022709425329000091"
    },
    "keyVersion": "1",
    "merchantNo": "P01010118267336",
    "msg": "Success.",
    "notifyTime": "2025-02-27T09:41:12 +0000",
    "notifyType": "PAYMENT"
}

代扣失败通知参数示例：

json

{
    "appId": "d68f5da6a0174388821a64114c6b322c",
    "code": "PAYMENT_FAILED",
    "data": {
        "channelNo": "TPC462800174064934688659000687",
        "completeTime": "2025-02-27T09:44:00.216Z",
        "country": "US",
        "currency": "USD",
        "outTradeNo": "20250227174218727122389",
        "paymentDetails": [
            {
                "applePayInfo": {
                    "cardOrg": "VISA",
                    "cardIdentifierNo": "123456****1234"
                },
                "paymentMethodType": "APPLEPAY",
            }
        ],
        "reference": "reference",
        "status": "FAILED",
        "thirdChannelNo": "dycbhzfsmz69480",
        "totalAmount": 10,
        "tradeToken": "T2025022709462829000092"
    },
    "keyVersion": "1",
    "merchantNo": "P01010118267336",
    "msg": "Provider failed to process.",
    "notifyTime": "2025-02-27T09:44:00 +0000",
    "notifyType": "PAYMENT"
}

接收到通知结果以后，需要响应正确的code和message给PayerMax，否则PayerMax会认为商户未能正常接收到通知消息，会重试通知6次。

商户响应参数示例：

json

{
  "msg": "Success",
  "code": "SUCCESS"
}

6.2 使用查询获取支付结果

获取支付结果API文档，请参阅交易查询 API。不同环境的请求地址如下：

Prod请求地址：https://pay-gate.payermax.com/aggregate-pay/api/gateway/orderQuery
Test请求地址：https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/orderQuery

代扣结果查询请求参数示例：

json

{
  "version": "1.5",
  "keyVersion": "1",
  "requestTime": "2022-01-17T07:51:15.597+00:00",
  "appId": "a0dddd1f622243cb9aa1b676e808b5f8",
  "merchantNo": "02021382719993",
  "data": {
    "outTradeNo": "P1642410680681"
  }
}

代扣结果查询响应参数示例：

json

{
  "msg": "Success.",
  "code": "APPLY_SUCCESS",
  "data": {
    "reference": "reference查询和回调返回",
    "country": "SA",
    "totalAmount": 10,
    "outTradeNo": "P1642410680681",
    "currency": "USD",
    "channelNo": "DMCP000000000177005",
    "thirdChannelNo": "4ikqJ6ktEqyRawE1dvqb9c",
    "paymentCode": "2312121212",
    "tradeToken": "T2024062702289232000001",
    "completeTime": "2023-10-20T03:28:23.092Z",
    "paymentDetails": [
      {
        "targetOrg": "*",
        "applePayInfo": {
            "cardOrg": "VISA",
            "cardIdentifierNo": "123456****1234"
        },
        "paymentMethodType": "APPLEPAY",
        "paymentTokenID": "PMTOKEN20250224063712195626335000250",
        "payAmount": 10,
        "exchangeRate": "1",
        "payCurrency": "USD"
      }
    ],
    "status": "SUCCESS",
    "resultMsg": ""
  }
}

7. 解绑支付方式

用户取消代扣后，商户需要为用户解绑该支付方式，解绑支付方式API文档，请参考PaymentTokenID解绑 API。不同环境的请求地址如下：

Prod请求地址：https://pay-gate.payermax.com/aggregate-pay/api/gateway/removePaymentToken
Test请求地址：https://pay-gate-uat.payermax.com/aggregate-pay/api/gateway/removePaymentToken

请求参数示例：

json

{
  "version": "1.5",
  "keyVersion": "1",
  "requestTime": "2022-01-22T10:00:00.500+08:00",
  "appId": "46153e2b787241ae8b01857bb087d1bd",
  "merchantNo": "010229810189301",
  "data": {
    "userId": "TEST",
    "paymentTokenID": "PMTOKEN20230424072005899168200035002",
    "removeReason": "remove"
  }
}

响应参数示例：

json

{
  "code": "APPLY_SUCCESS",
  "msg": "Success",
  "data": {
    "paymentTokenID": "PMTOKEN20230424072005899168200035002",
    "userId": "Test",
    "paymentTokenStatus": "Deleted"
  }
}

集成模式详细介绍

收单基础产品

CARD

GOOGLEPAY

APPLEPAY

订阅代扣

PayerMax管理订阅计划

商户管理订阅计划

非周期性代扣

前置组件

Tokenization

Auth-Capture

争议

业务风险管控

错误排查

支付方式分类介绍

国家支付方式详情

亚太

中亚

中东及非洲

欧洲

北美拉美

全球

ApplePay-非周期性代扣集成 ​

1. 前端交互 ​

2. 准备事项 ​

3. 绑定支付方式 ​

3.1 使用PayerMax收银台绑定支付方式 ​

3.2 API模式绑定支付方式 ​

3.3 使用前置组件绑定支付方式 ​

4. 获取绑定支付方式结果 ​

5. 发起代扣 ​

6. 获取代扣结果 ​

6.1 使用callback获取支付结果 ​

6.2 使用查询获取支付结果 ​

7. 解绑支付方式 ​

ApplePay-非周期性代扣集成

1. 前端交互

2. 准备事项

3. 绑定支付方式

3.1 使用PayerMax收银台绑定支付方式

3.2 API模式绑定支付方式

3.3 使用前置组件绑定支付方式

4. 获取绑定支付方式结果

5. 发起代扣

6. 获取代扣结果

6.1 使用callback获取支付结果

6.2 使用查询获取支付结果

7. 解绑支付方式