> ## Documentation Index > Fetch the complete documentation index at: https://docs.billbuddyhq.com/llms.txt > Use this file to discover all available pages before exploring further. # 创建并激活 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 年，执行时请改为满足当前日期限制的实际日期。 ## OpenAPI ````yaml /openapi/billbuddy-v2-openapi.yaml post /api/v2/subscription/createDdr openapi: 3.0.3 info: title: BillBuddy API 接入文档 version: 2.0.0 description: > BillBuddy API 接入文档，本文收录第三方服务端主动调用的认证、交易和订阅接口。请求与响应示例均使用完整但虚构的业务数据及离线生成的演示令牌，不能用于实际认证或交易。 ## 接入步骤 1. 向 BillBuddy 获取 Client ID、Client Secret、商户标识及业务标识。如启用 IP 白名单，请使用已获准的固定出口 IP 调用。 2. 通过 POST /oauth/token 获取 access_token。业务请求携带 Authorization: Bearer {access_token} 和 Accept: application/json。JSON 请求使用 Content-Type: application/json；获取令牌使用表单。 3. 按需调用支付或订阅接口。客户通过 activation_url 打开托管激活页；Client Secret 仅可保存在商户服务端。 ## 标识及金额 商户身份由 OAuth 凭据确定，无需在请求中传 business_id。需要指定业务的接口使用 merchant_id；单笔交易查询和批次结果查询的 merchant_id 可选，省略或为空时在当前商户全部业务范围内查询；交易列表使用可选的 Mid（区分大小写），省略时查询当前商户的全部业务。业务标识必须属于凭据所属商户。响应中的标识请按各接口字段说明读取。 除 TXT 批量上传文件及其 amount_cents/declared_total_amount_cents 使用分外，金额使用主货币单位，最多两位小数，例如 10.50 表示 AUD 10.50。银行账号、卡号、月份、年份和邮编建议使用字符串，以保留前导零。 ## 成功和失败 业务 JSON 成功 code=0，常规失败 code=1。交易及订阅业务接口参数校验失败通常为 code=400、data={}，HTTP 状态仍为 200。V2 业务接口认证失败为 code=1，plan/list 标识业务校验失败为 code=1。HTTP 429 表示请求超过频率限制。OAuth 端点采用标准 OAuth 响应（HTTP 200/400/401/429）。 code=0 表示接口处理成功，扣款结果须另行判断：批量 accepted 仅表示请求已受理，将异步处理；银行 Pending、预约 Pending 和 3DS 待验证均不代表支付成功。交易、DDR 订阅和扣费计划各自使用不同的 status 枚举，请参阅对应字段说明。 ## 日期及频率 请求日期建议使用 YYYY-MM-DD。今天及明天均按服务业务时区 Australia/Sydney 计算（适用夏令时）；预约取消时间以 Australia/Sydney 为准（适用夏令时），仅允许在处理日 08:15 之前取消，到达该时刻即不可取消。支付 complete_date 与收银台 expires_at 使用 DD/MM/YYYY HH:mm:ss，其他时间格式见字段说明。 RRULE 标准示例：Daily FREQ=DAILY;INTERVAL=1；Weekly FREQ=WEEKLY;INTERVAL=1;BYDAY=MO；Fortnightly FREQ=WEEKLY;INTERVAL=2;BYDAY=MO；Monthly FREQ=MONTHLY;INTERVAL=1;BYMONTHDAY=15；Quarterly FREQ=MONTHLY;INTERVAL=3;BYMONTHDAY=15；Half Yearly FREQ=MONTHLY;INTERVAL=6;BYMONTHDAY=15；Yearly FREQ=YEARLY;INTERVAL=1;BYMONTH=2;BYMONTHDAY=15。星期缩写为 MO/TU/WE/TH/FR/SA/SU。Weekly/Monthly 省略具体扣费日时按起算日确定；单一 BYDAY=SA 或 SU 按周一处理，未指定具体日期且起算日在周末时也按周一处理。单值 BYMONTHDAY=29/30/31 在短月按月末处理；BYMONTHDAY=-1 表示月底。所有规则须符合有效 RRULE 格式。 非标准频率（如每 10 天）须同时传 process_type=12、custom_cycle_type=1、custom_cycle=10，且 day_of_debit=FREQ=DAILY;INTERVAL=10。单位 1/2/3/4 对应 DAILY/WEEKLY/MONTHLY/YEARLY，以天为单位时间隔最小为 5，其余单位最小为 1，INTERVAL 须等于 custom_cycle。季度、半年及年度还须提供 day_of_debit_dtstart；完整日期须严格晚于同段 start_date，并在其后一个计费周期内。createSchedule 的实际首次扣费日期由 DDR 起算日、扣费频率及最早明天的限制共同确定。 ## 使用示例 参数类型、可空、长度、枚举及数值范围见 Schema；条件必填、日期及业务限制见字段 description。请结合两者使用。curl 示例中的 BASE_URL、ACCESS_TOKEN、CLIENT_ID 和 CLIENT_SECRET 需由调用方设置；实际测试或生产域名由 BillBuddy 提供。示例中的客户、订单、卡号、账户及日期须替换为测试环境允许使用且满足日期限制的数据。 ## 托管订阅接入 调用 POST /api/v2/subscription/create 创建订阅，取得 activation_url 后原样用于浏览器跳转或 iframe 的 src；也可将 activation_html 用作 iframe 的 srcdoc。客户在 BillBuddy 提供的页面填写支付信息并完成授权和激活。请使用返回的完整链接，无需自行拼接地址或解析链接中的凭证。Client Secret 和 access_token 仅保存在商户服务端，不得放入 iframe 地址或页面内容。 周期订阅及 By agreement 须在 start_date 当天之前激活；纯一次性订阅须在创建后 30 天内提交激活。页面可以打开不保证仍可提交，以激活接口结果为准。 ## 示例数据约定 示例中的商户、客户、订单、支付 Token、会话链接和 OAuth 凭据均为虚构，不能用于真实调用。银行卡使用标准测试卡号；银行账户为虚构账户；邮箱使用 example.com 保留域名，电话号码使用澳大利亚保留的演示号码。请求中的 BASE_URL、ACCESS_TOKEN、CLIENT_ID 和 CLIENT_SECRET 仍需替换为获准测试环境的实际值。示例中必要的空字符串、null、空数组、0 和 false 表示实际接口状态，不能统一替换为非空值。 支付响应的 sign 按各支付场景的签名规则，使用公开演示密钥 bb_docs_demo_signing_key_2030 离线计算。3DS 待验证响应的 html 不参与签名计算。该密钥仅用于文档，不能用于实际签名或认证。 ## TXT 批量交易 使用 multipart/form-data 上传固定宽度 TXT 文件。文件金额及 amount_cents、declared_total_amount_cents 均以分计，不含附加费；文件格式和示例文件见“上传 TXT 批量交易文件”。上传成功仅表示已接收，请保存 batch_id 和 file_identifier，并使用批次结果接口查询逐笔状态。批次 completed 不代表所有支付成功。查询结果须使用同一商户的 OAuth 凭据；merchant_id 可省略，如传入则须与原上传请求的业务标识一致。响应字段含义以对应接口说明为准。 ## 开发语言请求示例 请求示例提供 cURL、Python、JavaScript、PHP、Go、Java 和 Ruby，同一语言下可切换各业务场景。各语言使用与 cURL 对应场景相同的请求参数和类型。 运行环境：cURL；Python 3.9+（标准库）；JavaScript 使用 Node.js 18+，保存为 .mjs 后运行；PHP 8+ 并启用 cURL 扩展；Go 1.20+；Java 11+（示例类名为 Example，保存为 Example.java）；Ruby 3+（标准库）。 运行前设置 BASE_URL；业务接口还需设置 ACCESS_TOKEN，获取令牌需设置 CLIENT_ID 和 CLIENT_SECRET。BASE_URL 使用 API 根地址，不附加 /api/v2。TXT 上传示例从当前目录读取 payments.txt。请先替换为获准测试数据，并结合响应 code 和业务状态判断结果。 servers: - url: https://staging-api.billbuddyhq.com description: Staging 测试环境 security: - oauth2: [] tags: - name: 认证 description: OAuth2 Client Credentials。 - name: 交易 description: 单笔、批量与预约取消。 - name: 订阅 description: 订阅模板、创建订阅、创建并激活 DDR 及推送扣费计划。 paths: /api/v2/subscription/createDdr: post: tags: - 订阅 summary: 创建并激活 DDR description: >- ### 客户、订阅及支付方式 必须提供 `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 年，执行时请改为满足当前日期限制的实际日期。 operationId: v2CreateDdr requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DdrCreateRequest' examples: baBank: summary: 银行账户 By agreement 授权 value: 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 recurringCard: summary: 信用卡周期 DDR value: merchant_id: '48290713' subscription_number: MEM-20300101-002 customer: customer_id: CUS48290713 plan: plan_name: Monthly membership recurring: schedule_name: Monthly fee recurring_type: 3 amount: '25.50' start_date: '2030-01-10' day_of_debit: FREQ=MONTHLY;INTERVAL=1;BYMONTHDAY=15 payment: type: 2 accept_terms_of_service_at: 1893456000000 card: card_number: '4111111111111111' expiration_month: '12' expiration_year: '2030' security_code: '123' name_on_card: Emily Carter email: emily.carter@example.com oneOff: summary: 纯一次性 DDR value: merchant_id: '48290713' subscription_number: MEM-20300101-003 customer: customer_id: CUS48290713 plan: plan_name: One time fee one_off: schedule_name: Initial fee amount: '20.00' payment_date: '2030-01-15' 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 responses: '200': description: HTTP 200。成功、业务失败、参数校验失败或业务鉴权失败以响应体 code 区分。 content: application/json: schema: oneOf: - $ref: '#/components/schemas/DdrCreateResponse' - $ref: '#/components/schemas/BusinessError' examples: success: summary: 激活成功 value: code: 0 message: ok data: customer_id: CUS48290713 plan_id: DDR73019482 subscription_number: MEM-20300101-001 status: 1 duplicate: summary: 编号已存在 value: code: 1 message: The subscription number already exists data: [] validation: summary: 参数错误 value: code: 400 message: The payment field is required. data: {} customerCreatedButDdrFailed: summary: DDR 创建失败，但客户已创建；重试时复用 customer_id value: code: 1 message: DDR create failed due to internal error data: customer_id: CUS48290714 '429': description: >- 请求超过频率限制。API 请求共享每分钟 120 次的限额，通常按请求来源 IP 计数，并非每个接口单独 120 次。请遵循 Retry-After 指定的等待秒数。 headers: Retry-After: description: 再次请求前应等待的秒数。 schema: type: integer content: application/json: schema: type: object description: 请求频率超限响应。 properties: message: type: string description: 限流提示。 example: message: Too Many Attempts. security: - oauth2: [] x-codeSamples: - lang: Shell label: 银行账户 By agreement 授权 source: |- 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" } } }' - lang: Shell label: 信用卡周期 DDR source: |- 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-002", "customer": { "customer_id": "CUS48290713" }, "plan": { "plan_name": "Monthly membership", "recurring": { "schedule_name": "Monthly fee", "recurring_type": 3, "amount": "25.50", "start_date": "2030-01-10", "day_of_debit": "FREQ=MONTHLY;INTERVAL=1;BYMONTHDAY=15" } }, "payment": { "type": 2, "accept_terms_of_service_at": 1893456000000, "card": { "card_number": "4111111111111111", "expiration_month": "12", "expiration_year": "2030", "security_code": "123", "name_on_card": "Emily Carter", "email": "emily.carter@example.com" } } }' - lang: Shell label: 纯一次性 DDR source: |- 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-003", "customer": { "customer_id": "CUS48290713" }, "plan": { "plan_name": "One time fee", "one_off": { "schedule_name": "Initial fee", "amount": "20.00", "payment_date": "2030-01-15" } }, "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" } } }' - lang: Python label: 银行账户 By agreement 授权 source: > import json import os import urllib.parse import urllib.request base_url = os.environ["BASE_URL"].rstrip("/") url = base_url + "/api/v2/subscription/createDdr" headers = {"Accept": "application/json"} headers["Authorization"] = "Bearer " + os.environ["ACCESS_TOKEN"] payload = json.loads(r'''{ "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" } } }''') body = json.dumps(payload).encode("utf-8") headers["Content-Type"] = "application/json" request = urllib.request.Request(url, data=body, headers=headers, method="POST") with urllib.request.urlopen(request, timeout=30) as response: print(response.read().decode("utf-8")) - lang: Python label: 信用卡周期 DDR source: > import json import os import urllib.parse import urllib.request base_url = os.environ["BASE_URL"].rstrip("/") url = base_url + "/api/v2/subscription/createDdr" headers = {"Accept": "application/json"} headers["Authorization"] = "Bearer " + os.environ["ACCESS_TOKEN"] payload = json.loads(r'''{ "merchant_id": "48290713", "subscription_number": "MEM-20300101-002", "customer": { "customer_id": "CUS48290713" }, "plan": { "plan_name": "Monthly membership", "recurring": { "schedule_name": "Monthly fee", "recurring_type": 3, "amount": "25.50", "start_date": "2030-01-10", "day_of_debit": "FREQ=MONTHLY;INTERVAL=1;BYMONTHDAY=15" } }, "payment": { "type": 2, "accept_terms_of_service_at": 1893456000000, "card": { "card_number": "4111111111111111", "expiration_month": "12", "expiration_year": "2030", "security_code": "123", "name_on_card": "Emily Carter", "email": "emily.carter@example.com" } } }''') body = json.dumps(payload).encode("utf-8") headers["Content-Type"] = "application/json" request = urllib.request.Request(url, data=body, headers=headers, method="POST") with urllib.request.urlopen(request, timeout=30) as response: print(response.read().decode("utf-8")) - lang: Python label: 纯一次性 DDR source: > import json import os import urllib.parse import urllib.request base_url = os.environ["BASE_URL"].rstrip("/") url = base_url + "/api/v2/subscription/createDdr" headers = {"Accept": "application/json"} headers["Authorization"] = "Bearer " + os.environ["ACCESS_TOKEN"] payload = json.loads(r'''{ "merchant_id": "48290713", "subscription_number": "MEM-20300101-003", "customer": { "customer_id": "CUS48290713" }, "plan": { "plan_name": "One time fee", "one_off": { "schedule_name": "Initial fee", "amount": "20.00", "payment_date": "2030-01-15" } }, "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" } } }''') body = json.dumps(payload).encode("utf-8") headers["Content-Type"] = "application/json" request = urllib.request.Request(url, data=body, headers=headers, method="POST") with urllib.request.urlopen(request, timeout=30) as response: print(response.read().decode("utf-8")) - lang: JavaScript label: 银行账户 By agreement 授权 source: | const env = (name) => { const value = process.env[name]; if (!value) throw new Error(`Missing environment variable: ${name}`); return value; }; const baseUrl = env("BASE_URL").replace(/\/+$/, ""); const url = new URL(baseUrl + "/api/v2/subscription/createDdr"); const headers = { Accept: "application/json" }; headers.Authorization = `Bearer ${env("ACCESS_TOKEN")}`; const payload = { "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" } } }; const body = JSON.stringify(payload); headers["Content-Type"] = "application/json"; const response = await fetch(url, { method: "POST", headers, body, signal: AbortSignal.timeout(30_000), }); console.log(await response.text()); - lang: JavaScript label: 信用卡周期 DDR source: | const env = (name) => { const value = process.env[name]; if (!value) throw new Error(`Missing environment variable: ${name}`); return value; }; const baseUrl = env("BASE_URL").replace(/\/+$/, ""); const url = new URL(baseUrl + "/api/v2/subscription/createDdr"); const headers = { Accept: "application/json" }; headers.Authorization = `Bearer ${env("ACCESS_TOKEN")}`; const payload = { "merchant_id": "48290713", "subscription_number": "MEM-20300101-002", "customer": { "customer_id": "CUS48290713" }, "plan": { "plan_name": "Monthly membership", "recurring": { "schedule_name": "Monthly fee", "recurring_type": 3, "amount": "25.50", "start_date": "2030-01-10", "day_of_debit": "FREQ=MONTHLY;INTERVAL=1;BYMONTHDAY=15" } }, "payment": { "type": 2, "accept_terms_of_service_at": 1893456000000, "card": { "card_number": "4111111111111111", "expiration_month": "12", "expiration_year": "2030", "security_code": "123", "name_on_card": "Emily Carter", "email": "emily.carter@example.com" } } }; const body = JSON.stringify(payload); headers["Content-Type"] = "application/json"; const response = await fetch(url, { method: "POST", headers, body, signal: AbortSignal.timeout(30_000), }); console.log(await response.text()); - lang: JavaScript label: 纯一次性 DDR source: | const env = (name) => { const value = process.env[name]; if (!value) throw new Error(`Missing environment variable: ${name}`); return value; }; const baseUrl = env("BASE_URL").replace(/\/+$/, ""); const url = new URL(baseUrl + "/api/v2/subscription/createDdr"); const headers = { Accept: "application/json" }; headers.Authorization = `Bearer ${env("ACCESS_TOKEN")}`; const payload = { "merchant_id": "48290713", "subscription_number": "MEM-20300101-003", "customer": { "customer_id": "CUS48290713" }, "plan": { "plan_name": "One time fee", "one_off": { "schedule_name": "Initial fee", "amount": "20.00", "payment_date": "2030-01-15" } }, "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" } } }; const body = JSON.stringify(payload); headers["Content-Type"] = "application/json"; const response = await fetch(url, { method: "POST", headers, body, signal: AbortSignal.timeout(30_000), }); console.log(await response.text()); - lang: PHP label: 银行账户 By agreement 授权 source: | "POST", CURLOPT_HTTPHEADER => $headers, CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30, CURLOPT_POSTFIELDS => $body, ]); $response = curl_exec($curl); if ($response === false) { $error = curl_error($curl); curl_close($curl); throw new RuntimeException($error); } curl_close($curl); echo $response, PHP_EOL; - lang: PHP label: 信用卡周期 DDR source: | "POST", CURLOPT_HTTPHEADER => $headers, CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30, CURLOPT_POSTFIELDS => $body, ]); $response = curl_exec($curl); if ($response === false) { $error = curl_error($curl); curl_close($curl); throw new RuntimeException($error); } curl_close($curl); echo $response, PHP_EOL; - lang: PHP label: 纯一次性 DDR source: | "POST", CURLOPT_HTTPHEADER => $headers, CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30, CURLOPT_POSTFIELDS => $body, ]); $response = curl_exec($curl); if ($response === false) { $error = curl_error($curl); curl_close($curl); throw new RuntimeException($error); } curl_close($curl); echo $response, PHP_EOL; - lang: Go label: 银行账户 By agreement 授权 source: | package main import ( "fmt" "io" "net/http" "os" "strings" "time" ) func mustEnv(name string) string { value := os.Getenv(name) if value == "" { panic("Missing environment variable: " + name) } return value } func main() { baseURL := strings.TrimRight(mustEnv("BASE_URL"), "/") endpoint := baseURL + "/api/v2/subscription/createDdr" payload := `{ "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" } } }` body := strings.NewReader(payload) req, err := http.NewRequest("POST", endpoint, body) if err != nil { panic(err) } req.Header.Set("Accept", "application/json") req.Header.Set("Authorization", "Bearer " + mustEnv("ACCESS_TOKEN")) req.Header.Set("Content-Type", "application/json") client := &http.Client{Timeout: 30 * time.Second} response, err := client.Do(req) if err != nil { panic(err) } defer response.Body.Close() result, err := io.ReadAll(response.Body) if err != nil { panic(err) } fmt.Println(string(result)) } - lang: Go label: 信用卡周期 DDR source: | package main import ( "fmt" "io" "net/http" "os" "strings" "time" ) func mustEnv(name string) string { value := os.Getenv(name) if value == "" { panic("Missing environment variable: " + name) } return value } func main() { baseURL := strings.TrimRight(mustEnv("BASE_URL"), "/") endpoint := baseURL + "/api/v2/subscription/createDdr" payload := `{ "merchant_id": "48290713", "subscription_number": "MEM-20300101-002", "customer": { "customer_id": "CUS48290713" }, "plan": { "plan_name": "Monthly membership", "recurring": { "schedule_name": "Monthly fee", "recurring_type": 3, "amount": "25.50", "start_date": "2030-01-10", "day_of_debit": "FREQ=MONTHLY;INTERVAL=1;BYMONTHDAY=15" } }, "payment": { "type": 2, "accept_terms_of_service_at": 1893456000000, "card": { "card_number": "4111111111111111", "expiration_month": "12", "expiration_year": "2030", "security_code": "123", "name_on_card": "Emily Carter", "email": "emily.carter@example.com" } } }` body := strings.NewReader(payload) req, err := http.NewRequest("POST", endpoint, body) if err != nil { panic(err) } req.Header.Set("Accept", "application/json") req.Header.Set("Authorization", "Bearer " + mustEnv("ACCESS_TOKEN")) req.Header.Set("Content-Type", "application/json") client := &http.Client{Timeout: 30 * time.Second} response, err := client.Do(req) if err != nil { panic(err) } defer response.Body.Close() result, err := io.ReadAll(response.Body) if err != nil { panic(err) } fmt.Println(string(result)) } - lang: Go label: 纯一次性 DDR source: | package main import ( "fmt" "io" "net/http" "os" "strings" "time" ) func mustEnv(name string) string { value := os.Getenv(name) if value == "" { panic("Missing environment variable: " + name) } return value } func main() { baseURL := strings.TrimRight(mustEnv("BASE_URL"), "/") endpoint := baseURL + "/api/v2/subscription/createDdr" payload := `{ "merchant_id": "48290713", "subscription_number": "MEM-20300101-003", "customer": { "customer_id": "CUS48290713" }, "plan": { "plan_name": "One time fee", "one_off": { "schedule_name": "Initial fee", "amount": "20.00", "payment_date": "2030-01-15" } }, "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" } } }` body := strings.NewReader(payload) req, err := http.NewRequest("POST", endpoint, body) if err != nil { panic(err) } req.Header.Set("Accept", "application/json") req.Header.Set("Authorization", "Bearer " + mustEnv("ACCESS_TOKEN")) req.Header.Set("Content-Type", "application/json") client := &http.Client{Timeout: 30 * time.Second} response, err := client.Do(req) if err != nil { panic(err) } defer response.Body.Close() result, err := io.ReadAll(response.Body) if err != nil { panic(err) } fmt.Println(string(result)) } - lang: Java label: 银行账户 By agreement 授权 source: | import java.io.ByteArrayOutputStream; import java.net.URI; import java.net.URLEncoder; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.nio.charset.StandardCharsets; import java.nio.file.Files; import java.nio.file.Path; import java.time.Duration; import java.util.LinkedHashMap; import java.util.Map; import java.util.UUID; import java.util.stream.Collectors; public class Example { static String requireEnv(String name) { String value = System.getenv(name); if (value == null || value.isEmpty()) { throw new IllegalArgumentException("Missing environment variable: " + name); } return value; } public static void main(String[] args) throws Exception { String baseUrl = requireEnv("BASE_URL").replaceAll("/+$", ""); String endpoint = baseUrl + "/api/v2/subscription/createDdr"; String payload = "{\n" + " \"merchant_id\": \"48290713\",\n" + " \"subscription_number\": \"MEM-20300101-001\",\n" + " \"customer\": {\n" + " \"customer_id\": \"CUS48290713\"\n" + " },\n" + " \"plan\": {\n" + " \"plan_name\": \"Usage based DDR\",\n" + " \"recurring\": {\n" + " \"recurring_type\": 5,\n" + " \"schedule_name\": \"Authorisation\",\n" + " \"start_date\": \"2030-01-10\"\n" + " }\n" + " },\n" + " \"payment\": {\n" + " \"type\": 1,\n" + " \"accept_terms_of_service_at\": 1893456000000,\n" + " \"accept_direct_debit_request_service_agreement_at\": 1893456000000,\n" + " \"bank\": {\n" + " \"bsb\": \"062-000\",\n" + " \"account_no\": \"618472950\",\n" + " \"account_name\": \"Emily Carter\"\n" + " }\n" + " }\n" + "}"; HttpRequest.Builder builder = HttpRequest.newBuilder(URI.create(endpoint)) .timeout(Duration.ofSeconds(30)) .header("Accept", "application/json"); builder.header("Authorization", "Bearer " + requireEnv("ACCESS_TOKEN")); builder.header("Content-Type", "application/json"); HttpRequest request = builder.method("POST", HttpRequest.BodyPublishers.ofString(payload, StandardCharsets.UTF_8)).build(); HttpClient client = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(30)).build(); HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8)); System.out.println(response.body()); } } - lang: Java label: 信用卡周期 DDR source: | import java.io.ByteArrayOutputStream; import java.net.URI; import java.net.URLEncoder; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.nio.charset.StandardCharsets; import java.nio.file.Files; import java.nio.file.Path; import java.time.Duration; import java.util.LinkedHashMap; import java.util.Map; import java.util.UUID; import java.util.stream.Collectors; public class Example { static String requireEnv(String name) { String value = System.getenv(name); if (value == null || value.isEmpty()) { throw new IllegalArgumentException("Missing environment variable: " + name); } return value; } public static void main(String[] args) throws Exception { String baseUrl = requireEnv("BASE_URL").replaceAll("/+$", ""); String endpoint = baseUrl + "/api/v2/subscription/createDdr"; String payload = "{\n" + " \"merchant_id\": \"48290713\",\n" + " \"subscription_number\": \"MEM-20300101-002\",\n" + " \"customer\": {\n" + " \"customer_id\": \"CUS48290713\"\n" + " },\n" + " \"plan\": {\n" + " \"plan_name\": \"Monthly membership\",\n" + " \"recurring\": {\n" + " \"schedule_name\": \"Monthly fee\",\n" + " \"recurring_type\": 3,\n" + " \"amount\": \"25.50\",\n" + " \"start_date\": \"2030-01-10\",\n" + " \"day_of_debit\": \"FREQ=MONTHLY;INTERVAL=1;BYMONTHDAY=15\"\n" + " }\n" + " },\n" + " \"payment\": {\n" + " \"type\": 2,\n" + " \"accept_terms_of_service_at\": 1893456000000,\n" + " \"card\": {\n" + " \"card_number\": \"4111111111111111\",\n" + " \"expiration_month\": \"12\",\n" + " \"expiration_year\": \"2030\",\n" + " \"security_code\": \"123\",\n" + " \"name_on_card\": \"Emily Carter\",\n" + " \"email\": \"emily.carter@example.com\"\n" + " }\n" + " }\n" + "}"; HttpRequest.Builder builder = HttpRequest.newBuilder(URI.create(endpoint)) .timeout(Duration.ofSeconds(30)) .header("Accept", "application/json"); builder.header("Authorization", "Bearer " + requireEnv("ACCESS_TOKEN")); builder.header("Content-Type", "application/json"); HttpRequest request = builder.method("POST", HttpRequest.BodyPublishers.ofString(payload, StandardCharsets.UTF_8)).build(); HttpClient client = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(30)).build(); HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8)); System.out.println(response.body()); } } - lang: Java label: 纯一次性 DDR source: | import java.io.ByteArrayOutputStream; import java.net.URI; import java.net.URLEncoder; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.nio.charset.StandardCharsets; import java.nio.file.Files; import java.nio.file.Path; import java.time.Duration; import java.util.LinkedHashMap; import java.util.Map; import java.util.UUID; import java.util.stream.Collectors; public class Example { static String requireEnv(String name) { String value = System.getenv(name); if (value == null || value.isEmpty()) { throw new IllegalArgumentException("Missing environment variable: " + name); } return value; } public static void main(String[] args) throws Exception { String baseUrl = requireEnv("BASE_URL").replaceAll("/+$", ""); String endpoint = baseUrl + "/api/v2/subscription/createDdr"; String payload = "{\n" + " \"merchant_id\": \"48290713\",\n" + " \"subscription_number\": \"MEM-20300101-003\",\n" + " \"customer\": {\n" + " \"customer_id\": \"CUS48290713\"\n" + " },\n" + " \"plan\": {\n" + " \"plan_name\": \"One time fee\",\n" + " \"one_off\": {\n" + " \"schedule_name\": \"Initial fee\",\n" + " \"amount\": \"20.00\",\n" + " \"payment_date\": \"2030-01-15\"\n" + " }\n" + " },\n" + " \"payment\": {\n" + " \"type\": 1,\n" + " \"accept_terms_of_service_at\": 1893456000000,\n" + " \"accept_direct_debit_request_service_agreement_at\": 1893456000000,\n" + " \"bank\": {\n" + " \"bsb\": \"062-000\",\n" + " \"account_no\": \"618472950\",\n" + " \"account_name\": \"Emily Carter\"\n" + " }\n" + " }\n" + "}"; HttpRequest.Builder builder = HttpRequest.newBuilder(URI.create(endpoint)) .timeout(Duration.ofSeconds(30)) .header("Accept", "application/json"); builder.header("Authorization", "Bearer " + requireEnv("ACCESS_TOKEN")); builder.header("Content-Type", "application/json"); HttpRequest request = builder.method("POST", HttpRequest.BodyPublishers.ofString(payload, StandardCharsets.UTF_8)).build(); HttpClient client = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(30)).build(); HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8)); System.out.println(response.body()); } } - lang: Ruby label: 银行账户 By agreement 授权 source: | require "net/http" require "uri" base_url = ENV.fetch("BASE_URL").sub(%r{/+$}, "") uri = URI(base_url + "/api/v2/subscription/createDdr") request = Net::HTTP::Post.new(uri) request["Accept"] = "application/json" request["Authorization"] = "Bearer " + ENV.fetch("ACCESS_TOKEN") request["Content-Type"] = "application/json" request.body = <<~'JSON' { "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" } } } JSON http = Net::HTTP.new(uri.host, uri.port) http.use_ssl = uri.scheme == "https" http.open_timeout = 30 http.read_timeout = 30 puts http.request(request).body - lang: Ruby label: 信用卡周期 DDR source: | require "net/http" require "uri" base_url = ENV.fetch("BASE_URL").sub(%r{/+$}, "") uri = URI(base_url + "/api/v2/subscription/createDdr") request = Net::HTTP::Post.new(uri) request["Accept"] = "application/json" request["Authorization"] = "Bearer " + ENV.fetch("ACCESS_TOKEN") request["Content-Type"] = "application/json" request.body = <<~'JSON' { "merchant_id": "48290713", "subscription_number": "MEM-20300101-002", "customer": { "customer_id": "CUS48290713" }, "plan": { "plan_name": "Monthly membership", "recurring": { "schedule_name": "Monthly fee", "recurring_type": 3, "amount": "25.50", "start_date": "2030-01-10", "day_of_debit": "FREQ=MONTHLY;INTERVAL=1;BYMONTHDAY=15" } }, "payment": { "type": 2, "accept_terms_of_service_at": 1893456000000, "card": { "card_number": "4111111111111111", "expiration_month": "12", "expiration_year": "2030", "security_code": "123", "name_on_card": "Emily Carter", "email": "emily.carter@example.com" } } } JSON http = Net::HTTP.new(uri.host, uri.port) http.use_ssl = uri.scheme == "https" http.open_timeout = 30 http.read_timeout = 30 puts http.request(request).body - lang: Ruby label: 纯一次性 DDR source: | require "net/http" require "uri" base_url = ENV.fetch("BASE_URL").sub(%r{/+$}, "") uri = URI(base_url + "/api/v2/subscription/createDdr") request = Net::HTTP::Post.new(uri) request["Accept"] = "application/json" request["Authorization"] = "Bearer " + ENV.fetch("ACCESS_TOKEN") request["Content-Type"] = "application/json" request.body = <<~'JSON' { "merchant_id": "48290713", "subscription_number": "MEM-20300101-003", "customer": { "customer_id": "CUS48290713" }, "plan": { "plan_name": "One time fee", "one_off": { "schedule_name": "Initial fee", "amount": "20.00", "payment_date": "2030-01-15" } }, "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" } } } JSON http = Net::HTTP.new(uri.host, uri.port) http.use_ssl = uri.scheme == "https" http.open_timeout = 30 http.read_timeout = 30 puts http.request(request).body components: schemas: DdrCreateRequest: type: object description: >- 通过商户服务端创建并立即激活 DDR。customer 为已有客户或新客户信息二选一。plan.recurring 与 plan.one_off 至少一段非空；不支持模板。recurring_type=5 仅创建 By agreement 扣款授权；1/2/3/4 创建周期扣费计划；one_off 单独使用为一次性，配合 recurring 为押金。payment 必填，不支持 3DS。币种固定 AUD。 properties: merchant_id: type: string description: 业务标识，由 BillBuddy 分配。 maxLength: 20 minLength: 1 subscription_number: type: string description: 商户订阅编号。同一商户及业务范围内唯一，已使用的编号不可重复使用；重复请求会失败，不会返回已有订阅。 maxLength: 64 minLength: 1 customer: type: object properties: customer_id: type: string description: BillBuddy 客户标识，须为当前商户及业务范围内的有效客户。 nullable: true maxLength: 32 firstName: type: string description: 新客户名字。创建新客户时必填。 nullable: true maxLength: 100 lastName: type: string description: 新客户姓氏。创建新客户时必填。 nullable: true maxLength: 100 emailAddress: type: string description: 新客户主邮箱。创建新客户时必填；同一商户及业务范围内已有此邮箱时请改传已有 customer_id。 nullable: true format: email maxLength: 500 mobilePhoneNumber: type: string description: 客户手机号。 nullable: true maxLength: 20 addressLine1: type: string description: 客户地址第一行。 nullable: true maxLength: 255 addressSuburb: type: string description: 客户城市或区。 nullable: true maxLength: 100 addressState: type: string description: 客户州或省。 nullable: true maxLength: 100 addressPostCode: type: string description: 客户邮编。 nullable: true maxLength: 50 description: 客户信息。已有客户标识与新客户资料二选一。 not: anyOf: - not: oneOf: - allOf: - type: object required: - customer_id properties: customer_id: type: string minLength: 1 pattern: \S - not: anyOf: - type: object required: - firstName properties: firstName: type: string minLength: 1 pattern: \S - type: object required: - lastName properties: lastName: type: string minLength: 1 pattern: \S - type: object required: - emailAddress properties: emailAddress: type: string minLength: 1 pattern: \S - allOf: - not: type: object required: - customer_id properties: customer_id: type: string minLength: 1 pattern: \S - type: object required: - firstName properties: firstName: type: string minLength: 1 pattern: \S - type: object required: - lastName properties: lastName: type: string minLength: 1 pattern: \S - type: object required: - emailAddress properties: emailAddress: type: string minLength: 1 pattern: \S plan: type: object properties: plan_name: type: string description: 订阅名称，必填，最长 255 字符。 maxLength: 255 minLength: 1 description: type: string description: 说明。 nullable: true maxLength: 500 surcharge_config: type: array description: >- 附加费选项，建议提交字符串数组，可选项见 Schema 和示例。省略、null 或空数组表示全部关闭；非数组也按全部关闭处理，未知选项不启用收费。credit_card_surcharge 表示信用卡附加费分组。实际是否收取受商户业务规则及支付方式限制。 卡类附加费受适用收费政策限制；政策不允许收费时，即使提交卡类选项也不启用收费。 nullable: true items: type: string description: 附加费选项。 enum: - 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: description: >- 是否收取客户扣款退票费，省略或 null 默认关闭。启用须已有适用的正数费额配置，实际金额以签署条款为准。也兼容 0/1 和字符串 "0"/"1"。 nullable: true oneOf: - type: boolean nullable: true - type: integer enum: - 0 - 1 - type: string enum: - '0' - '1' template_id: description: 本接口禁止使用此字段，请省略。 not: {} recurring: type: object properties: recurring_type: type: integer description: >- 订阅结束条件：1 按成功期数；2 按累计金额；3 持续至取消；4 按结束日期；5 By agreement，仅用于扣款授权，后续添加扣费计划。 提供非空 plan.recurring 时必填；该接口没有 enabled 开关。 nullable: true enum: - 1 - 2 - 3 - 4 - 5 - null start_date: type: string description: >- 起始日期。 建议使用 YYYY-MM-DD。 必须不早于服务业务时区的明天。 提供非空 plan.recurring 时必填；该接口没有 enabled 开关。 nullable: true format: date amount: oneOf: - type: number multipleOf: 0.01 minimum: 0.01 maximum: 9999999.99 nullable: true - type: string pattern: ^\d+(\.\d{1,2})?$ allOf: - pattern: >- ^0*(?:[1-9]\d{0,6}(?:\.\d{1,2})?|0\.(?:0[1-9]|[1-9]\d?))$ description: >- 单次或每期金额。 金额以主货币单位计，例如 10.50 表示 AUD 10.50，最多两位小数。接受数值或数字字符串，最小 0.01、最大 9999999.99，两种类型遵守相同范围限制。 recurring_type=1/2/3/4 时必填。By agreement(5) 仅用于扣款授权，不要求此字段。 recurring_type=5 时不用于定义扣费计划，建议省略；授权后的实际扣费规则通过 createSchedule 提交。 nullable: true day_of_debit: type: string description: >- RFC 5545 RRULE 扣费规则。recurring_type=1/2/3/4 时必填且不能为 null；recurring_type=5 为扣款授权，建议省略。授权后的扣费计划通过 createSchedule 提交。非标准频率须同时提供 process_type=12、custom_cycle_type 和 custom_cycle，并与 RRULE 一致。 nullable: true maxLength: 255 end_date: type: string description: >- 结束日期，建议使用 YYYY-MM-DD。recurring_type=4 时必填且不能为 null；提供时不得早于同一段的 start_date。recurring_type=5 时不用于定义扣费计划，建议省略。 nullable: true format: date end_terms: type: integer description: >- 成功扣费期数，正整数，最小为 1。recurring_type=1 时必填且不能为 null。recurring_type=5 时不用于定义扣费计划，建议省略。 nullable: true minimum: 1 total_amount: oneOf: - type: number multipleOf: 0.01 minimum: 0.01 nullable: true - type: string pattern: ^\d+(\.\d{1,2})?$ allOf: - pattern: >- ^0*(?:[1-9]\d*(?:\.\d{1,2})?|0\.(?:0[1-9]|[1-9]\d?))$ description: >- 目标累计金额，以主货币单位计，最多两位小数，最小为 0.01，接受数值或数字字符串。recurring_type=2 时必填且不能为 null。同时提供同段 amount 和 total_amount 时，amount 不得大于 total_amount。recurring_type=5 时不用于定义扣费计划，建议省略。 nullable: true process_type: type: integer description: >- 仅自定义频率时传 12。其他频率由 RRULE 推断，请省略此字段。 recurring_type=5 时不用于定义扣费计划，建议省略；授权后的实际扣费规则通过 createSchedule 提交。 nullable: true enum: - 12 - null custom_cycle_type: type: integer description: >- process_type=12 时必填。1 天、2 周、3 月、4 年；须与 RRULE 的 FREQ 对应。非 Custom 模式不得填写非空的自定义周期参数。 当 plan.recurring.process_type 为 12 时必填，且不能为 null。 recurring_type=5 时不用于定义扣费计划，建议省略；授权后的实际扣费规则通过 createSchedule 提交。 nullable: true enum: - 1 - 2 - 3 - 4 - null custom_cycle: type: integer description: >- process_type=12 时必填，正整数且必须等于 RRULE 的 INTERVAL。以天为单位时最小 5，其他单位最小 1。 当 plan.recurring.process_type 为 12 时必填，且不能为 null。 recurring_type=5 时不用于定义扣费计划，建议省略；授权后的实际扣费规则通过 createSchedule 提交。 nullable: true minimum: 1 day_of_debit_dtstart: type: string description: >- 首次扣费锚点。季度、半年、年度频率必填，推荐 YYYY-MM-DD；必须严格晚于对应 start_date，且在其后一个计费周期内（3/6/12 个月，按月底截断）。也支持 MM-DD，此时须为合法月日，不适用上述完整日期窗口限制。 recurring_type=5 时不用于定义扣费计划，建议省略；授权后的实际扣费规则通过 createSchedule 提交。 nullable: true pattern: ^(\d{4}-)?\d{2}-\d{2}$ schedule_name: type: string description: 扣费计划名称。 提供非空 plan.recurring 时必填；该接口没有 enabled 开关。 nullable: true maxLength: 255 description: >- 存在即启用，无 enabled 参数。支持 recurring_type 1/2/3/4/5。与 one_off 至少提供一段非空定义。 nullable: true not: anyOf: - allOf: - required: - recurring_type properties: recurring_type: enum: - 1 - not: required: - end_terms properties: end_terms: not: enum: - null - allOf: - required: - recurring_type properties: recurring_type: enum: - 2 - not: required: - total_amount properties: total_amount: not: enum: - null - allOf: - required: - recurring_type properties: recurring_type: enum: - 4 - not: required: - end_date properties: end_date: not: enum: - null minLength: 1 - allOf: - required: - recurring_type properties: recurring_type: enum: - 1 - 2 - 3 - 4 - not: required: - amount - day_of_debit properties: amount: not: enum: - null day_of_debit: not: enum: - null minLength: 1 - allOf: - required: - recurring_type properties: recurring_type: enum: - 1 - not: required: - end_terms properties: end_terms: not: enum: - null - allOf: - required: - recurring_type properties: recurring_type: enum: - 2 - not: required: - total_amount properties: total_amount: not: enum: - null - allOf: - required: - recurring_type properties: recurring_type: enum: - 4 - not: required: - end_date properties: end_date: not: enum: - null minLength: 1 - allOf: - required: - process_type properties: process_type: enum: - 12 - not: required: - custom_cycle_type - custom_cycle properties: custom_cycle_type: not: enum: - null custom_cycle: not: enum: - null - allOf: - required: - process_type - custom_cycle_type properties: process_type: enum: - 12 custom_cycle_type: enum: - 1 - not: required: - custom_cycle properties: custom_cycle: not: enum: - null minimum: 5 - allOf: - required: - custom_cycle_type properties: custom_cycle_type: not: enum: - null - not: required: - process_type properties: process_type: enum: - 12 - allOf: - required: - custom_cycle properties: custom_cycle: not: enum: - null - not: required: - process_type properties: process_type: enum: - 12 - allOf: - not: maxProperties: 0 - not: required: - recurring_type - start_date - schedule_name properties: recurring_type: not: enum: - null start_date: not: enum: - null minLength: 1 schedule_name: not: enum: - null minLength: 1 one_off: type: object properties: amount: oneOf: - type: number multipleOf: 0.01 minimum: 0.01 maximum: 9999999.99 nullable: true - type: string pattern: ^\d+(\.\d{1,2})?$ allOf: - pattern: >- ^0*(?:[1-9]\d{0,6}(?:\.\d{1,2})?|0\.(?:0[1-9]|[1-9]\d?))$ description: >- 单次或每期金额。 金额以主货币单位计，例如 10.50 表示 AUD 10.50，最多两位小数。接受数值或数字字符串，最小 0.01、最大 9999999.99，两种类型遵守相同范围限制。 当 plan.one_off 非空时必填，且不能为 null。 nullable: true payment_date: type: string description: >- 一次性扣款日期，至少为服务业务时区的明天。 当 plan.one_off 非空时必填，且不能为 null。 建议使用 YYYY-MM-DD。 必须不早于服务业务时区的明天。 nullable: true format: date description: type: string description: 说明。 nullable: true maxLength: 500 schedule_name: type: string description: 扣费计划名称。 当 plan.one_off 非空时必填，且不能为 null。 nullable: true maxLength: 255 description: 一次性付款定义；和 recurring 同启用时作为 Deposit，单独使用时为 One-off。 nullable: true not: anyOf: - allOf: - not: maxProperties: 0 - not: required: - amount - payment_date - schedule_name properties: amount: not: enum: - null payment_date: not: enum: - null minLength: 1 schedule_name: not: enum: - null minLength: 1 description: DDR 订阅定义，包含订阅名称、扣费规则及费用选项。 required: - plan_name not: not: anyOf: - type: object properties: recurring: type: object not: enum: - null minProperties: 1 required: - recurring - type: object properties: one_off: type: object not: enum: - null minProperties: 1 required: - one_off payment: type: object properties: type: type: integer description: 支付方式：1 银行账户，2 信用卡。 enum: - 1 - 2 accept_terms_of_service_at: description: >- 客户接受服务条款的时间，必填。 接受 Unix 毫秒或秒时间戳，也可使用 YYYY-MM-DD HH:mm:ss 格式的业务时区（Australia/Sydney）日期时间字符串；建议传毫秒时间戳，避免时区歧义。 必填时不能为 null、空字符串或仅空白字符。 oneOf: - type: number - type: string minLength: 1 accept_direct_debit_request_service_agreement_at: description: >- 客户接受 DDRSA 的时间，银行账户支付时必填。 接受 Unix 毫秒或秒时间戳，也可使用 YYYY-MM-DD HH:mm:ss 格式的业务时区（Australia/Sydney）日期时间字符串；建议传毫秒时间戳，避免时区歧义。 必填时不能为 null、空字符串或仅空白字符。 nullable: true oneOf: - type: number nullable: true - type: string minLength: 1 card: type: object properties: card_number: type: string description: >- 信用卡号，使用 Visa、Mastercard 或 American Express；最终能否使用取决于品牌识别及渠道配置。 pattern: ^\d{13,19}$ minLength: 1 expiration_month: type: string description: 卡有效期月份，建议两位数字，如 12。 pattern: ^\d{1,2}$ minLength: 1 expiration_year: type: string description: 卡有效期年份，建议四位数字，如 2030。 pattern: ^\d{2,4}$ minLength: 1 security_code: type: string description: 卡安全码 CVV，不使用数字类型以免丢失前导零。 pattern: ^\d{3,4}$ minLength: 1 name_on_card: type: string description: 卡面姓名。 maxLength: 100 minLength: 1 email: type: string description: 邮箱。 nullable: true format: email maxLength: 500 description: 信用卡信息。 payment.type=2 时此对象及必填子字段必须提供。 required: - card_number - expiration_month - expiration_year - security_code - name_on_card bank: type: object properties: bsb: type: string description: 澳洲 BSB。 pattern: ^\d{3}-?\d{3}$ minLength: 1 account_no: type: string description: 银行账号，使用字符串保留前导零。 pattern: ^\d{6,9}$ minLength: 1 account_name: type: string description: 银行账户名。 maxLength: 255 minLength: 1 email: type: string description: 邮箱。 nullable: true format: email maxLength: 500 description: 银行账户信息。 payment.type=1 时此对象及必填子字段必须提供。 required: - bsb - account_no - account_name description: 创建并激活时使用的支付方式和协议接受时间。 card/bank 的可提交字段以各自 Schema 为准。 required: - type - accept_terms_of_service_at not: anyOf: - allOf: - required: - type properties: type: enum: - 2 - not: required: - card properties: card: not: enum: - null - allOf: - required: - type properties: type: enum: - 1 - not: required: - bank properties: bank: not: enum: - null - allOf: - required: - type properties: type: enum: - 1 - not: required: - accept_direct_debit_request_service_agreement_at properties: accept_direct_debit_request_service_agreement_at: not: enum: - null notify_email: description: >- 是否允许本交易或订阅相关邮件通知。false 表示禁止，true 表示允许；省略或 null 时使用该业务的 API 邮件通知设置，默认关闭。实际发送受通知偏好和适用规则约束。 也兼容 0/1 和字符串 "0"/"1"。 nullable: true oneOf: - type: boolean nullable: true - type: integer enum: - 0 - 1 - type: string enum: - '0' - '1' notify_sms: description: >- 是否允许本交易或订阅相关短信通知。false 表示禁止，true 表示允许；省略或 null 时使用该业务的 API 短信通知设置，默认关闭。实际发送受通知偏好和适用规则约束。 也兼容 0/1 和字符串 "0"/"1"。 nullable: true oneOf: - type: boolean nullable: true - type: integer enum: - 0 - 1 - type: string enum: - '0' - '1' required: - merchant_id - subscription_number - customer - plan - payment DdrCreateResponse: type: object description: 成功响应。 properties: code: type: integer description: 0 表示 DDR 已创建并激活，不表示已完成扣款。 enum: - 0 message: type: string description: 响应说明。 data: type: object description: 已激活 DDR，无托管激活链接。 properties: customer_id: type: string description: BillBuddy 客户标识。 plan_id: type: string description: DDR 订阅 ID。 status: type: integer description: >- DDR 状态：1 Active、2 Inactive、3 Processing、4 Processed、5 On Hold、6 Completed、7 Cancelled、8 Paused、9 Expired。 enum: - 1 subscription_number: type: string description: 回显商户订阅编号。 required: - customer_id - plan_id - status - subscription_number required: - code - message - data BusinessError: type: object description: 业务错误。HTTP 通常仍为 200。 properties: code: type: integer description: 业务失败、认证失败为 1；Request 参数及文件属性校验失败为 400。 enum: - 1 - 400 message: type: string description: 错误原因，具体文案会因失败原因不同而变化。 data: oneOf: - type: object description: 空对象或错误上下文。 properties: customer_id: type: string description: createDdr 后续步骤失败时，可能返回已创建并保留的客户 ID；重试可使用此 ID。 - type: array items: {} description: 通常为空数组。 description: 错误数据，可能为 []、{} 或包含 customer_id 的客户上下文。 required: - code - message - data securitySchemes: oauth2: type: oauth2 description: OAuth2 client_credentials 授权。access_token 到期后重新获取。 flows: clientCredentials: tokenUrl: /oauth/token scopes: {} ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.