APM-周期性订阅集成

该文档介绍了周期性订阅集成APM支付方式的相关集成步骤，具体包含：创建订阅计划、激活订阅计划以及接收订阅扣款结果等。

1. 准备事项

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

2. 交互流程

3. 订阅计划规则

PayerMax提供多种类型的订阅计划：普通订阅、n天试用订阅、前n期优惠订阅；创建订阅计划时，可以通过传入不同的参数来创建不同类型的订阅计划。
PayerMax管理的订阅计划，总时长不能超过3年。
创建订阅计划后，需在首期扣款开始时间之前完成激活，若首期扣款时间与订阅创建时间相差大于24小时，则需要在24小时内完成激活，否则订阅计划会被置为已过期，过期后PayerMax会通知该订阅计划已过期。
激活订阅计划后，后续的扣款由PayerMax发起；后续每期扣款，会在该期开始前24小时内进行扣款，如果扣款失败，24小时内系统会自动重试，若重试5次不成功，则订阅扣款失败，订阅计划终止。

订阅计划状态说明

状态值	状态说明	备注
INACTIVE	未激活	创建订阅计划后，状态为未激活
ACTIVE_FAILED	激活失败	激活失败后的状态
ACTIVE	生效中	激活成功后的状态
TERMINATE	订阅终止	某期扣款失败后，订阅计划会终止
CANCEL	订阅取消	主动取消订阅计划
FINISH	订阅完成	订阅计划所有期数都完成扣款
EXPIRED	过期未激活	首期扣款时间开始后，还未激活订阅计划

订阅扣款状态说明

状态值	状态说明
PENDING	扣款中
SUCCESS	扣款成功
FAILED	扣款失败

4. 创建订阅计划

以下是几种订阅计划类型的API创建请求响应示例，有关完整的API规范，请参阅创建订阅计划 API。创建订阅计划不同环境的请求地址如下：

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

4.1 普通订阅计划

首期扣款开始时间（firstPeriodStartDate）在请求时间（requestTime）后24小时内，且无优惠配置（trialPeriodConfig）；创建普通订阅计划入参如下：

json

{
    "version": "1.5",
    "keyVersion": "1",
    "requestTime": "2025-02-26T05:00:00+00:00",
    "appId": "6666c8b036a24579974497c2f9a33333",
    "merchantNo": "010213834784554",
    "data": {
        "subscriptionRequestId": "subscription100000000000001", // 必填、商户创建订阅计划的单号
        "userId": "test10001", // 必填、用户id
        "language": "en", // 非必填、 语言
        "callbackUrl": "http://***.com/notifyUrl/subscription",  // 必填、订阅结果和扣款结果的通知地址
        "subscriptionPlan": { // 必填、 订阅计划信息
            "subject": "subject", // 必填、标题
            "description": "PMMAX周期首期扣款", // 非必填、描述
            "totalPeriods": 24, //必填、总期数
            "periodRule": { // 必填、扣款规则
                "periodUnit": "M", // 必填、按月（M），D(日)，W（周），Y（年）扣款
                "periodCount": 2 // 必填、2个月扣款一次
            },
             // 每期扣款金额
            "periodAmount": { //必填
                "amount": 10.0, // 必填
                "currency": "USD" // 必填
            },
            "firstPeriodStartDate": "2025-02-26T12:00:00+00:00" //必填、第一期扣款开始时间传当天，firstPeriodStartDate - requestTime < 24小时
        }
    }
}

4.2 n天试用

首期扣款开始时间（firstPeriodStartDate）在请求时间（requestTime）后，且两个时间相差n天，同时无优惠配置（trialPeriodConfig）。以下订阅计划入参示例为试用2天的场景，firstPeriodStartDate和requestTime相差2天；创建2天试用订阅计划入参如下：

json

