> ## 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. # Create and activate a DDR > ### Customer, subscription and payment method Supply `merchant_id`, `subscription_number`, `customer`, `plan` and `payment`. Choose either `customer.customer_id` for an existing customer or `firstName`, `lastName` and `emailAddress` for a new customer. Do not combine the two. `plan.plan_name` is required; templates are not supported. Provide at least one non-empty `plan.recurring` or `plan.one_off` segment. This endpoint has no `enabled` switch. Every recurring segment requires `recurring_type`, `start_date` and `schedule_name`; types 1–4 also require `amount` and `day_of_debit`. | recurring_type | End condition | Additional required fields | | --- | --- | --- | | 1 | Successful payment count | `end_terms` | | 2 | Total amount | `total_amount`, with `amount` no greater than `total_amount` | | 3 | Until cancelled | No additional end condition | | 4 | End date | `end_date`, no earlier than the segment's `start_date` | | 5 | By agreement authorization | No amount or frequency required; add payment schedules later through `createSchedule` | A non-empty one-off segment requires `schedule_name`, `amount` and `payment_date`. Start and payment dates must be no earlier than tomorrow in the business timezone. See individual fields for quarterly, half-yearly, yearly and custom frequency requirements. | payment.type | Payment details | Agreement timestamps | | --- | --- | --- | | 1, bank account | `payment.bank.bsb`, `payment.bank.account_no`, `payment.bank.account_name` | `accept_terms_of_service_at`, `accept_direct_debit_request_service_agreement_at` | | 2, credit card | `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` | Choose the bank or card details matching `payment.type`. Submit only the selected object where possible. The other object is not used for this binding, but any supplied fields must still pass validation. All agreement timestamps are within `payment`. See request fields for accepted types and limits. The merchant server submits a payment method and agreement acceptance timestamp on the customer's behalf. A successful creation returns status=1 Active. Supports recurring types 1/2/3/4, By agreement (5), one_off only, and recurring plus one-off combinations. Templates and 3DS are not supported, and no activation link is provided. By agreement creates a debit authorization only; call createSchedule to add a payment schedule. subscription_number must be unique within the same merchant and business. On failure, data.customer_id may identify a customer already created; reuse that identifier when retrying. If a failure response includes data.customer_id, the customer has already been created. Retry with customer.customer_id to reuse that customer and avoid duplicates. The error message varies by cause. All examples illustrate request and response formats. Replace customers, orders, cards and accounts with approved test data. BASE_URL is the service root domain without /api/v2. ACCESS_TOKEN is the access_token returned by /oauth/token. Example dates are in 2030; replace them with actual dates that satisfy the current date restrictions. ## OpenAPI ````yaml /openapi/billbuddy-v2-openapi.en.yaml post /api/v2/subscription/createDdr openapi: 3.0.3 info: title: BillBuddy API Integration Guide version: 2.0.0 description: > 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 return 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. ## Request examples by programming language Examples are provided in cURL, Python, JavaScript, PHP, Go, Java and Ruby, with the same business scenarios available in each language. Each example preserves the parameters and types from its corresponding cURL scenario. Requirements: cURL; Python 3.9+ (standard library); JavaScript with Node.js 18+, saved as an .mjs file; PHP 8+ with the cURL extension; Go 1.20+; Java 11+ (save the Example class as Example.java); Ruby 3+ (standard library). Set BASE_URL before running examples. Business endpoints also require ACCESS_TOKEN; token requests require CLIENT_ID and CLIENT_SECRET. BASE_URL is the API root without /api/v2. TXT upload examples read payments.txt from the current directory. Replace fictional values with approved test data and assess the response code and business status separately. servers: - url: https://staging-api.billbuddyhq.com description: Staging environment security: - oauth2: [] tags: - name: Authentication description: OAuth2 Client Credentials。 - name: Transactions description: Single payments, batch payments and scheduled payment cancellations. - name: Subscriptions description: >- Subscription templates, hosted subscription creation, DDR creation and activation, and payment schedule submission. paths: /api/v2/subscription/createDdr: post: tags: - Subscriptions summary: Create and activate a DDR description: >- ### Customer, subscription and payment method Supply `merchant_id`, `subscription_number`, `customer`, `plan` and `payment`. Choose either `customer.customer_id` for an existing customer or `firstName`, `lastName` and `emailAddress` for a new customer. Do not combine the two. `plan.plan_name` is required; templates are not supported. Provide at least one non-empty `plan.recurring` or `plan.one_off` segment. This endpoint has no `enabled` switch. Every recurring segment requires `recurring_type`, `start_date` and `schedule_name`; types 1–4 also require `amount` and `day_of_debit`. | recurring_type | End condition | Additional required fields | | --- | --- | --- | | 1 | Successful payment count | `end_terms` | | 2 | Total amount | `total_amount`, with `amount` no greater than `total_amount` | | 3 | Until cancelled | No additional end condition | | 4 | End date | `end_date`, no earlier than the segment's `start_date` | | 5 | By agreement authorization | No amount or frequency required; add payment schedules later through `createSchedule` | A non-empty one-off segment requires `schedule_name`, `amount` and `payment_date`. Start and payment dates must be no earlier than tomorrow in the business timezone. See individual fields for quarterly, half-yearly, yearly and custom frequency requirements. | payment.type | Payment details | Agreement timestamps | | --- | --- | --- | | 1, bank account | `payment.bank.bsb`, `payment.bank.account_no`, `payment.bank.account_name` | `accept_terms_of_service_at`, `accept_direct_debit_request_service_agreement_at` | | 2, credit card | `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` | Choose the bank or card details matching `payment.type`. Submit only the selected object where possible. The other object is not used for this binding, but any supplied fields must still pass validation. All agreement timestamps are within `payment`. See request fields for accepted types and limits. The merchant server submits a payment method and agreement acceptance timestamp on the customer's behalf. A successful creation returns status=1 Active. Supports recurring types 1/2/3/4, By agreement (5), one_off only, and recurring plus one-off combinations. Templates and 3DS are not supported, and no activation link is provided. By agreement creates a debit authorization only; call createSchedule to add a payment schedule. subscription_number must be unique within the same merchant and business. On failure, data.customer_id may identify a customer already created; reuse that identifier when retrying. If a failure response includes data.customer_id, the customer has already been created. Retry with customer.customer_id to reuse that customer and avoid duplicates. The error message varies by cause. All examples illustrate request and response formats. Replace customers, orders, cards and accounts with approved test data. BASE_URL is the service root domain without /api/v2. ACCESS_TOKEN is the access_token returned by /oauth/token. Example dates are in 2030; replace them with actual dates that satisfy the current date restrictions. operationId: v2CreateDdr requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DdrCreateRequest' examples: baBank: summary: Bank account By agreement authorization 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: Recurring DDR with a credit card 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: One-off-only 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. Distinguish success, business errors, validation errors and business authentication errors using the response body code. content: application/json: schema: oneOf: - $ref: '#/components/schemas/DdrCreateResponse' - $ref: '#/components/schemas/BusinessError' examples: success: summary: Activated successfully value: code: 0 message: ok data: customer_id: CUS48290713 plan_id: DDR73019482 subscription_number: MEM-20300101-001 status: 1 duplicate: summary: Subscription number already exists value: code: 1 message: The subscription number already exists data: [] validation: summary: Parameter error value: code: 400 message: The payment field is required. data: {} customerCreatedButDdrFailed: summary: >- DDR creation failed after customer creation; reuse customer_id when retrying value: code: 1 message: DDR create failed due to internal error data: customer_id: CUS48290714 '429': description: >- Rate limit exceeded. API requests share a limit of 120 requests per minute, normally counted by source IP; this is not a separate allowance for each endpoint. Wait for the seconds specified by Retry-After. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer content: application/json: schema: type: object description: Rate limit response. properties: message: type: string description: Rate limit message. example: message: Too Many Attempts. security: - oauth2: [] x-codeSamples: - lang: Shell label: Bank account By agreement authorization 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: Recurring DDR with a credit card 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: One-off-only 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: Bank account By agreement authorization 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: Recurring DDR with a credit card 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: One-off-only 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: Bank account By agreement authorization 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: Recurring DDR with a credit card 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: One-off-only 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: Bank account By agreement authorization 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: Recurring DDR with a credit card 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: One-off-only 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: Bank account By agreement authorization 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: Recurring DDR with a credit card 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: One-off-only 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: Bank account By agreement authorization 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: Recurring DDR with a credit card 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: One-off-only 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: Bank account By agreement authorization 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: Recurring DDR with a credit card 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: One-off-only 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: >- Creates and immediately activates a DDR from the merchant server. customer must contain either an existing customer reference or new customer details. At least one of plan.recurring and plan.one_off must be nonempty; templates are not supported. recurring_type=5 creates a By agreement debit authorization only; 1/2/3/4 create recurring payment schedules. one_off alone is a one-off payment; combined with recurring it is a deposit. payment is required; 3DS is not supported. Currency is fixed to AUD. properties: merchant_id: type: string description: Business identifier assigned by BillBuddy. maxLength: 20 minLength: 1 subscription_number: type: string description: >- Merchant subscription number. Must be unique within the same merchant and business. A previously used number cannot be reused; duplicates fail instead of returning the existing subscription. maxLength: 64 minLength: 1 customer: type: object properties: customer_id: type: string description: >- BillBuddy customer identifier. Must identify a valid customer within the current merchant and business. nullable: true maxLength: 32 firstName: type: string description: >- New customer's first name. Required when creating a new customer. nullable: true maxLength: 100 lastName: type: string description: New customer's last name. Required when creating a new customer. nullable: true maxLength: 100 emailAddress: type: string description: >- New customer's primary email address. Required when creating a new customer. If it already belongs to a customer in the same merchant and business, supply that existing customer_id instead. nullable: true format: email maxLength: 500 mobilePhoneNumber: type: string description: Customer mobile phone number. nullable: true maxLength: 20 addressLine1: type: string description: Customer address line 1. nullable: true maxLength: 255 addressSuburb: type: string description: Customer city or suburb. nullable: true maxLength: 100 addressState: type: string description: Customer state or province. nullable: true maxLength: 100 addressPostCode: type: string description: Customer postcode. nullable: true maxLength: 50 description: >- Customer information. Supply either an existing customer identifier or new customer details. 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: Subscription name. Required; at most 255 characters. maxLength: 255 minLength: 1 description: type: string description: Description. nullable: true maxLength: 500 surcharge_config: type: array description: >- Surcharge options, preferably an array of strings. See the schema and examples for allowed options. Omission, null or an empty array disables all options; non-array values are also treated as all disabled. Unknown options do not enable charges. credit_card_surcharge selects the credit card surcharge group. Actual charges depend on merchant business rules and payment method restrictions. Card surcharges remain subject to the applicable charging policy; if that policy prohibits them, selecting card options does not enable charges. nullable: true items: type: string description: Surcharge option. 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: >- Whether to charge a customer dishonour fee. Omission or null defaults to off. Enabling it requires an applicable positive fee configuration; the signed terms determine the actual amount. Also accepts 0/1 and the strings "0"/"1". nullable: true oneOf: - type: boolean nullable: true - type: integer enum: - 0 - 1 - type: string enum: - '0' - '1' template_id: description: This endpoint prohibits this field. Omit it. not: {} recurring: type: object properties: recurring_type: type: integer description: >- Subscription end condition: 1 after a number of successful payments; 2 at a cumulative amount; 3 until cancelled; 4 on an end date; 5 By agreement, which creates a debit authorization for later payment schedules. Required when plan.recurring is nonempty; this endpoint has no enabled flag. nullable: true enum: - 1 - 2 - 3 - 4 - 5 - null start_date: type: string description: >- Start date, preferably YYYY-MM-DD. Must be no earlier than tomorrow in the service business timezone. Required when plan.recurring is nonempty; this endpoint has no enabled flag. The earliest date is tomorrow in the service business timezone. 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: >- One-off or per-payment amount in major currency units, for example 10.50 means AUD 10.50. At most two decimal places. Numbers and numeric strings are accepted, with a minimum of 0.01 and maximum of 9999999.99; the same range applies to both types. Required for recurring_type=1/2/3/4. By agreement (5) creates a debit authorization only and does not require this field. For recurring_type=5, this field does not define a payment schedule and should be omitted; submit actual debit rules through createSchedule after authorization. nullable: true day_of_debit: type: string description: >- RFC 5545 RRULE debit rule. Required and non-null for recurring_type=1/2/3/4. Omit it for recurring_type=5, which creates a debit authorization; submit subsequent payment schedules through createSchedule. Nonstandard frequencies require process_type=12, custom_cycle_type and custom_cycle consistent with the RRULE. nullable: true maxLength: 255 end_date: type: string description: >- End date, preferably YYYY-MM-DD. Required and non-null when recurring_type=4. When supplied, cannot precede start_date in the same segment. Omit for recurring_type=5 because it does not define a payment schedule. nullable: true format: date end_terms: type: integer description: >- Number of successful payments, an integer of at least 1. Required and non-null when recurring_type=1. Omit for recurring_type=5 because it does not define a payment schedule. 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: >- Target total amount in major currency units, with at most two decimal places and a minimum of 0.01. Accepts a number or numeric string. Required and non-null when recurring_type=2. When amount and total_amount are both supplied in the same segment, amount must not exceed total_amount. Omit for recurring_type=5 because it does not define a payment schedule. nullable: true process_type: type: integer description: >- Provide 12 only for a custom frequency. Other frequencies are inferred from the RRULE; omit this field for them. For recurring_type=5, this field does not define a payment schedule and should be omitted; submit actual debit rules through createSchedule after authorization. nullable: true enum: - 12 - null custom_cycle_type: type: integer description: >- Required for process_type=12: 1 days, 2 weeks, 3 months, 4 years. Must correspond to the RRULE FREQ. Non-Custom mode prohibits nonempty custom cycle parameters. Required and non-null when plan.recurring.process_type=12. For recurring_type=5, this field does not define a payment schedule and should be omitted; submit actual debit rules through createSchedule after authorization. nullable: true enum: - 1 - 2 - 3 - 4 - null custom_cycle: type: integer description: >- Required for process_type=12. A positive integer equal to the RRULE INTERVAL. Minimum 5 for days and 1 for other units. Required and non-null when plan.recurring.process_type=12. For recurring_type=5, this field does not define a payment schedule and should be omitted; submit actual debit rules through createSchedule after authorization. nullable: true minimum: 1 day_of_debit_dtstart: type: string description: >- First debit anchor. Required for quarterly, half-yearly and yearly frequencies. YYYY-MM-DD is recommended; the date must be strictly after the corresponding start_date and within one billing cycle (3/6/12 months, clamped to month end). MM-DD is also accepted if it is a valid month/day; the full-date window restriction does not apply to that format. For recurring_type=5, this field does not define a payment schedule and should be omitted; submit actual debit rules through createSchedule after authorization. nullable: true pattern: ^(\d{4}-)?\d{2}-\d{2}$ schedule_name: type: string description: >- Payment schedule name. Required when plan.recurring is nonempty; this endpoint has no enabled flag. nullable: true maxLength: 255 description: >- Enabled by its presence; no enabled parameter is supported. Supports recurring_type=1/2/3/4/5. At least one nonempty definition must be supplied between this field and 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: >- One-off or per-payment amount in major currency units, for example 10.50 means AUD 10.50. At most two decimal places. Numbers and numeric strings are accepted, with a minimum of 0.01 and maximum of 9999999.99; the same range applies to both types. Required and non-null when plan.one_off is nonempty. nullable: true payment_date: type: string description: >- One-off debit date. Must be no earlier than tomorrow in the service business timezone. Required and non-null when plan.one_off is nonempty. YYYY-MM-DD is recommended. Cannot precede tomorrow in the service business timezone. nullable: true format: date description: type: string description: Description. nullable: true maxLength: 500 schedule_name: type: string description: >- Payment schedule name. Required and non-null when plan.one_off is nonempty. nullable: true maxLength: 255 description: >- One-off payment definition. Acts as a Deposit when enabled with recurring, or as a One-off when used alone. 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 subscription definition, including the subscription name, debit rules and fee options. 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: 'Payment method: 1 bank account, 2 credit card.' enum: - 1 - 2 accept_terms_of_service_at: description: >- Timestamp when the customer accepted the terms of service. Required. Accepts Unix milliseconds or seconds, or a date-time string in YYYY-MM-DD HH:mm:ss format in the business timezone (Australia/Sydney). Milliseconds are recommended to avoid timezone ambiguity. When required, cannot be null, empty or whitespace-only. oneOf: - type: number - type: string minLength: 1 accept_direct_debit_request_service_agreement_at: description: >- Timestamp when the customer accepted the DDRSA. Required for bank account payments. Accepts Unix milliseconds or seconds, or a date-time string in YYYY-MM-DD HH:mm:ss format in the business timezone (Australia/Sydney). Milliseconds are recommended to avoid timezone ambiguity. When required, cannot be null, empty or whitespace-only. nullable: true oneOf: - type: number nullable: true - type: string minLength: 1 card: type: object properties: card_number: type: string description: >- Visa, Mastercard or American Express card number. Acceptance depends on card brand recognition and channel configuration. pattern: ^\d{13,19}$ minLength: 1 expiration_month: type: string description: Card expiry month, preferably two digits, such as 12. pattern: ^\d{1,2}$ minLength: 1 expiration_year: type: string description: Card expiry year, preferably four digits, such as 2030. pattern: ^\d{2,4}$ minLength: 1 security_code: type: string description: >- Card security code (CVV). Use a string to preserve leading zeros. pattern: ^\d{3,4}$ minLength: 1 name_on_card: type: string description: Name on the card. maxLength: 100 minLength: 1 email: type: string description: Email address. nullable: true format: email maxLength: 500 description: >- Credit card information. Required with its mandatory child fields when payment.type=2. required: - card_number - expiration_month - expiration_year - security_code - name_on_card bank: type: object properties: bsb: type: string description: Australian BSB. pattern: ^\d{3}-?\d{3}$ minLength: 1 account_no: type: string description: Bank account number. Use a string to preserve leading zeros. pattern: ^\d{6,9}$ minLength: 1 account_name: type: string description: Bank account holder name. maxLength: 255 minLength: 1 email: type: string description: Email address. nullable: true format: email maxLength: 500 description: >- Bank account information. Required with its mandatory child fields when payment.type=1. required: - bsb - account_no - account_name description: >- Payment method and agreement acceptance timestamps for creation and activation. Each card/bank schema defines its accepted fields. 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: >- Whether to allow email notifications for this transaction or subscription. false prohibits them; true allows them. Omission or null uses the business's API email notification setting, which defaults to off. Actual delivery depends on notification preferences and applicable rules. Also accepts 0/1 and the strings "0"/"1". nullable: true oneOf: - type: boolean nullable: true - type: integer enum: - 0 - 1 - type: string enum: - '0' - '1' notify_sms: description: >- Whether to allow SMS notifications for this transaction or subscription. false prohibits them; true allows them. Omission or null uses the business's API SMS notification setting, which defaults to off. Actual delivery depends on notification preferences and applicable rules. Also accepts 0/1 and the strings "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: Success response. properties: code: type: integer description: >- 0 means the DDR was created and activated. Does not indicate a completed charge. enum: - 0 message: type: string description: Response message. data: type: object description: Activated DDR without a hosted activation link. properties: customer_id: type: string description: BillBuddy customer identifier. plan_id: type: string description: DDR subscription ID. status: type: integer description: >- DDR status: 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: Echoes the merchant subscription number. required: - customer_id - plan_id - status - subscription_number required: - code - message - data BusinessError: type: object description: Business error. HTTP status is usually still 200. properties: code: type: integer description: >- Business and authentication errors use 1; request parameter and upload file property validation errors use 400. enum: - 1 - 400 message: type: string description: Error reason. The exact message varies by cause. data: oneOf: - type: object description: Empty object or error context. properties: customer_id: type: string description: >- If a later createDdr step fails, this may identify a customer that was created and retained. Reuse this ID when retrying. - type: array items: {} description: Usually an empty array. description: >- Error data: may be [], {} or customer context containing customer_id. required: - code - message - data securitySchemes: oauth2: type: oauth2 description: >- OAuth2 client_credentials authorization. Obtain a new access_token when it expires. flows: clientCredentials: tokenUrl: /oauth/token scopes: {} ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.