> ## 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.

# 快速开始

> 认证、标识、金额、日期及托管订阅接入约定

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 的 merchant\_id 缺失、格式不正确或业务不可访问时返回 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 可省略，如传入则须与原上传请求的业务标识一致。响应字段含义以对应接口说明为准。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.