{
    "version": "1.5",
    "keyVersion": "1",
    "requestTime": "2025-02-26T05:00:00+00:00",
    "appId": "6666c8b036a24579974497c2f9a33333",
    "merchantNo": "010213834784554",
    "data": {
        "subscriptionRequestId": "subscription100000000000001", // 必填、商户创建订阅计划的单号
        "userId": "test10001", // 必填、用户id
        "language": "en", // 非必填、 语言
        "callbackUrl": "http://***.com/notifyUrl/subscription",  // 必填、订阅结果和扣款结果的通知地址
        "subscriptionPlan": { // 必填、 订阅计划信息
            "subject": "subject", // 必填、标题
            "description": "PMMAX周期首期扣款", // 非必填、描述
            "totalPeriods": 24, //必填、总期数
            "periodRule": { // 必填、扣款规则
                "periodUnit": "M", // 必填、按月（M），D(日)，W（周），Y（年）扣款
                "periodCount": 2 // 必填、2个月扣款一次
            },
             // 每期扣款金额
            "periodAmount": { //必填
                "amount": 10.0, // 必填、订阅金额
                "currency": "USD" // 必填、订阅币种
            },
            "firstPeriodStartDate": "2025-02-28T05:00:00+00:00" //必填、第一期扣款开始时间传当天，firstPeriodStartDate - requestTime > 24小时
        }
    }
}

4.3 前n期优惠

首期扣款开始时间（firstPeriodStartDate）在请求时间（requestTime）后24小时内，包含优惠配置信息（trialPeriodConfig）。以下订阅计划入参示例为前2期优惠的场景，优惠期扣款金额为3USD，从第3期开始，扣款金额为10USD；前2期优惠入参如下：

json

{
    "version": "1.5",
    "keyVersion": "1",
    "requestTime": "2025-02-26T05:00:00+00:00",
    "appId": "6666c8b036a24579974497c2f9a33333",
    "merchantNo": "010213834784554",
    "data": {
        "subscriptionRequestId": "subscription100000000000001", // 必填、商户创建订阅计划的单号
        "userId": "test10001", // 必填、用户id
        "language": "en", // 非必填、 语言
        "callbackUrl": "http://***.com/notifyUrl/subscription",  // 必填、订阅结果和扣款结果的通知地址
        "subscriptionPlan": { // 必填、 订阅计划信息
            "subject": "subject", // 必填、标题
            "description": "PMMAX周期首期扣款", // 非必填、描述
            "totalPeriods": 24, //必填、总期数
            "periodRule": { // 必填、扣款规则
                "periodUnit": "M", // 必填、按月（M），D(日)，W（周），Y（年）扣款
                "periodCount": 2 // 必填、2个月扣款一次
            },
             // 非优惠期扣款金额
            "periodAmount": { //必填
                "amount": 10.0, // 必填、订阅金额
                "currency": "USD" // 必填、订阅币种
            },
            "firstPeriodStartDate": "2025-02-26T12:00:00+00:00", //必填、第一期扣款开始时间传当天，firstPeriodStartDate - requestTime < 24小时
            "trialPeriodConfig": { // 非必填、优惠期配置
                "trialPeriodCount": 2, //优惠期数
                "trialPeriodAmount": { // 优惠期扣款金额
                    "amount": 3.0, // 优惠期扣款金额，金额为0标识优惠期免费
                    "currency": "USD" // 优惠期扣款币种
                }
            }
        }
    }
}

创建订阅计划响应参数示例：

json

{
  "msg": "Success.",
  "code": "APPLY_SUCCESS",
  "data": {
    "subscriptionRequestId": "subscription100000000000001", //创建订阅计划时商户上送的请求单号
    "subscriptionPlan": {
        "subscriptionNo": "SUB20250202620949065212112", // PayerMax生成的订阅单号
        "subscriptionStatus": "INACTIVE", //未激活
    }
  }
}

5. 激活订阅计划

创建订阅计划后，此时订阅计划处于未激活状态，需用户完成一笔支付或授权来激活订阅计划，订阅计划才能生效。PayerMax提供了收银台模式、API模式和前置组件模式3种集成模式来完成首笔支付或授权。

激活请求参数说明：

如果订阅计划类型是n天试用，则激活时totalAmount的值为0；如果订阅计划类型是前n期优惠，则激活时totalAmount的值为优惠期设置的金额；如果订阅计划类型是普通订阅，则激活时totalAmount的值固定期的金额；
激活时的currency必须和订阅计划中的币种保持一致；
激活时的userId必须和订阅计划中的userId保持一致；
激活时必须上送创建订阅计划后PayerMax返回的订阅单号subscriptionNo；
激活时subject的值须与订阅计划中的subject保持一致；

5.1 收银台模式激活订阅计划

注意：

收银台模式激活订阅计划时，支持全量收银台模式、指定支付方式、指定支付方式+目标机构。

