curl -X POST "${BASE_URL}/api/v2/subscription/createDdr" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "merchant_id": "48290713",
  "subscription_number": "MEM-20300101-001",
  "customer": {
    "customer_id": "CUS48290713"
  },
  "plan": {
    "plan_name": "Usage based DDR",
    "recurring": {
      "recurring_type": 5,
      "schedule_name": "Authorisation",
      "start_date": "2030-01-10"
    }
  },
  "payment": {
    "type": 1,
    "accept_terms_of_service_at": 1893456000000,
    "accept_direct_debit_request_service_agreement_at": 1893456000000,
    "bank": {
      "bsb": "062-000",
      "account_no": "618472950",
      "account_name": "Emily Carter"
    }
  }
}'

{
  "code": 0,
  "message": "ok",
  "data": {
    "customer_id": "CUS48290713",
    "plan_id": "DDR73019482",
    "subscription_number": "MEM-20300101-001",
    "status": 1
  }
}

创建并激活 DDR

客户、订阅及支付方式

必须提供 merchant_id、subscription_number、customer、plan 和 payment。客户信息二选一：已有客户使用 customer.customer_id；新客户提供 firstName、lastName、emailAddress，不要同时填写已有客户标识。plan.plan_name 必填，且不支持模板。

plan.recurring 和 plan.one_off 至少提供一个非空段，本接口没有 enabled 开关。周期段均须提供 recurring_type、start_date、schedule_name；类型 1–4 还须提供 amount 和 day_of_debit。

recurring_type	结束条件	额外必填参数
1	按成功期数	`end_terms`
2	按累计金额	`total_amount`，且 `amount` 不得大于 `total_amount`
3	持续至取消	无额外结束条件
4	按结束日期	`end_date`，不得早于该段的 `start_date`
5	By agreement 授权	无须金额或频率；后续通过 `createSchedule` 添加扣费计划

非空一次性段须提供 schedule_name、amount、payment_date。起始或付款日期至少为业务时区的明天。季度、半年、年度及自定义频率的附加要求见字段说明。

payment.type	支付信息	协议时间
1，银行账户	`payment.bank.bsb`、`payment.bank.account_no`、`payment.bank.account_name`	`accept_terms_of_service_at`、`accept_direct_debit_request_service_agreement_at`
2，信用卡	`payment.card.card_number`、`payment.card.expiration_month`、`payment.card.expiration_year`、`payment.card.security_code`、`payment.card.name_on_card`	`accept_terms_of_service_at`

按 payment.type 选择对应的银行账户或信用卡信息，建议仅提交所选类型的对象；另一类型的对象不用于本次绑定，但其中已提交的字段仍须符合字段校验。所有协议时间均位于 payment 内，具体类型及字段限制见请求参数。

由商户服务端代客户提交支付方式及协议接受时间，创建成功后 status=1 Active。支持周期类型 1/2/3/4、By agreement（5）、纯 one_off，以及周期与一次性组合。不支持模板或 3DS，不提供激活链接。By agreement 仅完成扣款授权，需调用 createSchedule 添加扣费计划。subscription_number 在同一商户及业务范围内唯一。创建失败时，data.customer_id 可能返回已创建的客户标识，重试时应复用该标识。

若失败响应中 data.customer_id 有值，该客户已创建；重试时请通过 customer.customer_id 复用该客户，避免重复创建。错误 message 会因失败原因不同而变化。

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

POST

api

subscription

createDdr

curl -X POST "${BASE_URL}/api/v2/subscription/createDdr" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "merchant_id": "48290713",
  "subscription_number": "MEM-20300101-001",
  "customer": {
    "customer_id": "CUS48290713"
  },
  "plan": {
    "plan_name": "Usage based DDR",
    "recurring": {
      "recurring_type": 5,
      "schedule_name": "Authorisation",
      "start_date": "2030-01-10"
    }
  },
  "payment": {
    "type": 1,
    "accept_terms_of_service_at": 1893456000000,
    "accept_direct_debit_request_service_agreement_at": 1893456000000,
    "bank": {
      "bsb": "062-000",
      "account_no": "618472950",
      "account_name": "Emily Carter"
    }
  }
}'

{
  "code": 0,
  "message": "ok",
  "data": {
    "customer_id": "CUS48290713",
    "plan_id": "DDR73019482",
    "subscription_number": "MEM-20300101-001",
    "status": 1
  }
}

授权

Authorization

string

header

必填

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

请求体

application/json

通过商户服务端创建并立即激活 DDR。customer 为已有客户或新客户信息二选一。plan.recurring 与 plan.one_off 至少一段非空；不支持模板。recurring_type=5 仅创建 By agreement 扣款授权；1/2/3/4 创建周期扣费计划；one_off 单独使用为一次性，配合 recurring 为押金。payment 必填，不支持 3DS。币种固定 AUD。

merchant_id

string

必填

业务标识，由 BillBuddy 分配。

Required string length: 1 - 20

subscription_number

string

必填

商户订阅编号。同一商户及业务范围内唯一，已使用的编号不可重复使用；重复请求会失败，不会返回已有订阅。

Required string length: 1 - 64

customer

object

必填

客户信息。已有客户标识与新客户资料二选一。

Show child attributes

plan

object

必填

DDR 订阅定义，包含订阅名称、扣费规则及费用选项。

Show child attributes

payment

object

必填

创建并激活时使用的支付方式和协议接受时间。 card/bank 的可提交字段以各自 Schema 为准。

Show child attributes

notify_email

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

notify_sms

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

响应

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

Option 1
Option 2

成功响应。

code

enum<integer>

必填

0 表示 DDR 已创建并激活，不表示已完成扣款。

可用选项:

0

message

string

必填

响应说明。

data

object

必填

已激活 DDR，无托管激活链接。

Show child attributes