跳到主要内容

QFPay订阅支付API

创建并管理订阅及订阅支付

订阅支付运行流程​

API运行环境​

环境名称地址
Sandboxhttps://openapi-int.qfapi.com

API资源​

如需要创建并管理一个订阅支付活动,需要如下的API资源:

API资源
Customer
Payment Token
Product
Subscription

创建订阅支付的流程​

enter image description here

信息

当前 subscription 的创建流程如下:

  1. 配置你的异步通知地址，你可以通过通知获取 token_id 并且跟进订阅支付的状态。
  2. 创建 customer 对象并获得 customer_id。
  3. 对接我们的 element 服务 并使用 elements.createEnhance() 和 payment.pay() 来构建 token 创建页面. 然后使用 customer_id 和卡信息来创建 token 并获得 token_id。
  4. 创建 product 对象并获得 product_id，你可以在 product 对象定义订阅支付的每个扣款周期的交易金额和两次扣款周期的间隔。
  5. 使用 customer_id, product_id 和 token_id 创建 subscription 对象，订阅支付的开始时间和总的扣款周期将在 subscription 对象定义。

订阅支付的状态​

state diagram 所有订阅状态一旦触发都会推送至商户后台服务

通用响应参数列表​

参数名称参数类型描述
respcdString返回码, 0000 = API呼叫成功
resperrString呼叫结果的详情
respmsgString呼叫的信息详情
dataObject结果值, JSON对象或由JSON对象组成的列表

返回数据示例

当呼叫 subscription/v1/query 之后

{
  "resperr": "success",
  "respcd": "0000",
  "respmsg": "success",
  "data": [
    {
      "total_billing_cycles": 3,
      "last_billing_time": "2024-11-21T11:12:06Z",
      "is_available": 1,
      "userid": 2510351,
      "last_billing_status": "SUCCESS",
      "state": "ACTIVE",
      "products": [
        { "product_id": "prod_8efecd0bd******b9aa1ec5ec01", "quantity": 1 }
      ],
      "retry_attempts": 0,
      "completed_iteration": 1,
      "token_id": "tk_9ac510017*******69b614e8f7ee",
      "subscription_id": "sub_e120378de*******da066f690da75",
      "customer_id": "cust_5ba1539f*******c9bda11d12c854e36",
      "next_billing_time": "2024-11-21T11:13:06Z"
    }
  ]
}

Customer​

Customer 是一个提供给商户用于存储客户信息的API资源. 这个对象可以被应用在 PaymentToken, Subscription API中.

创建 Customer 对象​

API 路径 : /customer/v1/create

请求参数列表​

参数名称参数类型是否必填描述
nameString否客户姓名
phoneString否客户联系方式
emailString否客户邮箱
billing_addressString否客户账单地址, 字符串化的JSON对象

在data部分的响应参数列表​

参数名称参数类型描述
customer_idStringQFPay 系统生成的唯一 customer 对象ID值

更新 customer 对象​

API 路径 : /customer/v1/update

请求参数列表​

参数名称参数类型是否必填描述
customer_idString是QFPay 系统生成的唯一 customer 对象ID值
nameString否客户姓名
phoneString否客户联系方式
emailString否客户邮箱
billing_addressJSON否客户账单地址

在data部分的响应参数列表​

参数名称参数类型描述
customer_idStringQFPay 系统生成的唯一 customer 对象ID值
rowAffectedInt更新的记录数量

查询 customer 对象​

API 路径 : /customer/v1/query

请求参数列表​

参数名称参数类型是否必填描述
customer_idString否QFPay 系统生成的唯一 customer 对象ID值
nameString否客户姓名
phoneString否客户联系方式
emailString否客户邮箱
pageInt否默认值 = 1
page_sizeInt否默认值 = 10, 最大值是100

在data部分的响应参数列表​

包含如下参数的 customer 对象数组：

参数名称参数类型描述
customer_idStringQFPay 系统生成的唯一 customer 对象ID值
nameString客户姓名
phoneString客户联系方式
emailString客户邮箱

删除 customer 对象​

永久删除 customer 对象, 不能撤销. 任何与已删除的 customer 对象相关联的订阅计划将会被取消 API 路径 : /customer/v1/delete

请求参数列表​

参数名称参数类型是否必填描述
customer_idString是QFPay 系统生成的唯一 customer 对象ID值

在data部分的响应参数列表​

