curl -X POST "${BASE_URL}/api/v2/subscription/create" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "merchant_id": "48290713",
  "customer": {
    "customer_id": "CUS48290713"
  },
  "plan": {
    "plan_name": "Monthly membership",
    "recurring": {
      "enabled": 1,
      "schedule_name": "Monthly fee",
      "recurring_type": 3,
      "amount": "25.50",
      "start_date": "2030-01-10",
      "day_of_debit": "FREQ=MONTHLY;INTERVAL=1;BYMONTHDAY=15"
    },
    "surcharge_config": []
  },
  "notify_email": false,
  "notify_sms": false
}'

{
  "code": 0,
  "message": "ok",
  "data": {
    "customer_id": "CUS48290713",
    "plan_id": "DDR73019482",
    "status": 2,
    "activation_url": "https://staging-api.billbuddyhq.com/api/v2/subscription/activatePage/73a9c4f128d60b5e9a2746cd801fb352",
    "activation_html": "<!DOCTYPE html><html><head><meta charset=\"UTF-8\"><meta http-equiv=\"refresh\" content=\"0;url=https://staging-api.billbuddyhq.com/api/v2/subscription/activatePage/73a9c4f128d60b5e9a2746cd801fb352\"><style>html,body{height:100%;margin:0}body{display:flex;align-items:center;justify-content:center;font-family:-apple-system,Segoe UI,Roboto,Arial,sans-serif;color:#444;background:#fff}.tip{text-align:center;font-size:16px}.spin{width:28px;height:28px;margin:0 auto 12px;border:3px solid #ddd;border-top-color:#888;border-radius:50%;animation:r .8s linear infinite}@keyframes r{to{transform:rotate(360deg)}}</style></head><body><div class=\"tip\"><div class=\"spin\"></div>Redirecting...</div><form method=\"get\" action=\"https://staging-api.billbuddyhq.com/api/v2/subscription/activatePage/73a9c4f128d60b5e9a2746cd801fb352\" target=\"_self\" id=\"checkform\" name=\"checkform\"></form><script>window.onload=function(){document.checkform.submit();};</script></body></html>"
  }
}

创建托管订阅

选择订阅模式

推荐使用 customer 和 plan 嵌套参数。客户信息二选一：已有客户填写 customer.customer_id；新客户填写 customer.firstName、customer.lastName、customer.emailAddress，不要同时提供已有客户标识。

模式	提交参数	条件及限制
手填订阅	`plan.plan_name`，以及 `plan.recurring`、`plan.one_off` 中至少一个启用段	启用段的 `enabled` 设为 1；可同时启用周期和一次性段
模板订阅	`plan.template_id` 及模板对应日期	模板含周期段时提供 `plan.start_date`，含一次性段时提供 `plan.payment_date`；`plan_name` 可省略继承模板
By agreement	`plan.plan_name` 和 `plan.schedule`	首条计划填写 `schedule_name`、`type`、`amount`、`start_date`；类型只允许 1、2、3、4、6

三种模式互斥。手填周期段启用时，须提供 schedule_name、recurring_type、amount、start_date、day_of_debit。一次性段启用时，须提供 schedule_name、amount、payment_date。日期至少为业务时区的明天。

周期结束条件	额外必填参数
`recurring_type=1` / `schedule.type=1`，按成功期数	`end_terms`
`recurring_type=2` / `schedule.type=2`，按累计金额	`total_amount`，且 `amount` 不得大于 `total_amount`
`recurring_type=3` / `schedule.type=3`，持续至取消	无额外结束条件
`recurring_type=4` / `schedule.type=4`，按结束日期	`end_date`，不得早于同段的 `start_date`
`schedule.type=6`，一次性	不要求 `day_of_debit`；此类型不适用于 `recurring_type`

季度、半年、年度频率须提供 day_of_debit_dtstart。自定义频率须提供 process_type=12、custom_cycle_type 和 custom_cycle，并与 RRULE 一致。具体范围及日期窗口见字段说明。

顶层同名替代参数仍受支持；建议新接入统一使用嵌套形式。两种形式同时出现时，同名的嵌套字段优先。

创建成功后 status=2 Inactive，订阅尚未激活。将返回的完整 activation_url 原样提供给客户打开，或设为 iframe 的 src；也可将 activation_html 用作 iframe 的 srcdoc。客户在 BillBuddy 提供的页面填写支付信息并完成授权和激活。无需自行拼接激活链接或解析凭证，Client Secret 和 access_token 仅保存在商户服务端。三种定义模式互斥：recurring/one_off 手填模式、template_id 模板模式、schedule By agreement 模式。模板模式须提供其启用部分的日期（周期 start_date、一次性 payment_date）。新客户信息与已有客户引用互斥。推荐使用 customer/plan 嵌套参数；替代参数形式见字段说明。成功响应可能不含激活链接，此时请联系 BillBuddy 核对已创建订阅后再处理；接口未提供调用方幂等编号，请勿盲目重试创建。周期订阅及 By agreement 须在 start_date 当天之前激活；纯一次性订阅须在创建后 30 天内提交激活。页面可以打开不保证仍可提交，以激活接口结果为准。

