QFPay订阅支付API
创建并管理订阅及订阅支付
订阅支付运行流程
API运行环境
| 环境名称 | 地址 |
|---|---|
| Sandbox | https://openapi-int.qfapi.com |
API资源
如需要创建并管理一个订阅支付活动,需要如下的API资源:
| API资源 |
|---|
| Customer |
| Payment Token |
| Product |
| Subscription |
创建订阅支付的流程
订阅支付的状态
state diagram 所有订阅状态一旦触发都会推送至商户后台服务
通用响应参数列表
| 参数名称 | 参数类型 | 描述 |
|---|---|---|
| respcd | String | 返回码, 0000 = API呼叫成功 |
| resperr | String | 呼叫结果的详情 |
| respmsg | String | 呼叫的信息详情 |
| page | Int | 查询页数,在查询API中出现 |
| page_size | Int | 查询页大小,在查询API中出现 |
| data | Object | 结果值, JSON对象或由JSON对象组成的列表 |
Customer
Customer 是一个提供给商户用于存储客户信息的API资源. 这个对象可以被应用在 PaymentToken, Subscription API中.
创建 Customer 对象
API路径: /customer/v1/create
请求参数列表:
| 参数名称 | 参数类型 | 是否必填 | 描述 |
|---|---|---|---|
| name | String | 否 | 客户姓名 |
| phone | String | 否 | 客户联系方式 |
| String | 否 | 客户邮箱 | |
| billing_address | String | 否 | 客户账单地址, 字符串化的JSON对象 |
在data部分的响应参数列表:
| 参数名称 | 参数类型 | 描述 |
|---|---|---|
| customer_id | String | QFPay 系统生成的唯一 customer 对象ID值 |
| name | String | 客户姓名 |
| phone | String | 客户联系方式 |
| String | 客户邮箱 | |
| billing_address | JSON | 客户账单地址 |
更新 customer 对象
API路径: /customer/v1/update
请求参数列表:
| 参数名称 | 参数类型 | 是否必填 | 描述 |
|---|---|---|---|
| customer_id | String | 是 | QFPay 系统生成的唯一 customer 对象ID值 |
| name | String | 否 | 客户姓名 |
| phone | String | 否 | 客户联系方式 |
| String | 否 | 客户邮箱 | |
| billing_address | JSON | 否 | 客户账单地址 |
在data部分的响应参数列表:
| 参数名称 | 参数类型 | 描述 |
|---|---|---|
| customer_id | String | QFPay 系统生成的唯一 customer 对象ID值 |
| name | String | 客户姓名 |
| phone | String | 客户联系方式 |
| String | 客户邮箱 | |
| billing_address | JSON | 客户账单地址 |
查询 customer 对象
API路径: /customer/v1/query
请求参数列表:
| 参数名称 | 参数类型 | 是否必填 | 描述 |
|---|---|---|---|
| customer_id | String | 否 | QFPay 系统生成的唯一 customer 对象ID值 |
| name | String | 否 | 客户姓名 |
| phone | String | 否 | 客户联系方式 |
| String | 否 | 客户邮箱 | |
| page | Int | 否 | 默认值 = 1 |
| page_size | Int | 否 | 默认值 = 10, 最大值是100 |
在data部分的响应参数列表:
| 参数名称 | 参数类型 | 描述 |
|---|---|---|
| customer_id | String | QFPay 系统生成的唯一 customer 对象ID值 |
| name | String | 客户姓名 |
| phone | String | 客户联系方式 |
| String | 客户邮箱 |
删除 customer 对象
永久删除 customer 对象, 不能撤销. 任何与已删除的 customer 对象相关联的订阅计划将会被取消
API路径: /customer/v1/delete
请求参数列表:
| 参数名称 | 参数类型 | 是否必填 | 描述 |
|---|---|---|---|
| customer_id | String | 是 | QFPay 系统生成的唯一 customer 对象ID值 |
Product
Product 是商户要提供给客户的商品和服务的模型.它定义了交易金额, 交易货币和扣款周期(如可用). 这个对象可被用于 subscription API
创建 product 对象
创建一个新的 product 对象
API路径: /product/v1/create
| 参数名称 | 参数类型 | 是否必填 | 描述 |
|---|---|---|---|
| name | String | 是 | 展示给客户的产品名称 |
| type | String | 否 | 默认值=onetime, 可用值: onetime, recurring |
| description | String | 否 | 产品描述 |
| txamt | Int | 是 | 交易金额, e.g. $1=100 |
| txcurrcd | String | 是 | 交易货币, e.g. HKD |
| interval | String | 否 | 可用值: monthly, yearly, 周期扣款产品必传 |
| interval_count | Int | 否 | 两次扣款的间隔, 最高允许1年, 周期扣款产品必传 |
| usage_type | String | 否 | 默认值=licensed, 可用值: licensed |
在data部分的响应参数列表:
| 参数名称 | 参数类型 | 描述 |
|---|---|---|
| product_id | String | QFPay 系统生成的唯一 product 对象的ID值 |
| name | String | 展示给客户的产品名称 |
| type | String | 默认值=onetime, 可用值: onetime, recurring |
| description | String | 产品描述 |
| txamt | Int | 交易金额, e.g. $1=100 |
| txcurrcd | String | 交易货币, e.g. HKD |
| interval | String | 可用值: monthly, yearly |
| interval_count | Int | 两次扣款的间隔 |
| usage_type | String | 默认值=licensed, 可用值: licensed |
更新 product 对象
更新当前的 product 对象信息
API路径: /product/v1/update
请求参数列表:
| 参数名称 | 参数类型 | 是否必填 | 描述 |
|---|---|---|---|
| product_id | String | 是 | QFPay 系统生成的唯一 product 对象的ID值 |
| name | String | 否 | 展示给客户的产品名称 |
| description | String | 否 | 产品描述 |
在data部分的响应参数列表:
| 参数名称 | 参数类型 | 描述 |
|---|---|---|
| product_id | String | QFPay 系统生成的唯一 product 对象的ID值 |
| name | String | 展示给客户的产品名称 |
| type | String | 默认值=onetime, 可用值: onetime, recurring |
| description | String | 产品描述 |
| txamt | Int | 交易金额, e.g. $1=100 |
| txcurrcd | String | 交易货币, e.g. HKD |
| interval | String | 可用值: monthly, yearly |
| interval_count | Int | 两次 扣款的间隔 |
| usage_type | String | 默认值=licensed, 可用值: licensed |
查询 product 对象
API路径: /product/v1/create
请求参数列表:
| 参数名称 | 参数类型 | 是否必填 | 描述 |
|---|---|---|---|
| product_id | String | 否 | QFPay 系统生成的唯一 product 对象的ID值 |
| name | String | 否 | 展示给客户的产品名称 |
| description | String | 否 | 产品描述 |
| txcurrcd | String | 否 | 交易货币 |
| interval | String | 否 | 可用值: monthly,yearly |
| page | Int | 否 | page no., 默认值=1 |
| page_size | Int | 否 | page size, 默认值=10,max value=100 |
在data部分的响应参数列表:
| product_id | String | QFPay 系统生成的唯一 product 对象的ID值 |
|---|---|---|
| name | String | 展示给客户的产品名称 |
| type | String | 可用值: onetime, recurring |
| description | String | 产品描述 |
| txamt | Int | 交易金额, e.g. $1=100 |
| txcurrcd | String | 交易货币, e.g. HKD |
| interval | String | 可用值: monthly, yearly |
| interval_count | Int | 两次扣款的间隔 |
| usage_type | String | 可用值: licensed |
删除 product 对象
只能够删除不与任何 subscription 对象关联的 product 对象
API路径: /product/v1/delete
请求参数列表:
| 参数名称 | 参数类型 | 是否必填 | 描述 |
|---|---|---|---|
| product_id | String | 否 | QFPay 系统生成的唯一 product 对象的ID值 |
Subscription
QFPay 会基于产品类型和支付令牌,在每个扣款周期自动向客户收费直到订阅结束或是取消. 在创建 subscription 对象之前, payment token, customer 和 product 必须被创建.
创建 subscription 对象
API路径: /subscription/v1/create
请求参数列表:
| 参数名称 | 参数类型 | 是否必填 | 描述 |
|---|---|---|---|
| customer_id | String | 是 | QFPay 系统生成的唯一 customer 对象ID值 |
| token_id | String | 是 | QFPay 系统生成的唯一 payment token 对象的ID值 |
| products | Object | 是 | QFPay 系统生成的唯一 product 对象的ID值和相应数量的列表 |
| total_billing_cycles | Int | 否 | 订阅支付总的扣款周期, 若为null值则为无限 |
| start_time | String | 否 | 订阅开始时间,订阅将开始首次扣款 |
products 中的参数:
| 参数名称 | 参数类型 | 是否必填 | 描述 |
|---|---|---|---|
| product_id | String | 是 | QFPay 系统生成的唯一 product 对象的ID值 |
| quantity | Int | 否 | 默认值=1 |
在data部分的响应参数列表:
| 参数名称 | 参数类型 | 描述 |
|---|---|---|
| customer_id | String | QFPay 系统生成的唯一 customer 对象ID值 |
| token_id | String | QFPay 系统生成的唯一 payment token 对象的ID值 |
| products | Object | QFPay 系统生成的唯一 product 对象的ID值和相应数量的列表 |
| total_billing_cycles | Int | 订阅支付总的扣款周期, 若为null值则为无限 |
| start_time | String | 否 |
更新 subscription 对象
更新当前的 subscription 对象
API路径: /subscription/v1/update
请求参数列表:
| 参数名称 | 参数类型 | 是否必填 | 描述 |
|---|---|---|---|
| subscription_id | String | 是 | QFPay 系统生成的唯一 subscription 对象的ID值 |
| total_billing_cycles | Int | 否 | 订阅支付总的扣款周期, 若为null值则为无限 |
| start_time | String | 否 | 订阅开始时间,订阅将开始首次扣款 |
| token_id | String | 否 | QFPay 系统生成的唯一 payment token 对象的ID值 |
| products | Object | 否 | QFPay 系统生成的唯一 product 对象的ID值和想赢数量的列表 |
在data部分的响应参数列表:
| 参数名称 | 参数类型 | 描述 |
|---|---|---|
| subscription_id | String | QFPay 系统生成的唯一 subscription 对象的ID值 |
| customer_id | String | QFPay 系统生成的唯一 customer 对象ID值 |
| token_id | String | QFPay 系统生成的唯一 payment token 对象的ID值 |
| products | Object | QFPay 系统生成的唯一 product 对象的ID值和相应数量的列表 |
| total_billing_cycles | Int | 订阅支付总的扣款周期, 若为null值则为无限 |
| start_time | String | 订阅开始时间,订阅将开始首次扣款 |
| state | String | 订阅的状态 |
查询 subscription 对象
API路径: /subscription/v1/query
请求参数列表:
| 参数名称 | 参数类型 | 是否必填 | 描述 |
|---|---|---|---|
| page | Int | 否 | 查询页数,默认值=1 |
| page_size | Int | 否 | 查询页面大小, 默认值=10, 最大值=100 |
| subscritpion_id | String | 否 | QFPay 系统生成的唯一 subscription 对象的ID值 |
| customer_id | String | 否 | QFPay 系统生成的唯一 customer 对象ID值 |
| token_id | String | 否 | QFPay 系统生成的唯一 payment token 对象的ID值 |
| state | String | 否 | 订阅的状态, e.g. incompelete, active,... |
在data部分的响应参数列表:
| 参数名称 | 参数类型 | 描述 |
|---|---|---|
| subscription_id | String | QFPay 系统生成的唯一 subscription 对象的ID值 |
| customer_id | String | QFPay 系统生成的唯一 customer 对象ID值 |
| token_id | String | QFPay 系统生成的唯一 payment token 对象的ID值 |
| products | Object | QFPay 系统生成的唯一 product 对象的ID值和相应数量的列表 |
| total_billing_cycles | Int | 订阅支付总的扣款周期, 若为null值则为无限 |
| state | String | 订阅的状态 |
| next_billing_time | String | 下次扣款时间 |
| last_billing_time | String | 上次扣款时间 |
| completed_billing_iteration | Int | 已完成的扣款次数 |
| start_time | String | 订阅开始时间,订阅将开始首次扣款 |
Cancel subscription 对象
立即取消客户的订阅
API路径: /subscription/v1/cancel
请求参数列表:
| 参数名称 | 参数类型 | 是否必填 | 描述 |
|---|---|---|---|
| subscription_id | String | 是 | QFPay 系统中的唯一订阅对象ID |