参数名称参数类型描述
customer_idStringQFPay 系统生成的唯一 customer 对象ID值
rowDeletedInt删除的记录数量

Product​

Product 是商户要提供给客户的商品和服务的模型.它定义了交易金额, 交易货币和扣款周期(如可用). 这个对象可被用于 subscription API

创建 product 对象​

创建一个新的 product 对象

API 路径 : /product/v1/create

参数名称参数类型是否必填描述
nameString是展示给客户的产品名称
typeString否默认值=onetime, 可用值: onetime, recurring
descriptionString否产品描述
txamtInt是交易金额, e.g. $1=100。建议数值大于200，避免因支付金额过低而被交易风控。
txcurrcdString是交易货币, e.g. HKD
intervalString否可用值: monthly, yearly, 周期扣款产品必传（在 sandbox 环境中可以使用 minutes 和 hours 用于测试）
interval_countInt否两次扣款的间隔, 最高允许1年, 周期扣款产品必传
usage_typeString否默认值=licensed, 可用值: licensed

在data部分的响应参数列表​

参数名称参数类型描述
product_idStringQFPay 系统生成的唯一 product 对象的ID值

更新 product 对象​

更新当前的 product 对象信息 API 路径 : /product/v1/update

请求参数列表​

参数名称参数类型是否必填描述
product_idString是QFPay 系统生成的唯一 product 对象的ID值
nameString否展示给客户的产品名称
descriptionString否产品描述

在data部分的响应参数列表​

参数名称参数类型描述
product_idStringQFPay 系统生成的唯一 product 对象的ID值
rowAffectedInt更新的记录数量

查询 product 对象​

API 路径 : /product/v1/query

请求参数列表​

参数名称参数类型是否必填描述
product_idString否QFPay 系统生成的唯一 product 对象的ID值
nameString否展示给客户的产品名称
descriptionString否产品描述
txcurrcdString否交易货币
intervalString否可用值: monthly,yearly
pageInt否page no., 默认值=1
page_sizeInt否page size, 默认值=10,max value=100

在data部分的响应参数列表​

包含如下参数的 product 对象数组:

product_idStringQFPay 系统生成的唯一 product 对象的ID值
nameString展示给客户的产品名称
typeString可用值: onetime, recurring
descriptionString产品描述
txamtInt交易金额, e.g. $1=100。建议数值大于200，避免因支付金额过低而被交易风控。
txcurrcdString交易货币, e.g. HKD
intervalString可用值: monthly, yearly
interval_countInt两次扣款的间隔
usage_typeString可用值: licensed

删除 product 对象​

只能够删除不与任何 subscription 对象关联的 product 对象

API 路径 : /product/v1/delete

请求参数列表​

参数名称参数类型是否必填描述
product_idString否QFPay 系统生成的唯一 product 对象的ID值

在data部分的响应参数列表​

参数名称参数类型描述
product_idStringQFPay 系统生成的唯一 product 对象的ID值
rowDeletedInt删除的记录数量

Subscription​

QFPay 会基于产品类型和支付令牌,在每个扣款周期自动向客户收费直到订阅结束或是取消. 在创建 subscription 对象之前, payment token, customer 和 product 必须被创建.

创建 subscription 对象​

API 路径 : /subscription/v1/create

请求参数列表​

参数名称参数类型是否必填描述
customer_idString是QFPay 系统生成的唯一 customer 对象ID值
token_idString是QFPay 系统生成的唯一 payment token 对象的ID值
productsObject是QFPay 系统生成的唯一 product 对象的ID值和相应数量的列表
total_billing_cyclesInt否订阅支付总的扣款周期, 若为null值则为无限
start_timeString否订阅开始时间,订阅将开始首次扣款

products 中的参数:

参数名称参数类型是否必填描述
product_idString是QFPay 系统生成的唯一 product 对象的ID值
quantityInt否默认值=1

示例:

{
  "products": [
      {
          "product_id": "prod_54c3772d******9a54b236e09ec74f",
          "quantity": 1
      }
  ],
  "customer_id": "cust_aaf6aae94******982c54c9cae5ba32",
  "token_id": "tk_a99892fd*********d3417d168a18bb",
  "total_billing_cycles": 2,
  "start_time": "2020-05-14 12:32:56"
}

在data部分的响应参数列表​