收银台模式激活订阅计划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": "订阅计划的标题", // 保持和订阅计划的subject一致
    "totalAmount": 10, // 保持和订阅金额一致：【n天试用】时金额为0；【前n期优惠】时金额为优惠期金额；【普通订阅】时金额为每期扣款金额
    "currency": "USD", // 保持和订阅币种一致
    "userId": "test1111", // 保持和订阅计划的用户号一致
    "language": "en",
    "reference": "test subscription",
    "frontCallbackUrl": "http://www.frontCallbackUrl.com",
    "notifyUrl": "http://www.notifyUrl.com",
    "integrate": "Hosted_Checkout", // 激活时为固定值：Hosted_Checkout
    "expireTime": "1800",
    "subscriptionPlan": { // 订阅信息
        "subscriptionNo": "SUB25022603353890000002003" //需要激活的订阅单号
    },
    "paymentDetail": {
      "mitType": "SCHEDULED", // 必传，MIT类型，周期性代扣时为SCHEDULED，非周期性代扣时为UNSCHEDULED
      "tokenForFutureUse": true, // 必传，值为true，生成paymentTokenID，用于后续代扣
      "merchantInitiated": false // 必传，false标识不是商户主动发起，有用户参与；true标识商户主动发起，不需要用户参与
    }
  }
}

指定支付方式激活订阅计划请求参数示例：

json

{
  "version": "1.5",
  "keyVersion": "1",
  "requestTime": "2022-01-17T09:05:52.194+00:00",
  "appId": "bbd8d2639a7c4dfd8df7d005294390df",
  "merchantNo": "020113838535952",
  "data": {
    "outTradeNo": "APIFOXDEV1745388079422", // 商户下单唯一单号
    "subject": "订阅计划的标题", // 保持和订阅计划的subject一致
    "totalAmount": 10, // 保持和订阅金额一致：【n天试用】时金额为0；【前n期优惠】时金额为优惠期金额；【普通订阅】时金额为每期扣款金额
    "currency": "USD", // 保持和订阅币种一致
    "country": "KR", // 必传
    "userId": "test1111", // 保持和订阅计划的用户号一致
    "language": "en",
    "reference": "test subscription",
    "frontCallbackUrl": "http://www.frontCallbackUrl.com",
    "notifyUrl": "http://www.notifyUrl.com",
    "integrate": "Hosted_Checkout", // 激活时为固定值：Hosted_Checkout
    "expireTime": "1800",
    "subscriptionPlan": { // 订阅信息
        "subscriptionNo": "SUB25022603353890000002003" //需要激活的订阅单号
    },
    "paymentDetail": {
      "paymentMethodType": "WALLET",
      "mitType": "SCHEDULED", // 必传，MIT类型，周期性代扣时为SCHEDULED，非周期性代扣时为UNSCHEDULED
      "tokenForFutureUse": true, // 必传，值为true，生成paymentTokenID，用于后续代扣
      "merchantInitiated": false // 必传，false标识不是商户主动发起，有用户参与；true标识商户主动发起，不需要用户参与
    }
  }
}

指定支付方式+目标机构（钱包）激活订阅计划请求参数示例：

json

