跳转到主要内容
POST

授权

Authorization
string
header
必填

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

请求体

application/json

向已激活且已绑定支付方式的 By agreement DDR 添加扣费计划,使用该 DDR 的支付方式。存在任何 Paused 扣费计划(包括 Deposit 押金)时须先恢复或取消;存在 Active 的非 Deposit 扣费计划时须待其结束或取消后再添加。非标准 RRULE 须同时提供 process_type=12、custom_cycle_type 及 custom_cycle。

merchant_id
string
必填

业务标识,由 BillBuddy 分配。

Required string length: 1 - 20
plan_id
string
必填

DDR 订阅 ID。

Required string length: 1 - 50
type
enum<integer>
必填

扣费计划类型:1 按成功期数;2 按累计金额;3 持续至取消;4 按结束日期;6 One-off。不允许 5 或 7。

可用选项:
1,
2,
3,
4,
6
amount
必填

单次或每期金额。 金额以主货币单位计,例如 10.50 表示 AUD 10.50,最多两位小数。接受数值或数字字符串,最小 0.01、最大 9999999.99,两种类型遵守相同范围限制。

必填范围: 0.01 <= x <= 9999999.99必须是以下数值的倍数 0.01
start_date
string<date>
必填

扣费计划起始日期 YYYY-MM-DD。不得早于 DDR 的起算日。可传过去日期;实际首次扣费不得早于服务业务时区的明天,并须符合 DDR 起算日及 RRULE 日期规则。

Minimum string length: 1
schedule_name
string | null

扣费计划名称。 省略时使用 DDR 的 plan_name。

Maximum string length: 255
total_amount

目标累计金额,以主货币单位计,最多两位小数,最小为 0.01,接受数值或数字字符串。type=2 时必填且不能为 null。服务按目标金额推算期数。

必填范围: x >= 0.01必须是以下数值的倍数 0.01
day_of_debit
string | null

RFC 5545 RRULE 扣费规则。type=1/2/3/4 时必填且不能为 null;type=6(一次性)可省略。频率写法见接入说明。

Maximum string length: 255
process_type
enum<integer> | null

仅自定义频率时传 12。其他频率由 RRULE 推断,请省略此字段。

可用选项:
12,
null
custom_cycle_type
enum<integer> | null

process_type=12 时必填。1 天、2 周、3 月、4 年;须与 RRULE 的 FREQ 对应。非 Custom 模式不得填写非空的自定义周期参数。 当 process_type 为 12 时必填,且不能为 null。

可用选项:
1,
2,
3,
4,
null
custom_cycle
integer | null

process_type=12 时必填,正整数且必须等于 RRULE 的 INTERVAL。以天为单位时最小 5,其他单位最小 1。 当 process_type 为 12 时必填,且不能为 null。

必填范围: x >= 1
day_of_debit_dtstart
string | null

首次扣费锚点。季度、半年、年度频率必填,推荐 YYYY-MM-DD;必须严格晚于对应 start_date,且在其后一个计费周期内(3/6/12 个月,按月底截断)。也支持 MM-DD,此时须为合法月日,不适用上述完整日期窗口限制。

Pattern: ^(\d{4}-)?\d{2}-\d{2}$
end_date
string<date> | null

结束日期,建议使用 YYYY-MM-DD。type=4 时必填且不能为 null;提供时不得早于同一段的 start_date。

end_terms
integer | null

成功扣费期数,正整数,最小为 1。type=1 时必填且不能为 null。

必填范围: x >= 1

响应

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

成功响应。

code
enum<integer>
必填

0 表示扣费计划创建成功,不表示已完成扣款。

可用选项:
0
message
string
必填

响应说明。

data
object
必填

新扣费计划。