参数名称参数类型描述
subscription_idStringQFPay 系统生成的唯一 subscription 对象ID值
stateString第一次创建后 subscription 的状态，包含：ACTIVE, INCOMPLETE, COMPLETED

更新 subscription 对象​

更新当前的 subscription 对象 API 路径 : /subscription/v1/update

请求参数列表​

参数名称参数类型是否必填描述
subscription_idString是QFPay 系统生成的唯一 subscription 对象的ID值
total_billing_cyclesInt否订阅支付总的扣款周期, 若为null值则为无限
start_timeString否订阅开始时间,订阅将开始首次扣款
token_idString否QFPay 系统生成的唯一 payment token 对象的ID值
productsObject否QFPay 系统生成的唯一 product 对象的ID值和想赢数量的列表

在data部分的响应参数列表​

参数名称参数类型描述
subscription_idStringQFPay 系统生成的唯一 subscription 对象的ID值
rowAffectedInt更新的记录数量

查询 subscription 对象​

API 路径 : /subscription/v1/query

请求参数列表​

参数名称参数类型是否必填描述
pageInt否查询页数,默认值=1
page_sizeInt否查询页面大小, 默认值=10, 最大值=100
subscritpion_idString否QFPay 系统生成的唯一 subscription 对象的ID值
customer_idString否QFPay 系统生成的唯一 customer 对象ID值
token_idString否QFPay 系统生成的唯一 payment token 对象的ID值
stateString否订阅的状态, e.g. incompelete, active,...

在data部分的响应参数列表​

包含如下参数的 subscription 对象数组:

参数名称参数类型描述
subscription_idStringQFPay 系统生成的唯一 subscription 对象的ID值
customer_idStringQFPay 系统生成的唯一 customer 对象ID值
token_idStringQFPay 系统生成的唯一 payment token 对象的ID值
productsObjectQFPay 系统生成的唯一 product 对象的ID值和相应数量的列表
total_billing_cyclesInt订阅支付总的扣款周期, 若为null值则为无限
stateString订阅的状态
next_billing_timeString下次扣款时间
last_billing_timeString上次扣款时间
completed_billing_iterationInt已完成的扣款次数
start_timeString订阅开始时间,订阅将开始首次扣款

取消 subscription 订阅​

立即取消客户的订阅

API 路径 : /subscription/v1/cancel

请求参数列表​

参数名称参数类型是否必填描述
subscription_idString是QFPay 系统中的唯一 subscription 对象ID

在data部分的响应参数列表​

参数名称参数类型描述
subscription_idStringQFPay 系统中的唯一 subscription 对象ID
rowDeletedInt删除的记录数量

查询指定 subscription 订阅下的订单​

API 路径 : /subscription/billing_order/v1/list

请求方法 : POST

请求参数列表​

参数名称参数类型是否必填描述
subscription_idString是QFPay 系统中的唯一 subscription 对象ID
pageInt否查询页数,默认值=1
page_sizeInt否查询页面大小, 默认值=10, 最大值=100

在data部分的响应参数列表​

包含如下参数的 subscription order 对象数组:

参数名称参数类型描述
subscription_order_idString扣款订单的标识ID, 格式: sub_ord_ + 所属 subscription 对象的 id 值 + 4 位标识该订单为第几次扣款。例如：sub_ord_a360f06exxxxxxx4c3a_0001 表示 subscription sub_a360f06exxxxxxx4c3a 的第一次扣款订单
subscription_idStringQFPay 系统中的唯一 subscription 对象ID, 格式: sub_xxxxxxxx 例如： sub_a360f06exxxxxxx4c3a
trigger_byString谁触发此次订单扣款, QFPay 系统是 auto, 手动扣款是 manual
sequence_noInt该订单是所属的 subscription 的第几次扣款, 例如：2

对订阅手动扣款​

使用 API 来对一个订阅计划手动立即扣款, 扣款行为与自动扣款相同.

API 路径 : /subscription/v1/charge

请求方法 : POST

请求参数​

参数名称类型是否必填描述
subscription_idString是QFPay 系统中的唯一 subscription 对象ID
subscription_order_idString否扣款订单的标识ID, 格式: sub_ord_ + 所属 subscription 对象的 id 值 + 4 位标识该订单为第几次扣款。例如：sub_ord_a360f06exxxxxxx4c3a_0001 表示 subscription sub_a360f06exxxxxxx4c3a 的第一次扣款订单