{
  "version": "1.5",
  "keyVersion": "1",
  "requestTime": "2022-01-17T09:05:52.194+00:00",
  "appId": "bbd8d2639a7c4dfd8df7d005294390df",
  "merchantNo": "020113838535952",
  "data": {
    "outTradeNo": "APIFOXDEV1745388079422", // 商户下单唯一单号
    "subject": "订阅计划的标题", // 保持和订阅计划的subject一致
    "totalAmount": 10, // 保持和订阅金额一致：【n天试用】时金额为0；【前n期优惠】时金额为优惠期金额；【普通订阅】时金额为每期扣款金额
    "currency": "USD", // 保持和订阅币种一致
    "country": "KR", // 必传
    "userId": "test1111", // 保持和订阅计划的用户号一致
    "language": "en",
    "reference": "test subscription",
    "frontCallbackUrl": "http://www.frontCallbackUrl.com",
    "notifyUrl": "http://www.notifyUrl.com",
    "integrate": "Hosted_Checkout", // 激活时为固定值：Hosted_Checkout
    "expireTime": "1800",
    "subscriptionPlan": { // 订阅信息
        "subscriptionNo": "SUB25022603353890000002003" //需要激活的订阅单号
    },
    "paymentDetail": {
      "paymentMethodType": "WALLET",
      "targetOrg": "NAVERPAY",
      "mitType": "SCHEDULED", // 必传，MIT类型，周期性代扣时为SCHEDULED，非周期性代扣时为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"
    }
}

5.2 API模式激活订阅计划

注意：

API模式激活订阅计划，可以指定卡支付方式，也可指定钱包支付方式进行激活。

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

API模式指定钱包激活订阅计划请求参数示例:

json

{
  "version": "1.5",
  "keyVersion": "1",
  "requestTime": "2022-01-17T09:05:52.194+00:00",
  "appId": "bbd8d2639a7c4dfd8df7d005294390df",
  "merchantNo": "020113838535952",
  "data": {
    "outTradeNo": "APIFOXDEV1745388079422", // 商户下单唯一单号
    "subject": "订阅计划的标题", // 保持和订阅计划的subject一致
    "totalAmount": 10, // 保持和订阅金额一致：【n天试用】时金额为0；【前n期优惠】时金额为优惠期金额；【普通订阅】时金额为每期扣款金额
    "currency": "USD", // 保持和订阅币种一致
    "country": "KR", // 必传
    "userId": "test1111", // 保持和订阅计划的用户号一致
    "language": "en",
    "reference": "test subscription",
    "frontCallbackUrl": "http://www.frontCallbackUrl.com",
    "notifyUrl": "http://www.notifyUrl.com",
    "integrate": "Direct_Payment", // 激活时为固定值：Direct_Payment
    "expireTime": "1800",
    "subscriptionPlan": { // 订阅信息
        "subscriptionNo": "SUB25022603353890000002003" //需要激活的订阅单号
    },
    "terminalType": "WEB", // 终端类型，WEB、WAP or APP
    "osType": "ANDROID", // 操作系统类型 ANDROID or IOS
    "paymentDetail": {
      "paymentMethodType": "WALLET", //必传 支付方式
      "targetOrg": "NAVERPAY", // 必传 ，目标机构
      "mitType": "SCHEDULED", // 必传，MIT类型，周期性订阅时为SCHEDULED，非周期性代扣时为UNSCHEDULED
      "tokenForFutureUse": true, // 必传，值为true，生成paymentTokenID，用于后续代扣
      "merchantInitiated": false // false表示是需要用户参数；true表示商户发起的代扣，无需用户参与
    }
  }
}

API模式激活订阅计划响应示例:

json

{
    "msg": "Success.",
    "code": "APPLY_SUCCESS",
    "data": {
        // 跳转地址
        "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"
    }
}

5.3 前置组件模式激活订阅计划

注意：

前置组件模式不支持钱包支付方式，只支持卡支付方式激活订阅计划。

前置组件集成请参考：集成步骤。

前置组件模式激活订阅计划时，商户服务端需要调用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

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", // 保持和订阅金额一致：【n天试用】和【n天试用+前n期优惠】时金额为0；【前n期优惠】时金额为优惠期金额；【普通订阅】时金额为每期扣款金额；也可以不填
    "mitType": "SCHEDULED", // 必填，PayerMax管理订阅计划时，值为SCHEDULED
    "currency": "USD", // 必填
    "country": "SA", // 非必填
    "userId": "U10001", // 必填，用户id
    "componentList": [ // 必填，组件支持的支付方式
      "CARD"
    ]
  }
}

响应示例:

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": "P1642410680681", // 商户下单唯一单号
    "subject": "订阅计划的标题", // 保持和订阅计划的subject一致
    "totalAmount": 10, // 保持和订阅金额一致：【n天试用】和【n天试用+前n期优惠】时金额为0；【前n期优惠】时金额为优惠期金额；【普通订阅】时金额为每期扣款金额
    "currency": "USD", // 保持和订阅币种一致
    "userId": "test1111", // 保持和订阅计划的用户号一致
    "language": "en",
    "reference": "test subscription",
    "frontCallbackUrl": "http://www.frontCallbackUrl.com",
    "notifyUrl": "http://www.notifyUrl.com",
    "integrate": "Direct_Payment", // 激活时为固定值：Direct_Payment
    "expireTime": "1800",
    "subscriptionPlan": { // 订阅信息
        "subscriptionNo": "SUB25022603353890000002003" //需要激活的订阅单号
    },
    "terminalType": "WEB", // 终端类型，WEB、WAP or APP
    "osType": "ANDROID", // 操作系统类型 ANDROID or IOS
    "paymentDetail": {
      "paymentToken": "CPT4f200d278f3a454b9e91c81edc641e2b", //激活时必传
      "sessionKey": "bdsf8982348974hhf82934bf8239424", //激活时必传
      "mitType": "SCHEDULED", // 必传，MIT类型，周期性代扣时为SCHEDULED，非周期性代扣时为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": {
      //3ds验证地址
    "redirectUrl": "https://cashier-n-uat.payermax.com/index.html#/cashier/home?merchantId=020213827212251&merchantAppId=3b242b56a8b64274bcc37dac281120e3&country=ID&tradeToken=TOKEN20220117091121294138752&language=en&token=IHjqkZ8%2F%2FFcnfDPxWTvJFOrulUAKfXFUkxHJSiTdlnjnX1G6AOuTiSl6%2BN05EzxTaJkcSsSyGh5a1q%2FACwWN0sDD%2FgwY5YdWu3ghDcH2wqm%2BJIcEh0qZqo%2BQFnXp65bvkLZnY7VO7HwZGzyrpMBlPhfRCQxwBbc6lJcSYuPf%2Fe8%3D&amount=10000¤cy=IDR&frontCallbackUrl=https%3A%2F%2Fwww.payermax.com",
    "outTradeNo": "P1642410680681",
    "tradeToken": "T2024062702289232000001",
    "status": "PENDING"
  }
}

