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.
Authorizations
OAuth2 client_credentials authorization. Obtain a new access_token when it expires.
Body
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.
Business identifier assigned by BillBuddy.
1 - 20Merchant 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.
1 - 64Customer information. Supply either an existing customer identifier or new customer details.
Show child attributes
Show child attributes
DDR subscription definition, including the subscription name, debit rules and fee options.
Show child attributes
Show child attributes
Payment method and agreement acceptance timestamps for creation and activation. Each card/bank schema defines its accepted fields.
Show child attributes
Show child attributes
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".
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".
Response
HTTP 200. Distinguish success, business errors, validation errors and business authentication errors using the response body code.