所有示例均为格式示例，客户、订单、卡及账户数据须替换为测试环境获准使用的数据。BASE_URL 为服务根域名，不附加 /api/v2；ACCESS_TOKEN 为 /oauth/token 返回的 access_token。日期示例为 2030 年，执行时请改为满足当前日期限制的实际日期。

POST

api

subscription

create

curl -X POST "${BASE_URL}/api/v2/subscription/create" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "merchant_id": "48290713",
  "customer": {
    "customer_id": "CUS48290713"
  },
  "plan": {
    "plan_name": "Monthly membership",
    "recurring": {
      "enabled": 1,
      "schedule_name": "Monthly fee",
      "recurring_type": 3,
      "amount": "25.50",
      "start_date": "2030-01-10",
      "day_of_debit": "FREQ=MONTHLY;INTERVAL=1;BYMONTHDAY=15"
    },
    "surcharge_config": []
  },
  "notify_email": false,
  "notify_sms": false
}'

{
  "code": 0,
  "message": "ok",
  "data": {
    "customer_id": "CUS48290713",
    "plan_id": "DDR73019482",
    "status": 2,
    "activation_url": "https://staging-api.billbuddyhq.com/api/v2/subscription/activatePage/73a9c4f128d60b5e9a2746cd801fb352",
    "activation_html": "<!DOCTYPE html><html><head><meta charset=\"UTF-8\"><meta http-equiv=\"refresh\" content=\"0;url=https://staging-api.billbuddyhq.com/api/v2/subscription/activatePage/73a9c4f128d60b5e9a2746cd801fb352\"><style>html,body{height:100%;margin:0}body{display:flex;align-items:center;justify-content:center;font-family:-apple-system,Segoe UI,Roboto,Arial,sans-serif;color:#444;background:#fff}.tip{text-align:center;font-size:16px}.spin{width:28px;height:28px;margin:0 auto 12px;border:3px solid #ddd;border-top-color:#888;border-radius:50%;animation:r .8s linear infinite}@keyframes r{to{transform:rotate(360deg)}}</style></head><body><div class=\"tip\"><div class=\"spin\"></div>Redirecting...</div><form method=\"get\" action=\"https://staging-api.billbuddyhq.com/api/v2/subscription/activatePage/73a9c4f128d60b5e9a2746cd801fb352\" target=\"_self\" id=\"checkform\" name=\"checkform\"></form><script>window.onload=function(){document.checkform.submit();};</script></body></html>"
  }
}

授权

Authorization

string

header

必填

OAuth2 client_credentials 授权。access_token 到期后重新获取。

请求体

application/json

创建待激活订阅。客户引用与新客户资料二选一；新客户必须完整提供 firstName、lastName、emailAddress。订阅定义必须且只能选择手填、模板或 By agreement 一种。手填模式至少启用一个收费段；非模板模式必须提供 plan_name。推荐使用 customer、plan 嵌套参数。

merchant_id

string

必填

业务标识，由 BillBuddy 分配。

Required string length: 1 - 20

notify_email

是否允许本交易或订阅相关邮件通知。false 表示禁止，true 表示允许；省略或 null 时使用该业务的 API 邮件通知设置，默认关闭。实际发送受通知偏好和适用规则约束。也兼容 0/1 和字符串 "0"/"1"。

notify_sms

是否允许本交易或订阅相关短信通知。false 表示禁止，true 表示允许；省略或 null 时使用该业务的 API 短信通知设置，默认关闭。实际发送受通知偏好和适用规则约束。也兼容 0/1 和字符串 "0"/"1"。

customer

object

复用客户时传 customer_id；新建客户时传 firstName、lastName、emailAddress，二者互斥。

Show child attributes

plan

object

恰好选择一种模式：recurring/one_off 手填；template_id 模板；schedule By agreement。

Show child attributes

customer_id

string | null

仍支持的顶层替代参数；推荐使用 customer.customer_id。同名嵌套字段与本字段同时提供时，以嵌套字段为准。

BillBuddy 客户标识，须为当前商户及业务范围内的有效客户。

Maximum string length: 32

firstName

string | null

仍支持的顶层替代参数；推荐使用 customer.firstName。同名嵌套字段与本字段同时提供时，以嵌套字段为准。

新客户名字。创建新客户时必填。

Maximum string length: 100

lastName

string | null

仍支持的顶层替代参数；推荐使用 customer.lastName。同名嵌套字段与本字段同时提供时，以嵌套字段为准。

新客户姓氏。创建新客户时必填。

Maximum string length: 100

emailAddress

string<email> | null

仍支持的顶层替代参数；推荐使用 customer.emailAddress。同名嵌套字段与本字段同时提供时，以嵌套字段为准。

新客户主邮箱。创建新客户时必填；同一商户及业务范围内已有此邮箱时请改传已有 customer_id。

Maximum string length: 500

mobilePhoneNumber