6. 获取订阅计划激活结果

商户可以通过创建订阅计划时上送的callbackUrl地址来接收订阅计划状态变更通知和订阅扣款结果。

6.1 获取订阅计划状态变更结果

订阅计划状态变更通知详细通知报文请参考：订阅状态变更通知 API。

订阅激活成功通知参数示例：

json

{
    "keyVersion": "1",
    "merchantNo": "P01000116980333",
    "msg": "Success.",
    "notifyTime": "2023-04-24T09:44:40.761Z",
    "notifyType": "SUBSCRIPTION"
    "appId": "6c556bcd56c84652176b3c5abc389296",
    "code": "APPLY_SUCCESS",
    "data": {
        "subscriptionRequestId": "requestMWRkgX5iHaTmf45ePdEP",
        "userId": "10003",
        "subscriptionPlan": {
            "subscriptionNo": "SUB20221212174716894496912",
            "subscriptionStatus": "ACTIVE" // 激活成功
        }
    }
}

订阅激活失败通知参数示例：

json

{
    "keyVersion": "1",
    "merchantNo": "P01000116980333",
    "msg": "Success.",
    "notifyTime": "2023-04-24T09:44:40.761Z",
    "notifyType": "SUBSCRIPTION"
    "appId": "6c556bcd56c84652176b3c5abc389296",
    "code": "APPLY_SUCCESS",
    "data": {
        "subscriptionRequestId": "requestMWRkgX5iHaTmf45ePdEP",
        "userId": "10003",
        "subscriptionPlan": {
            "subscriptionNo": "SUB20221212174716894496912",
            "subscriptionStatus": "ACTIVE_FAILED" // 激活失败
        }
    }
}

商户响应参数示例：

json

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

6.2 获取订阅扣款结果

若创建的订阅计划是普通订阅或前n期优惠，订阅计划激活的同时也会进行首期扣款，扣款完成后，PayerMax会通知商户扣款结果；订阅扣款结果通知报文请参考：扣款结果通知 API。

钱包支付方式扣款成功通知参数示例：

json

{
    "keyVersion": "1",
    "merchantNo": "P01000116980333",
    "msg": "Success.",
    "notifyTime": "2023-04-24T09:44:40.761Z",
    "notifyType": "SUBSCRIPTION_PAYMENT"
    "appId": "6c556bcd56c84652176b3c5abc389296",
    "code": "APPLY_SUCCESS",
    "data": {
        "subscriptionRequestId": "requestMWRkgX5iHaTmf45ePdEP",
        "merchantNo": "P01010113865434",
        "userId": "10003",
        "subscriptionPlan": {
            "subscriptionNo": "SUB20221212174716894496912"
        },
        "subscriptionPaymentDetail": {
            "subscriptionIndex": 1, // 扣款期数
            "paymentStatus": "SUCCESS", //本期订单状态
            "periodStartTime": "2025-10-13T15:59:59+0000", // 本期开始时间
            "periodEndTime": "2025-12-13T15:59:59+0000", // 本期结束时间
            "payAmount": { // 扣款金额
                "amount": "10",
                "currency": "USD"
            },
            "paymentMethodType": "WALLET",
            "targetOrg": "NAVERPAY",
            "lastPaymentInfo": { 
                "tradeToken": "T20221212174800970116912", //支付单号 tradeToken可用于发起退款
                "lastPaymentStatus": "SUCCESS", // 最新扣款结果
                "payTime": "2025-02-13T15:59:59+0000" // 支付时间
            }
        }
    }
}

