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

# Quickstart

> Authentication, identifiers, amounts, dates and hosted subscription integration

BillBuddy API integration guide. It covers authentication, transaction and subscription endpoints called by third-party servers. Request and response examples contain complete fictional business data and tokens generated offline; they cannot authenticate or initiate real transactions.

## Getting started

1. Obtain your Client ID, Client Secret, merchant identifier and business identifier from BillBuddy. If an IP allowlist applies, send requests from an approved fixed outbound IP address.
2. Obtain an access\_token through POST /oauth/token. Business requests require Authorization: Bearer \{access\_token} and Accept: application/json. Use Content-Type: application/json for JSON requests and form encoding for token requests.
3. Call the payment or subscription endpoints as needed. Customers open the hosted activation page through activation\_url. Store the Client Secret only on your server.

## Identifiers and amounts

OAuth credentials identify the merchant; business\_id is not a request parameter. Endpoints that require a business use merchant\_id. For single-transaction and batch-result lookups, merchant\_id is optional; omit it or leave it empty to search all businesses of the authenticated merchant. The transaction list uses optional, case-sensitive Mid; omit it to query all businesses belonging to the authenticated merchant. A requested business must belong to that merchant. Read response identifiers according to each endpoint's field definitions.
TXT file amounts, amount\_cents and declared\_total\_amount\_cents use cents. Other amounts use major currency units with at most two decimal places: 10.50 means AUD 10.50. Use strings for bank account numbers, card numbers, months, years and postcodes to preserve leading zeros.

## Success and failure

Business JSON responses use code=0 for success and code=1 for ordinary failures. Transaction and subscription validation failures usually return code=400 and data=\{} with HTTP 200. V2 business endpoint authentication failures use code=1. A missing, malformed or inaccessible business merchant\_id for plan/list returns code=1. HTTP 429 indicates a rate limit. The OAuth endpoint uses standard OAuth responses with HTTP 200/400/401/429.
code=0 means the API request was processed successfully; assess the payment outcome separately. Batch accepted means the request was accepted for asynchronous processing. Bank Pending, scheduled Pending and outstanding 3DS authentication do not indicate payment success. Transactions, DDR subscriptions and payment schedules use different status enumerations; refer to their field definitions.

## Dates and frequencies

Use YYYY-MM-DD for request dates. Today and tomorrow are evaluated in Australia/Sydney, including daylight saving time. Scheduled cancellations also use Australia/Sydney: cancellation must occur strictly before 08:15 on the processing date; it is no longer permitted at that time. Payment complete\_date and checkout expires\_at use DD/MM/YYYY HH:mm:ss. Refer to individual fields for other formats.
Standard RRULE examples: 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. Weekday abbreviations are MO/TU/WE/TH/FR/SA/SU. Weekly/Monthly rules without a specific debit day derive it from the start date. A single BYDAY=SA or SU is treated as Monday; a weekend start date without an explicit debit day is also treated as Monday. A single BYMONTHDAY=29/30/31 falls on the last day of shorter months; BYMONTHDAY=-1 means the last day of the month. All rules must be valid RRULE expressions.
For a nonstandard frequency such as every 10 days, provide process\_type=12, custom\_cycle\_type=1, custom\_cycle=10 and day\_of\_debit=FREQ=DAILY;INTERVAL=10. Units 1/2/3/4 correspond to DAILY/WEEKLY/MONTHLY/YEARLY. The minimum interval is 5 for days and 1 for other units. INTERVAL must equal custom\_cycle. Quarterly, half-yearly and yearly schedules also require day\_of\_debit\_dtstart. Its complete date must be strictly after the start\_date of the same schedule segment and within one billing cycle after it. The first actual debit date for createSchedule depends on the DDR start date, debit frequency and the requirement that it be no earlier than tomorrow.

## Using examples

Schemas define types, nullability, lengths, enumerations and numeric ranges. Field descriptions define conditional requirements, dates and business restrictions. Use both together. Set BASE\_URL, ACCESS\_TOKEN, CLIENT\_ID and CLIENT\_SECRET before running curl examples. BillBuddy provides the actual test and production domains. Replace example customers, orders, cards, accounts and dates with values permitted in your test environment and satisfying the date restrictions.

## Hosted subscription integration

Call POST /api/v2/subscription/create, then use the complete activation\_url unchanged for a browser redirect or an iframe src. Alternatively, use activation\_html as the iframe srcdoc. Customers enter payment information, authorize debits and activate the subscription on the BillBuddy-hosted page. Use the full returned URL; do not construct it yourself or parse its credentials. Keep the Client Secret and access\_token on your server; never include them in iframe URLs or page contents.

Recurring and By agreement subscriptions must be activated before start\_date. One-off-only subscriptions must be submitted for activation within 30 days of creation. An accessible page does not guarantee submission is still permitted; the activation response is authoritative.

## Example data conventions

Example merchants, customers, orders, payment tokens, session links and OAuth credentials are fictional and cannot be used for real requests. Card numbers are standard test card numbers; bank accounts are fictional. Email addresses use the reserved example.com domain, and phone numbers use Australian numbers reserved for examples. Replace BASE\_URL, ACCESS\_TOKEN, CLIENT\_ID and CLIENT\_SECRET with actual values from your approved test environment. Empty strings, null, empty arrays, 0 and false represent meaningful API states in some examples and must not be replaced indiscriminately.
Payment response signatures are calculated offline according to the signing rules for each payment scenario, using the public demo key bb\_docs\_demo\_signing\_key\_2030. The html field is excluded for responses awaiting 3DS authentication. This key is for documentation only and cannot sign or authenticate real requests.

## TXT batch transactions

Upload fixed-width TXT files using multipart/form-data. File amounts, amount\_cents and declared\_total\_amount\_cents use cents, excluding surcharges; see “Upload a TXT transaction file” for the format and example file. Upload success only confirms acceptance. Retain batch\_id and file\_identifier and use the batch result endpoint to check individual outcomes. Batch completed does not mean every payment succeeded. Use OAuth credentials for the same merchant to query results. merchant\_id is optional; when supplied, it must match the business identifier in the original upload. Response identifiers follow the definitions for each endpoint.


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