> ## 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 batch direct payments > ### Parameters for each transaction Supply `merchant_id` and `transactions` at the top level, with 1–100 transactions per batch. Each transaction requires `trans_func`, `amount`, `merchant_order_no` and `currency`, plus the fields below. | trans_func | Operation | Additional required fields per transaction | | --- | --- | --- | | 2 | Token payment | `card_token`, `first_name`, `last_name` | | 3 | Card number payment | `card.card_number`, `card.expiration_month`, `card.expiration_year`, `card.security_code`, `first_name`, `last_name` | | 5 | Bank account payment | `bank_account.bsb`, `bank_account.account_no`, `bank_account.account_name`; this transaction uses the bank account, so omit `card` because it is not used for payment | Batches do not support token creation, checkout or 3DS. `is3ds` and `return_url` are not supported row parameters. Optional `process_date` must be strictly after today in the business timezone. Invalid rows return reasons while valid rows can be accepted; acceptance does not mean payment succeeded. Submit 1 to 100 transactions per request. Each transaction receives an acceptance or rejection result. accepted means the request was accepted for asynchronous processing, not that payment succeeded. Only trans_func=2/3/5 are supported; token creation, checkout and 3DS are not supported. Existing order numbers, duplicate order numbers within the batch and invalid parameters cause the affected transactions to be rejected without preventing other valid transactions from being accepted. Top-level code may still be 0 even when all transactions are rejected. Check each result and confirm the final payment status. Per-transaction results apply when batch processing completes normally. A malformed request structure or processing exception may fail the whole batch. If complete per-transaction results are unavailable, query order status before deciding whether to retry. 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/trans/batchDirectPay 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/trans/batchDirectPay: post: tags: - Transactions summary: Create batch direct payments description: >- ### Parameters for each transaction Supply `merchant_id` and `transactions` at the top level, with 1–100 transactions per batch. Each transaction requires `trans_func`, `amount`, `merchant_order_no` and `currency`, plus the fields below. | trans_func | Operation | Additional required fields per transaction | | --- | --- | --- | | 2 | Token payment | `card_token`, `first_name`, `last_name` | | 3 | Card number payment | `card.card_number`, `card.expiration_month`, `card.expiration_year`, `card.security_code`, `first_name`, `last_name` | | 5 | Bank account payment | `bank_account.bsb`, `bank_account.account_no`, `bank_account.account_name`; this transaction uses the bank account, so omit `card` because it is not used for payment | Batches do not support token creation, checkout or 3DS. `is3ds` and `return_url` are not supported row parameters. Optional `process_date` must be strictly after today in the business timezone. Invalid rows return reasons while valid rows can be accepted; acceptance does not mean payment succeeded. Submit 1 to 100 transactions per request. Each transaction receives an acceptance or rejection result. accepted means the request was accepted for asynchronous processing, not that payment succeeded. Only trans_func=2/3/5 are supported; token creation, checkout and 3DS are not supported. Existing order numbers, duplicate order numbers within the batch and invalid parameters cause the affected transactions to be rejected without preventing other valid transactions from being accepted. Top-level code may still be 0 even when all transactions are rejected. Check each result and confirm the final payment status. Per-transaction results apply when batch processing completes normally. A malformed request structure or processing exception may fail the whole batch. If complete per-transaction results are unavailable, query order status before deciding whether to retry. 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: v2BatchDirectPay requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BatchDirectPayRequest' examples: batch: summary: Batch payment request value: merchant_id: '48290713' transactions: - amount: '25.50' merchant_order_no: BB-BATCH-20300101-001 currency: AUD trans_func: 3 first_name: Emily last_name: Carter card: card_number: '4111111111111111' expiration_month: '12' expiration_year: '2030' security_code: '123' notify_email: false notify_sms: false - trans_func: 5 amount: '12.00' merchant_order_no: BB-BATCH-20300101-002 currency: AUD bank_account: bsb: 062-000 account_no: '618472950' account_name: Emily Carter process_date: '2030-01-15' 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/BatchDirectPayResponse' - $ref: '#/components/schemas/BusinessError' examples: partial: summary: Partially accepted batch value: code: 0 message: accepted data: total: 2 accepted: 1 rejected: 1 items: - merchant_order_no: BB-BATCH-20300101-001 result: accepted - merchant_order_no: BB-BATCH-20300101-002 result: rejected reason: Order already exists allAccepted: summary: All transactions accepted value: code: 0 message: accepted data: total: 2 accepted: 2 rejected: 0 items: - merchant_order_no: BB-BATCH-20300101-001 result: accepted - merchant_order_no: BB-BATCH-20300101-002 result: accepted validation: summary: Invalid top-level request structure value: code: 400 message: The transactions field is required. data: {} auth: summary: OAuth failure value: code: 1 message: Unauthenticated, invalid or expired access token data: [] '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: Batch payment request source: |- curl -X POST "${BASE_URL}/api/v2/trans/batchDirectPay" \ -H "Authorization: Bearer ${ACCESS_TOKEN}" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ --data-raw '{ "merchant_id": "48290713", "transactions": [ { "amount": "25.50", "merchant_order_no": "BB-BATCH-20300101-001", "currency": "AUD", "trans_func": 3, "first_name": "Emily", "last_name": "Carter", "card": { "card_number": "4111111111111111", "expiration_month": "12", "expiration_year": "2030", "security_code": "123" }, "notify_email": false, "notify_sms": false }, { "trans_func": 5, "amount": "12.00", "merchant_order_no": "BB-BATCH-20300101-002", "currency": "AUD", "bank_account": { "bsb": "062-000", "account_no": "618472950", "account_name": "Emily Carter" }, "process_date": "2030-01-15" } ] }' - lang: Python label: Batch payment request source: > import json import os import urllib.parse import urllib.request base_url = os.environ["BASE_URL"].rstrip("/") url = base_url + "/api/v2/trans/batchDirectPay" headers = {"Accept": "application/json"} headers["Authorization"] = "Bearer " + os.environ["ACCESS_TOKEN"] payload = json.loads(r'''{ "merchant_id": "48290713", "transactions": [ { "amount": "25.50", "merchant_order_no": "BB-BATCH-20300101-001", "currency": "AUD", "trans_func": 3, "first_name": "Emily", "last_name": "Carter", "card": { "card_number": "4111111111111111", "expiration_month": "12", "expiration_year": "2030", "security_code": "123" }, "notify_email": false, "notify_sms": false }, { "trans_func": 5, "amount": "12.00", "merchant_order_no": "BB-BATCH-20300101-002", "currency": "AUD", "bank_account": { "bsb": "062-000", "account_no": "618472950", "account_name": "Emily Carter" }, "process_date": "2030-01-15" } ] }''') 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: Batch payment request 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/trans/batchDirectPay"); const headers = { Accept: "application/json" }; headers.Authorization = `Bearer ${env("ACCESS_TOKEN")}`; const payload = { "merchant_id": "48290713", "transactions": [ { "amount": "25.50", "merchant_order_no": "BB-BATCH-20300101-001", "currency": "AUD", "trans_func": 3, "first_name": "Emily", "last_name": "Carter", "card": { "card_number": "4111111111111111", "expiration_month": "12", "expiration_year": "2030", "security_code": "123" }, "notify_email": false, "notify_sms": false }, { "trans_func": 5, "amount": "12.00", "merchant_order_no": "BB-BATCH-20300101-002", "currency": "AUD", "bank_account": { "bsb": "062-000", "account_no": "618472950", "account_name": "Emily Carter" }, "process_date": "2030-01-15" } ] }; 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: Batch payment request 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: Batch payment request 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/trans/batchDirectPay" payload := `{ "merchant_id": "48290713", "transactions": [ { "amount": "25.50", "merchant_order_no": "BB-BATCH-20300101-001", "currency": "AUD", "trans_func": 3, "first_name": "Emily", "last_name": "Carter", "card": { "card_number": "4111111111111111", "expiration_month": "12", "expiration_year": "2030", "security_code": "123" }, "notify_email": false, "notify_sms": false }, { "trans_func": 5, "amount": "12.00", "merchant_order_no": "BB-BATCH-20300101-002", "currency": "AUD", "bank_account": { "bsb": "062-000", "account_no": "618472950", "account_name": "Emily Carter" }, "process_date": "2030-01-15" } ] }` 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: Batch payment request 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/trans/batchDirectPay"; String payload = "{\n" + " \"merchant_id\": \"48290713\",\n" + " \"transactions\": [\n" + " {\n" + " \"amount\": \"25.50\",\n" + " \"merchant_order_no\": \"BB-BATCH-20300101-001\",\n" + " \"currency\": \"AUD\",\n" + " \"trans_func\": 3,\n" + " \"first_name\": \"Emily\",\n" + " \"last_name\": \"Carter\",\n" + " \"card\": {\n" + " \"card_number\": \"4111111111111111\",\n" + " \"expiration_month\": \"12\",\n" + " \"expiration_year\": \"2030\",\n" + " \"security_code\": \"123\"\n" + " },\n" + " \"notify_email\": false,\n" + " \"notify_sms\": false\n" + " },\n" + " {\n" + " \"trans_func\": 5,\n" + " \"amount\": \"12.00\",\n" + " \"merchant_order_no\": \"BB-BATCH-20300101-002\",\n" + " \"currency\": \"AUD\",\n" + " \"bank_account\": {\n" + " \"bsb\": \"062-000\",\n" + " \"account_no\": \"618472950\",\n" + " \"account_name\": \"Emily Carter\"\n" + " },\n" + " \"process_date\": \"2030-01-15\"\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: Batch payment request source: | require "net/http" require "uri" base_url = ENV.fetch("BASE_URL").sub(%r{/+$}, "") uri = URI(base_url + "/api/v2/trans/batchDirectPay") 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", "transactions": [ { "amount": "25.50", "merchant_order_no": "BB-BATCH-20300101-001", "currency": "AUD", "trans_func": 3, "first_name": "Emily", "last_name": "Carter", "card": { "card_number": "4111111111111111", "expiration_month": "12", "expiration_year": "2030", "security_code": "123" }, "notify_email": false, "notify_sms": false }, { "trans_func": 5, "amount": "12.00", "merchant_order_no": "BB-BATCH-20300101-002", "currency": "AUD", "bank_account": { "bsb": "062-000", "account_no": "618472950", "account_name": "Emily Carter" }, "process_date": "2030-01-15" } ] } 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: BatchDirectPayRequest: type: object description: Request parameters. properties: merchant_id: type: string description: Business identifier assigned by BillBuddy. maxLength: 20 minLength: 1 transactions: type: array items: $ref: '#/components/schemas/BatchTransaction' description: >- List of 1 to 100 transactions. Ordinary per-transaction validation failures do not prevent other valid transactions from being accepted; malformed structures or processing exceptions may fail the entire batch. minItems: 1 maxItems: 100 required: - merchant_id - transactions BatchDirectPayResponse: type: object description: Success response. properties: code: type: integer description: >- 0 means batch request processing is complete. Check each accepted/rejected result; accepted does not indicate payment success. enum: - 0 message: type: string description: Response message. data: type: object description: Processing summary. properties: total: type: integer description: Number of transactions in this request. accepted: type: integer description: >- Number accepted for asynchronous processing. Does not indicate payment success. rejected: type: integer description: Number not accepted. items: type: array items: type: object description: Per-transaction processing results. properties: merchant_order_no: type: string description: Merchant order number. result: type: string description: >- Per-transaction result: accepted means accepted for asynchronous processing; rejected means not accepted. enum: - accepted - rejected reason: type: string description: Rejection reason, returned only when rejected. required: - merchant_order_no - result description: Per-transaction list in submission order. required: - total - accepted - rejected - items 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 BatchTransaction: type: object description: >- Payment request. Omitting both customer identifiers selects no-customer mode. If both customer_id and external_customer_id are provided, customer_id takes precedence. Only Visa/Mastercard/Amex cards are supported. Amount, name and card field requirements still apply to existing customers. Only operations 2/3/5 can be scheduled. is3ds and return_url are not supported by the batch endpoint; batch payments always disable 3DS. properties: trans_func: type: integer description: >- Transaction operation: 2 token payment; 3 card payment; 5 bank account payment. Batch payments do not support 1, 4 or 3DS. enum: - 2 - 3 - 5 amount: oneOf: - type: number multipleOf: 0.01 minimum: 0.01 maximum: 999999.99 - type: string pattern: ^\d+(\.\d{1,2})?$ allOf: - pattern: ^0*(?:[1-9]\d{0,5}(?:\.\d{1,2})?|0\.(?:0[1-9]|[1-9]\d?))$ description: >- 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 999999.99; the same range applies to both types. merchant_order_no: type: string description: >- Merchant order number. Must be unique within the same merchant. A duplicate request does not return an existing successful order. maxLength: 60 minLength: 1 currency: type: string description: >- Currency code, such as AUD. Currency support also depends on the merchant's payment channel configuration. minLength: 3 maxLength: 3 process_date: type: string description: >- Scheduled processing date in YYYY-MM-DD format. Must be strictly after today in the service business timezone. Supported only for trans_func=2/3/5 and cannot be combined with is3ds=1. YYYY-MM-DD is recommended. Must be later than today in the service business timezone. nullable: true format: date customer_id: type: string description: >- BillBuddy customer identifier. Must identify a valid customer within the current merchant and business. nullable: true maxLength: 32 external_customer_id: type: string description: >- Customer reference in the merchant system. Used to find the customer when customer_id is omitted. If both identifiers are provided, customer_id takes precedence. nullable: true maxLength: 64 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' card: type: object description: Credit card information. properties: card_number: type: string description: >- Visa, Mastercard or American Express card number. Acceptance depends on card brand recognition and channel configuration. Ignored for trans_func=2. Required and non-null for trans_func=3. Supply valid card details; the actual response determines the payment outcome. maxLength: 20 expiration_month: type: string description: >- Card expiry month, preferably two digits, such as 12. Ignored for trans_func=2. Required and non-null for trans_func=3. Supply valid card details; the actual response determines the payment outcome. minLength: 2 maxLength: 2 expiration_year: type: string description: >- Card expiry year, preferably four digits, such as 2030. Ignored for trans_func=2. Required and non-null for trans_func=3. Supply valid card details; the actual response determines the payment outcome. minLength: 4 maxLength: 4 security_code: type: string description: >- Card security code (CVV). Use a string to preserve leading zeros. Ignored for trans_func=2. Required and non-null for trans_func=3. Supply valid card details; the actual response determines the payment outcome. maxLength: 4 card_token: type: string description: >- Payment token returned by BillBuddy. When a customer is supplied, the token must belong to that customer. Required for trans_func=2. nullable: true maxLength: 255 bank_account: type: object description: Bank account information. properties: bsb: type: string description: >- Required for trans_func=5. Supply a valid six-digit BSB. Spaces and hyphens are permitted and excluded from the six-character length. nullable: true pattern: ^(?:[\s-]*[^\s-]){6}[\s-]*$ account_no: type: string description: >- Required for trans_func=5. Supply a valid bank account number as a string to preserve leading zeros. Spaces and hyphens are permitted. After removing these separators, the value must contain 1 to 9 characters and cannot consist solely of separators. nullable: true pattern: ^(?:[\s-]*[^\s-]){0,9}[\s-]*$ account_name: type: string description: >- Bank account holder name. Required and non-null when trans_func=5. nullable: true maxLength: 100 first_name: type: string description: >- First name. Required and non-null for trans_func=2/3; at most 50 characters. nullable: true maxLength: 50 last_name: type: string description: >- Last name. Required and non-null for trans_func=2/3; at most 50 characters. nullable: true maxLength: 50 email: type: string description: Email address. nullable: true format: email maxLength: 100 phone: type: string description: Contact phone number. nullable: true maxLength: 50 address: type: string description: Street address. nullable: true maxLength: 100 city: type: string description: City. nullable: true maxLength: 50 state: type: string description: State or province. nullable: true maxLength: 100 postcode: type: string description: Postcode. nullable: true maxLength: 8 country_iso2: type: string description: Two-letter country code, such as AU. nullable: true minLength: 2 maxLength: 2 required: - trans_func - amount - merchant_order_no - currency not: anyOf: - allOf: - required: - trans_func properties: trans_func: enum: - 2 - not: required: - card_token - first_name - last_name properties: card_token: not: enum: - null minLength: 1 first_name: not: enum: - null minLength: 1 last_name: not: enum: - null minLength: 1 - allOf: - required: - trans_func properties: trans_func: enum: - 3 - not: required: - card - first_name - last_name properties: card: not: enum: - null first_name: not: enum: - null minLength: 1 last_name: not: enum: - null minLength: 1 - allOf: - required: - trans_func properties: trans_func: enum: - 5 - not: required: - bank_account properties: bank_account: not: enum: - null - allOf: - required: - trans_func properties: trans_func: enum: - 3 - not: required: - card properties: card: not: enum: - null minProperties: 1 required: - card_number - expiration_month - expiration_year - security_code properties: card_number: not: enum: - null minLength: 1 expiration_month: not: enum: - null minLength: 1 expiration_year: not: enum: - null minLength: 1 security_code: not: enum: - null minLength: 1 - allOf: - required: - trans_func properties: trans_func: enum: - 5 - not: required: - bank_account properties: bank_account: not: enum: - null minProperties: 1 required: - bsb - account_no - account_name properties: bsb: not: enum: - null minLength: 1 account_no: not: enum: - null minLength: 1 pattern: '[^\s-]' account_name: not: enum: - null minLength: 1 - allOf: - required: - trans_func properties: trans_func: enum: - 2 - not: required: - card_token - first_name - last_name properties: card_token: not: enum: - null minLength: 1 first_name: not: enum: - null minLength: 1 last_name: not: enum: - null minLength: 1 - allOf: - required: - trans_func properties: trans_func: enum: - 3 - not: required: - first_name - last_name properties: first_name: not: enum: - null minLength: 1 last_name: not: enum: - null minLength: 1 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.