钱包支付方式扣款失败通知参数示例：

json

{
    "keyVersion": "1",
    "merchantNo": "P01000116980333",
    "msg": "Success.",
    "notifyTime": "2023-04-24T09:44:40.761Z",
    "notifyType": "SUBSCRIPTION_PAYMENT"
    "appId": "6c556bcd56c84652176b3c5abc389296",
    "code": "APPLY_SUCCESS",
    "data": {
        "subscriptionRequestId": "requestMWRkgX5iHaTmf45ePdEP",
        "merchantNo": "P01010113865434",
        "userId": "10003",
        "subscriptionPlan": {
            "subscriptionNo": "SUB20221212174716894496912"
        },
        "subscriptionPaymentDetail": {
            "subscriptionIndex": 1, // 扣款期数
            "paymentStatus": "FAILED", //本期订单状态
            "periodStartTime": "2022-10-13T15:59:59+0000", // 本期开始时间
            "periodEndTime": "2022-12-13T15:59:59+0000", // 本期结束时间
            "payAmount": { // 支付金额
                "amount": "10",
                "currency": "USD"
            },
            "paymentMethodType": "WALLET",
            "targetOrg": "NAVERPAY",
            "lastPaymentInfo": { 
                "tradeToken": "T20221212174800970116912", //支付单号 tradeToken 可用于退款
                "lastPaymentStatus": "FAILED", // 最新扣款结果
                "payTime": "2022-12-13T15:59:59+0000", // 支付时间
                "errorCode": "xxxx", // 扣款失败code
                "errorMsg": "xxxx", // 扣款失败原因
            }
        }
    }
}

商户响应参数示例：

json

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

6.3 获取订阅激活请求结果

商户可以通过激活订阅计划时上送的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": [
            {
                "paymentMethodType": "WALLET",
                "targetOrg": "NAVERPAY",
                "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": "UN",
        "currency": "USD",
        "outTradeNo": "20250227174218727122389",
        "paymentDetails": [
            {
                "paymentMethodType": "WALLET",
                "targetOrg": "NAVERPAY"
            }
        ],
        "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"
}

商户响应参数示例：

json

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

7. PayerMax后续扣款

订阅计划激活后，PayerMax会按照订阅周期，在每期开始前24小时开始扣款，每期扣款完成后，PayerMax会通知商户本期扣款结果；每期扣款，PayerMax会尝试扣款5次，如果全部失败，PayerMax会将该订阅计划终止，并通知商户；商户可以通过创建订阅计划时上送的callbackUrl地址来接收扣款结果。

钱包支付方式扣款成功通知参数示例：

json

{
    "keyVersion": "1",
    "merchantNo": "P01000116980333",
    "msg": "Success.",
    "notifyTime": "2023-04-24T09:44:40.761Z",
    "notifyType": "SUBSCRIPTION_PAYMENT"
    "appId": "6c556bcd56c84652176b3c5abc389296",
    "code": "APPLY_SUCCESS",
    "data": {
        "subscriptionRequestId": "requestMWRkgX5iHaTmf45ePdEP",
        "merchantNo": "P01010113865434",
        "userId": "10003",
        "subscriptionPlan": {
            "subscriptionNo": "SUB20221212174716894496912"
        },
        "subscriptionPaymentDetail": {
            "subscriptionIndex": 1, // 扣款期数
            "paymentStatus": "SUCCESS", //本期订单状态
            "periodStartTime": "2025-10-13T15:59:59+0000", // 本期开始时间
            "periodEndTime": "2025-12-13T15:59:59+0000", // 本期结束时间
            "payAmount": { // 扣款金额
                "amount": "10",
                "currency": "USD"
            },
            "paymentMethodType": "WALLET",
            "targetOrg": "NAVERPAY",
            "lastPaymentInfo": { 
                "tradeToken": "T20221212174800970116912", //支付单号 tradeToken可用于发起退款
                "lastPaymentStatus": "SUCCESS", // 最新扣款结果
                "payTime": "2025-02-13T15:59:59+0000" // 支付时间
            }
        }
    }
}

钱包支付方式扣款失败通知参数示例：