string | null

仍支持的顶层替代参数；推荐使用 customer.mobilePhoneNumber。同名嵌套字段与本字段同时提供时，以嵌套字段为准。

客户手机号。

Maximum string length: 20

addressLine1

string | null

仍支持的顶层替代参数；推荐使用 customer.addressLine1。同名嵌套字段与本字段同时提供时，以嵌套字段为准。

客户地址第一行。

Maximum string length: 255

addressSuburb

string | null

仍支持的顶层替代参数；推荐使用 customer.addressSuburb。同名嵌套字段与本字段同时提供时，以嵌套字段为准。

客户城市或区。

Maximum string length: 100

addressState

string | null

仍支持的顶层替代参数；推荐使用 customer.addressState。同名嵌套字段与本字段同时提供时，以嵌套字段为准。

客户州或省。

Maximum string length: 100

addressPostCode

string | null

仍支持的顶层替代参数；推荐使用 customer.addressPostCode。同名嵌套字段与本字段同时提供时，以嵌套字段为准。

客户邮编。

Maximum string length: 50

plan_name

string | null

仍支持的顶层替代参数；推荐使用 plan.plan_name。同名嵌套字段与本字段同时提供时，以嵌套字段为准。

订阅名称；模板模式可省略或传 null 并继承模板名称，其他模式必填且不能为空。

Maximum string length: 255

description

string | null

仍支持的顶层替代参数；推荐使用 plan.description。同名嵌套字段与本字段同时提供时，以嵌套字段为准。

说明。

Maximum string length: 500

recurring

object | null

仍支持的顶层替代参数；推荐使用 plan.recurring。同名嵌套字段与本字段同时提供时，以嵌套字段为准。

周期订阅定义。

Show child attributes

one_off

object | null

仍支持的顶层替代参数；推荐使用 plan.one_off。同名嵌套字段与本字段同时提供时，以嵌套字段为准。

一次性付款定义；和 recurring 同启用时作为 Deposit，单独使用时为 One-off。

Show child attributes

schedule

object | null

仍支持的顶层替代参数；推荐使用 plan.schedule。同名嵌套字段与本字段同时提供时，以嵌套字段为准。

By agreement 首条扣费计划定义。与 recurring/one_off 手填模式、template_id 模式互斥。

Show child attributes

surcharge_config

enum<string>[] | null

仍支持的顶层替代参数；推荐使用 plan.surcharge_config。同名嵌套字段与本字段同时提供时，以嵌套字段为准。

附加费选项，建议提交字符串数组，可选项见 Schema 和示例。省略、null 或空数组表示全部关闭；非数组也按全部关闭处理，未知选项不启用收费。credit_card_surcharge 表示信用卡附加费分组。实际是否收取受商户业务规则及支付方式限制。手填模式使用此设置；模板模式使用模板的附加费选项，本字段不覆盖模板；By agreement 的 schedule 模式不支持此设置。卡类附加费受适用收费政策限制；政策不允许收费时，即使提交卡类选项也不启用收费。

附加费选项。

可用选项:

direct_debit_surcharge,

visa_domestic_surcharge,

visa_international_surcharge,

mastercard_domestic_surcharge,

mastercard_international_surcharge,

amex_domestic_surcharge,

amex_international_surcharge,

credit_card_surcharge

dishonour_fee_switch

仍支持的顶层替代参数；推荐使用 plan.dishonour_fee_switch。同名嵌套字段与本字段同时提供时，以嵌套字段为准。

是否收取客户扣款退票费，省略或 null 默认关闭。启用须已有适用的正数费额配置，实际金额以签署条款为准。也兼容 0/1 和字符串 "0"/"1"。仅适用于 recurring/one_off 手填模式；模板模式和 By agreement 的 schedule 模式不支持通过本字段设置。

template_id

string | null

仍支持的顶层替代参数；推荐使用 plan.template_id。同名嵌套字段与本字段同时提供时，以嵌套字段为准。

可用模板 ID，来自 GET /api/v2/plan/list；只接受启用、ACTIVE、非阶梯且非 By agreement 的模板。

Maximum string length: 20

start_date

string<date> | null

仍支持的顶层替代参数；推荐使用 plan.start_date。同名嵌套字段与本字段同时提供时，以嵌套字段为准。

模板中 recurring 段的日期覆盖值。模板含 recurring 时必填；至少服务业务时区的明天。

payment_date

string<date> | null

仍支持的顶层替代参数；推荐使用 plan.payment_date。同名嵌套字段与本字段同时提供时，以嵌套字段为准。

模板中 one_off 段的日期覆盖值。模板含 one_off 时必填；至少服务业务时区的明天。

响应

HTTP 200。成功、业务失败、参数校验失败或业务鉴权失败以响应体 code 区分。

Option 1
Option 2

成功响应。

code

enum<integer>

必填

0 表示订阅已创建，尚待客户激活。

可用选项:

0

message

string

必填

响应说明。

data

object

必填

已创建但尚未激活的 DDR。

Show child attributes