该 API 只适用于有失败订单的订阅计划，该订阅计划应有如下之一的状态 UNPAID, INCOMPLETE, 或 PAST_DUE。 手动扣款成功后，如果扣款日期在订阅计划的下次计划扣款日期前，那么订阅计划将以状态ACTIVE正常运行；如果扣款在订阅计划的下次计划扣款日期之后, 订阅计划将被取消，客户需要重新订阅计划。如果扣款失败，订阅计划将保持原来的状态。

订阅支付行为​

异步通知​

通知适用于支付令牌的创建和订阅相关的事件和状态变化。

在成功创建支付令牌或激活订阅后，QFPay API 将向商户定义的 URL 发送异步通知消息。

备注

要配置通知地址，请通过电子邮件将地址以及商户和门店信息发送至 technical.support@qfpay.com

格式：JSON

支付令牌​

参数名称描述
useridQFPay Store ID
notify_type通知类型，payment_token
event令牌事件, 可以是 NEW, MATCH(该卡之前已经创建了 token)，CONFLICT(该卡之前已经创建了 token，但新提交的资料与上次不符)
tokenid支付令牌 ID
token_expiry_date令牌过期日期
cardcd卡号
card_scheme卡组织，例如 VISA
respcd响应码，例如 0000 (成功)
respmsg响应消息，例如 成功
sysdtm事件触发的系统时间
customer_id如果有的话是客户 ID
token_reasontokenization 的原因
token_reference系统中的 tokenization 的参考

示例：

{
    "respmsg": "",
    "card_scheme": "ECMC_DEBIT",
    "cardcd": "5200****1096",
    "tokenid": "tk_6a699aae75094caeb066f****988daa32de",
    "respcd": "0000",
    "token_expiry_date": "2024-04-30 00:00:00",
    "sysdtm": "2024-04-29 15:37:17",
    "notify_type": "payment_token",
    "event": "CONFLICT"
}

订阅状态变更​

当订阅状态发生变更时，会发送通知。

参数名称描述
notify_type通知类型 subscription
subscription_id唯一的 subscription 对象标识符，格式：sub_xxxxxxxx
state订阅状态，例如 COMPLETED, ACTIVE, 完整的状态可参考状态
sysdtm状态变更的系统时间

示例：

{
  "state": "COMPLETED",
  "sysdtm": "2024-04-24 15:19:39",
  "notify_type": "subscription",
  "subscription_id": "sub_e51bb914919*****f6b0fe36d"
}

订阅支付结果​

当收到订阅订单支付结果时，会发送通知。

参数名称描述
notify_type通知类型，subscription_payment
subscription_id唯一的 subscription 对象标识符，格式：sub_xxxxxxxx 例如 sub_a360f06exxxxxxx4c3a
subscription_order_id扣款订单的标识ID, 格式: sub_ord_ + 所属 subscription 对象的 id 值 + 4 位标识该订单为第几次扣款。例如：sub_ord_a360f06exxxxxxx4c3a_0001 表示 subscription sub_a360f06exxxxxxx4c3a 的第一次扣款订单
respcd响应码，例如 0000（成功情况）
respmsg响应消息，例如 success
syssn交易流水号
txdtm交易时间
txamt交易金额
txcurrcd交易货币
customer_id唯一的 customer 对象标识符，格式：cust_xxxxxx
product_id所有 product 对象的唯一标识符，使用逗号分隔，例如：prod_xxxxxa23f30,prod_xxxxxbe342ac
cardcd卡号
card_scheme仅适用于 0000，卡组织，例如 VISA
current_iteration此订阅的当前迭代次数，例如 1

示例：

{
  "txcurrcd": "HKD",
  "reason": "AUTHORISED",
  "cardcd": "",
  "subscription_order_id": "sub_ord_a360f06eb*****ad6aff24c3a",
  "product_id": "prod_8c838c17ddb043b9***11f1a85c30",
  "txdtm": "2024-04-24 15:19:37",
  "txamt": "300",
  "card_scheme": "VISA_DEBIT-SSL",
  "syssn": "20240424180500020000015704",
  "respcd": "0000",
  "subscription_id": "sub_e51bb914919***31d800f6b0fe36d",
  "customer_id": "cust_a9c0bcf2717f4***786a10e5f8f2",
  "notify_type": "subscription_payment",
  "current_iteration": "1",
}