json

{
    "keyVersion": "1",
    "merchantNo": "P01000116980333",
    "msg": "Success.",
    "notifyTime": "2023-04-24T09:44:40.761Z",
    "notifyType": "SUBSCRIPTION_PAYMENT"
    "appId": "6c556bcd56c84652176b3c5abc389296",
    "code": "APPLY_SUCCESS",
    "data": {
        "subscriptionRequestId": "requestMWRkgX5iHaTmf45ePdEP",
        "merchantNo": "P01010113865434",
        "userId": "10003",
        "subscriptionPlan": {
            "subscriptionNo": "SUB20221212174716894496912"
        },
        "subscriptionPaymentDetail": {
            "subscriptionIndex": 1, // 扣款期数
            "paymentStatus": "FAILED", //本期订单状态
            "periodStartTime": "2022-10-13T15:59:59+0000", // 本期开始时间
            "periodEndTime": "2022-12-13T15:59:59+0000", // 本期结束时间
            "payAmount": { // 支付金额
                "amount": "10",
                "currency": "USD"
            },
            "paymentMethodType": "WALLET",
            "targetOrg": "NAVERPAY",
            "lastPaymentInfo": { 
                "tradeToken": "T20221212174800970116912", //支付单号 tradeToken 可用于退款
                "lastPaymentStatus": "FAILED", // 最新扣款结果
                "payTime": "2022-12-13T15:59:59+0000", // 支付时间
                "errorCode": "xxxx", // 扣款失败code
                "errorMsg": "xxxx", // 扣款失败原因
            }
        }
    }
}

8. 管理订阅计划

订阅计划激活后，可进行订阅计划的管理，如查询订阅扣款结果、取消订阅计划等，订阅计划状态变更后，PayerMax会通知商户订阅计划状态。

8.1 订阅状态变更通知

商户可以通过创建订阅计划时上送的callbackUrl地址来接收订阅计划状态变更结果，详细通知报文请参考：订阅状态变更通知 API。

订阅计划终止通知参数示例：

json

{
    "keyVersion": "1",
    "merchantNo": "P01000116980333",
    "msg": "Success.",
    "notifyTime": "2023-04-24T09:44:40.761Z",
    "notifyType": "SUBSCRIPTION"
    "appId": "6c556bcd56c84652176b3c5abc389296",
    "code": "APPLY_SUCCESS",
    "data": {
        "subscriptionRequestId": "requestMWRkgX5iHaTmf45ePdEP",
        "userId": "10003",
        "subscriptionPlan": {
            "subscriptionNo": "SUB20221212174716894496912",
            "subscriptionStatus": "TERMINATE"
        }
    }
}

8.2 取消订阅计划

商户可取消订阅计划，如果正处于最新一期处于扣款中，须等该期扣款成功或扣款失败后，才能取消订阅计划；详细API报文请参考：取消订阅计划 API。不同环境的请求地址如下：

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

取消订阅计划请求参数示例：

json

{
  "version": "1.5", // 版本为1.5
  "keyVersion": "1",
  "requestTime": "2023-02-13T06:32:50.455+00:00",
  "appId": "82ff47ea6c724a60b666e3ac0ea172dd",
  "merchantNo": "P01010113865434",
  "data": {
    "subscriptionNo": "SUB20221212174716894496912" // PayerMax订阅单号
  }
}

取消订阅计划响应参数示例：

json

{
  "msg": "Success.",
  "code": "APPLY_SUCCESS",
  "data": {
    "subscriptionRequestId": "requestMWRkgX5iHaTmf45ePdEP",
    "userId": "10003",
    "subscriptionPlan": {
        "subscriptionNo": "SUB20221212174716894496912",
        "subscriptionStatus": "CANCEL" // 已取消
    }
  }
}

8.3 查询订阅扣款结果

查询订阅扣款结果API文档，请参考：订阅扣款结果查询 API。不同环境的请求地址如下：

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

查询订阅计划请求参数示例：

json

{
  "version": "1.5",
  "keyVersion": "1",
  "requestTime": "2023-02-13T06:32:50.455+00:00",
  "appId": "82ff47ea6c724a60b666e3ac0ea172dd",
  "merchantNo": "P01010113865434",
  "data": {
    "subscriptionRequestId": "requestMWRkgX5iHaTmf45ePdEP", //subscriptionNo和requestId必须传一个
    "subscriptionNo": "SUB20221212174716894496912" //subscriptionNo和requestId必须传一个
  }
}

查询订阅计划响应参数示例：

json

{
    "msg": "Success.",
    "code": "APPLY_SUCCESS",
    "data": {
        "subscriptionRequestId": "requestMWRkgX5iHaTmf45ePdEP",
        "merchantNo": "P01010113865434",
        "userId": "10003",
        "subscriptionPlan": {
            "subscriptionNo": "SUB20221212174716894496912",
            "subscriptionStatus": "ACTIVE" // 订阅状态、
        },
        "subscriptionPaymentDetails": [
            {
                "subscriptionIndex": 0, // 扣款期数：第一期
                "paymentStatus": "SUCCESS", //本期订单状态
                "periodStartTime": "2025-01-13T15:59:59+0000", // 本期开始时间
                "periodEndTime": "2025-02-13T15:59:59+0000", // 本期结束时间
                "payAmount": { // 支付金额
                    "amount": "100",
                    "currency": "SAR"
                },
                "paymentMethodType": "WALLET",
                "targetOrg": "NAVERPAY",
                "lastPaymentInfo": { 
                    "tradeToken": "T20221212174800970116912", //支付单号 tradeToken 可用于退款
                    "lastPaymentStatus": "SUCCESS", // 最新扣款结果
                    "payTime": "2025-01-12T15:59:59+0000", // 支付时间
                }
            },
            {
                "subscriptionIndex": 1, // 扣款期数：第二期
                "paymentStatus": "PENDING", //本期订单状态
                "periodStartTime": "2025-02-13T15:59:59+0000", // 本期开始时间
                "periodEndTime": "2025-03-13T15:59:59+0000", // 本期结束时间
                "payAmount": { // 支付金额
                    "amount": "100",
                    "currency": "SAR"
                },
                "paymentMethodType": "WALLET",
                "targetOrg": "NAVERPAY",
                "lastPaymentInfo": { 
                    "tradeToken": "T20221212174800970116912", //支付单号 tradeToken 可用于退款
                    "lastPaymentStatus": "FAILED", // 最新扣款结果
                    "payTime": "2025-02-12T15:59:59+0000", // 支付时间
                    "errorCode": "xxxx", // 扣款失败code
                    "errorMsg": "xxxx", // 扣款失败原因
                }
            }
        ]
    }
}

9. 商户自行管理订阅

PayerMax也支持商户自己管理订阅计划，商户按自身场景设计订阅产品形式，PayerMax只接受商户的扣款请求。具体的集成交互流程与非周期性代扣相同。

集成模式概览

收单基础产品

CARD

GOOGLEPAY

APPLEPAY

订阅代扣

APM

CARD

APPLEPAY

前置组件

Tokenization

Auth-Capture

争议

业务风险管控

错误排查

API付款

支付方式列表

欧洲

APM-周期性订阅集成 ​

1. 准备事项 ​

2. 交互流程 ​

3. 订阅计划规则 ​

4. 创建订阅计划 ​

4.1 普通订阅计划 ​

4.2 n天试用 ​

4.3 前n期优惠 ​

5. 激活订阅计划 ​

5.1 收银台模式激活订阅计划 ​

5.2 API模式激活订阅计划 ​

5.3 前置组件模式激活订阅计划 ​

6. 获取订阅计划激活结果 ​

6.1 获取订阅计划状态变更结果 ​

6.2 获取订阅扣款结果 ​

6.3 获取订阅激活请求结果 ​

7. PayerMax后续扣款 ​

8. 管理订阅计划 ​

8.1 订阅状态变更通知 ​

8.2 取消订阅计划 ​

8.3 查询订阅扣款结果 ​

9. 商户自行管理订阅 ​

APM-周期性订阅集成

1. 准备事项

2. 交互流程

3. 订阅计划规则

4. 创建订阅计划

4.1 普通订阅计划

4.2 n天试用

4.3 前n期优惠

5. 激活订阅计划

5.1 收银台模式激活订阅计划

5.2 API模式激活订阅计划

5.3 前置组件模式激活订阅计划

6. 获取订阅计划激活结果

6.1 获取订阅计划状态变更结果

6.2 获取订阅扣款结果

6.3 获取订阅激活请求结果

7. PayerMax后续扣款

8. 管理订阅计划

8.1 订阅状态变更通知

8.2 取消订阅计划

8.3 查询订阅扣款结果

9. 商户自行管理订阅