> ## 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. # Query a TXT batch and its details > Retrieve a batch and its per-record processing results for the authenticated merchant, optionally filtered by business. Use an OAuth2 Bearer token; no request signature is required. Supply batch_id or file_identifier. When both are supplied, they must match the same batch. line_number is the logical number in a D record; record_line_no is the physical file line number including the header. Results are paginated in ascending line_number order. line_number and status filters combine, and details is always an array. Use page 1 for a single-line lookup. pagination.total counts filtered records, while summary always covers all current details in the batch. code=0 only means the lookup succeeded, even when the batch or details failed. Batch completed means transaction creation processing is complete; it does not guarantee payment success. Read both detail status and transaction_status. created_pending may also correspond to an expired transaction. details=[] can mean details are not yet available or no records match; it does not mean all payments succeeded. Transaction numbers and statuses may be null when unavailable; do not repeat payments on that basis. Use OAuth credentials for the same merchant. merchant_id may be omitted or empty to locate the batch across all businesses of that merchant; when supplied, it must match the business identifier in the original upload. This lookup only returns processing results and does not execute payments again. ## OpenAPI ````yaml /openapi/billbuddy-v2-openapi.en.yaml get /api/v2/trans/bulk-upload/result 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/bulk-upload/result: get: tags: - Transactions summary: Query a TXT batch and its details description: >- Retrieve a batch and its per-record processing results for the authenticated merchant, optionally filtered by business. Use an OAuth2 Bearer token; no request signature is required. Supply batch_id or file_identifier. When both are supplied, they must match the same batch. line_number is the logical number in a D record; record_line_no is the physical file line number including the header. Results are paginated in ascending line_number order. line_number and status filters combine, and details is always an array. Use page 1 for a single-line lookup. pagination.total counts filtered records, while summary always covers all current details in the batch. code=0 only means the lookup succeeded, even when the batch or details failed. Batch completed means transaction creation processing is complete; it does not guarantee payment success. Read both detail status and transaction_status. created_pending may also correspond to an expired transaction. details=[] can mean details are not yet available or no records match; it does not mean all payments succeeded. Transaction numbers and statuses may be null when unavailable; do not repeat payments on that basis. Use OAuth credentials for the same merchant. merchant_id may be omitted or empty to locate the batch across all businesses of that merchant; when supplied, it must match the business identifier in the original upload. This lookup only returns processing results and does not execute payments again. operationId: v2BulkUploadResult parameters: - name: merchant_id in: query required: false description: >- Optional business identifier, up to 20 characters. When supplied, it must belong to the authenticated merchant and match the target batch. Omit it or leave it empty to locate a batch across all businesses of that merchant. schema: type: string maxLength: 20 nullable: true example: '48290713' - name: batch_id in: query required: false description: >- Supply this or file_identifier; both must match the same batch when supplied together. schema: type: integer format: int64 minimum: 1 nullable: true example: 2048 - name: file_identifier in: query required: false description: >- Supply this or batch_id; both must match the same batch when supplied together. schema: type: string minLength: 10 maxLength: 10 pattern: ^[A-Za-z0-9_]{10}$ nullable: true example: PAY2030001 - name: line_number in: query required: false description: >- Filter by exact logical line number, minimum 1. Combines with status when both are supplied; details remains an array. schema: type: integer minimum: 1 nullable: true example: 2 - name: page in: query required: false description: Page number, starting at 1; defaults to 1 when omitted or null. schema: type: integer nullable: true minimum: 1 default: 1 - name: page_size in: query required: false description: Records per page, range 1–200; defaults to 50 when omitted or null. schema: type: integer minimum: 1 maximum: 200 default: 50 nullable: true - name: status in: query required: false description: >- Filter by one detail status. validation_failed: Detail validation failed; payment processing was not started; queued: Awaiting processing; processing: Processing; created_pending: Transaction created without a confirmed success or failure; the transaction may also have expired; payment_succeeded: Payment succeeded; payment_failed: Payment failed; system_failed: Processing error; verify the payment outcome. schema: type: string enum: - validation_failed - queued - processing - created_pending - payment_succeeded - payment_failed - system_failed - null nullable: true responses: '200': description: >- HTTP 200. code=0 means the lookup succeeded; code=1 indicates a business or authentication error; code=400 indicates invalid query parameters. content: application/json: schema: oneOf: - $ref: '#/components/schemas/BulkUploadResultResponse' - $ref: '#/components/schemas/PublicApiError' examples: success: summary: Batch processing complete with one payment still Pending value: code: 0 message: ok data: request_id: 09ef4182-bcd8-4bb1-a326-498a05f0e4bb batch: batch_id: 2048 upload_request_id: 19eb4182-bcd8-4bb1-a326-498a05f0e4aa merchant_id: '7294815' business_id: '48290713' file_identifier: PAY2030001 status: completed declared_detail_count: 2 declared_total_amount_cents: 7350 summary: validation_failed: 0 queued: 0 processing: 0 created_pending: 1 payment_succeeded: 1 payment_failed: 0 system_failed: 0 details: - line_number: 1 record_line_no: 2 reference_number: INV-2030-001 account_type: BC amount_cents: 2550 status: created_pending failure_reason: '' trans_no: b1893452400000826 transaction_status: 3 transaction_status_text: Pending transaction_result: '' - line_number: 2 record_line_no: 3 reference_number: INV-2030-002 account_type: CT amount_cents: 4800 status: payment_succeeded failure_reason: '' trans_no: b1893452400000972 transaction_status: 1 transaction_status_text: Successful transaction_result: '' pagination: page: 1 page_size: 50 total: 2 last_page: 1 awaitingDetails: summary: File accepted; details are not yet available value: code: 0 message: ok data: request_id: 09ef4182-bcd8-4bb1-a326-498a05f0e4bb batch: batch_id: 2048 upload_request_id: 19eb4182-bcd8-4bb1-a326-498a05f0e4aa merchant_id: '7294815' business_id: '48290713' file_identifier: PAY2030001 status: received declared_detail_count: 2 declared_total_amount_cents: 7350 summary: validation_failed: 0 queued: 0 processing: 0 created_pending: 0 payment_succeeded: 0 payment_failed: 0 system_failed: 0 details: [] pagination: page: 1 page_size: 50 total: 0 last_page: 1 paymentFailed: summary: Transaction creation complete, with one payment failed value: code: 0 message: ok data: request_id: 09ef4182-bcd8-4bb1-a326-498a05f0e4bb batch: batch_id: 2048 upload_request_id: 19eb4182-bcd8-4bb1-a326-498a05f0e4aa merchant_id: '7294815' business_id: '48290713' file_identifier: PAY2030001 status: completed declared_detail_count: 2 declared_total_amount_cents: 7350 summary: validation_failed: 0 queued: 0 processing: 0 created_pending: 1 payment_succeeded: 0 payment_failed: 1 system_failed: 0 details: - line_number: 1 record_line_no: 2 reference_number: INV-2030-001 account_type: BC amount_cents: 2550 status: created_pending failure_reason: '' trans_no: b1893452400000826 transaction_status: 3 transaction_status_text: Pending transaction_result: '' - line_number: 2 record_line_no: 3 reference_number: INV-2030-002 account_type: CT amount_cents: 4800 status: payment_failed failure_reason: Payment failed trans_no: b1893452400000972 transaction_status: 2 transaction_status_text: Failed transaction_result: Payment failed pagination: page: 1 page_size: 50 total: 2 last_page: 1 invalidDetail: summary: >- A detail failed validation and has no transaction information value: code: 0 message: ok data: request_id: 09ef4182-bcd8-4bb1-a326-498a05f0e4bb batch: batch_id: 2048 upload_request_id: 19eb4182-bcd8-4bb1-a326-498a05f0e4aa merchant_id: '7294815' business_id: '48290713' file_identifier: PAY2030001 status: partially_completed declared_detail_count: 2 declared_total_amount_cents: 7350 summary: validation_failed: 1 queued: 0 processing: 0 created_pending: 1 payment_succeeded: 0 payment_failed: 0 system_failed: 0 details: - line_number: 1 record_line_no: 2 reference_number: INV-2030-001 account_type: BC amount_cents: 2550 status: created_pending failure_reason: '' trans_no: b1893452400000826 transaction_status: 3 transaction_status_text: Pending transaction_result: '' - line_number: 2 record_line_no: 3 reference_number: INV-2030-002 account_type: CT amount_cents: 4800 status: validation_failed failure_reason: Payment method not found for token trans_no: null transaction_status: null transaction_status_text: null transaction_result: '' pagination: page: 1 page_size: 50 total: 2 last_page: 1 singleLine: summary: >- line_number=2 returns one detail; summary still covers the full batch value: code: 0 message: ok data: request_id: 09ef4182-bcd8-4bb1-a326-498a05f0e4bb batch: batch_id: 2048 upload_request_id: 19eb4182-bcd8-4bb1-a326-498a05f0e4aa merchant_id: '7294815' business_id: '48290713' file_identifier: PAY2030001 status: completed declared_detail_count: 2 declared_total_amount_cents: 7350 summary: validation_failed: 0 queued: 0 processing: 0 created_pending: 1 payment_succeeded: 1 payment_failed: 0 system_failed: 0 details: - line_number: 2 record_line_no: 3 reference_number: INV-2030-002 account_type: CT amount_cents: 4800 status: payment_succeeded failure_reason: '' trans_no: b1893452400000972 transaction_status: 1 transaction_status_text: Successful transaction_result: '' pagination: page: 1 page_size: 50 total: 1 last_page: 1 noMatchingDetails: summary: No details match the filters value: code: 0 message: ok data: request_id: 09ef4182-bcd8-4bb1-a326-498a05f0e4bb batch: batch_id: 2048 upload_request_id: 19eb4182-bcd8-4bb1-a326-498a05f0e4aa merchant_id: '7294815' business_id: '48290713' file_identifier: PAY2030001 status: completed declared_detail_count: 2 declared_total_amount_cents: 7350 summary: validation_failed: 0 queued: 0 processing: 0 created_pending: 1 payment_succeeded: 1 payment_failed: 0 system_failed: 0 details: [] pagination: page: 1 page_size: 50 total: 0 last_page: 1 notFound: summary: Transaction not found value: code: 1 message: Batch not found data: {} validation: summary: Invalid query parameters value: code: 400 message: The page size field must not be greater than 200. data: {} unauthenticated: summary: Authentication failed 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. security: - oauth2: [] x-codeSamples: - lang: Shell label: Look up by file identifier source: |- curl --get "${BASE_URL}/api/v2/trans/bulk-upload/result" \ -H "Authorization: Bearer ${ACCESS_TOKEN}" \ -H "Accept: application/json" \ --data-urlencode merchant_id=48290713 \ --data-urlencode file_identifier=PAY2030001 - lang: Shell label: Filter by status and paginate a batch source: |- curl --get "${BASE_URL}/api/v2/trans/bulk-upload/result" \ -H "Authorization: Bearer ${ACCESS_TOKEN}" \ -H "Accept: application/json" \ --data-urlencode merchant_id=48290713 \ --data-urlencode batch_id=2048 \ --data-urlencode status=created_pending \ --data-urlencode page=1 \ --data-urlencode page_size=50 - lang: Shell label: Look up one detail source: |- curl --get "${BASE_URL}/api/v2/trans/bulk-upload/result" \ -H "Authorization: Bearer ${ACCESS_TOKEN}" \ -H "Accept: application/json" \ --data-urlencode merchant_id=48290713 \ --data-urlencode batch_id=2048 \ --data-urlencode line_number=2 \ --data-urlencode page=1 - lang: Python label: Look up by file identifier source: > import json import os import urllib.parse import urllib.request base_url = os.environ["BASE_URL"].rstrip("/") url = base_url + "/api/v2/trans/bulk-upload/result" headers = {"Accept": "application/json"} headers["Authorization"] = "Bearer " + os.environ["ACCESS_TOKEN"] params = { "merchant_id": "48290713", "file_identifier": "PAY2030001", } url += "?" + urllib.parse.urlencode(params) body = None request = urllib.request.Request(url, data=body, headers=headers, method="GET") with urllib.request.urlopen(request, timeout=30) as response: print(response.read().decode("utf-8")) - lang: Python label: Filter by status and paginate a batch source: > import json import os import urllib.parse import urllib.request base_url = os.environ["BASE_URL"].rstrip("/") url = base_url + "/api/v2/trans/bulk-upload/result" headers = {"Accept": "application/json"} headers["Authorization"] = "Bearer " + os.environ["ACCESS_TOKEN"] params = { "merchant_id": "48290713", "batch_id": "2048", "status": "created_pending", "page": "1", "page_size": "50", } url += "?" + urllib.parse.urlencode(params) body = None request = urllib.request.Request(url, data=body, headers=headers, method="GET") with urllib.request.urlopen(request, timeout=30) as response: print(response.read().decode("utf-8")) - lang: Python label: Look up one detail source: > import json import os import urllib.parse import urllib.request base_url = os.environ["BASE_URL"].rstrip("/") url = base_url + "/api/v2/trans/bulk-upload/result" headers = {"Accept": "application/json"} headers["Authorization"] = "Bearer " + os.environ["ACCESS_TOKEN"] params = { "merchant_id": "48290713", "batch_id": "2048", "line_number": "2", "page": "1", } url += "?" + urllib.parse.urlencode(params) body = None request = urllib.request.Request(url, data=body, headers=headers, method="GET") with urllib.request.urlopen(request, timeout=30) as response: print(response.read().decode("utf-8")) - lang: JavaScript label: Look up by file identifier 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/bulk-upload/result"); const headers = { Accept: "application/json" }; headers.Authorization = `Bearer ${env("ACCESS_TOKEN")}`; const params = new URLSearchParams({ "merchant_id": "48290713", "file_identifier": "PAY2030001", }); url.search = params.toString(); const response = await fetch(url, { method: "GET", headers, signal: AbortSignal.timeout(30_000), }); console.log(await response.text()); - lang: JavaScript label: Filter by status and paginate a batch 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/bulk-upload/result"); const headers = { Accept: "application/json" }; headers.Authorization = `Bearer ${env("ACCESS_TOKEN")}`; const params = new URLSearchParams({ "merchant_id": "48290713", "batch_id": "2048", "status": "created_pending", "page": "1", "page_size": "50", }); url.search = params.toString(); const response = await fetch(url, { method: "GET", headers, signal: AbortSignal.timeout(30_000), }); console.log(await response.text()); - lang: JavaScript label: Look up one detail 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/bulk-upload/result"); const headers = { Accept: "application/json" }; headers.Authorization = `Bearer ${env("ACCESS_TOKEN")}`; const params = new URLSearchParams({ "merchant_id": "48290713", "batch_id": "2048", "line_number": "2", "page": "1", }); url.search = params.toString(); const response = await fetch(url, { method: "GET", headers, signal: AbortSignal.timeout(30_000), }); console.log(await response.text()); - lang: PHP label: Look up by file identifier source: | "48290713", "file_identifier" => "PAY2030001", ]; $url .= '?' . http_build_query($params, '', '&', PHP_QUERY_RFC3986); $curl = curl_init($url); curl_setopt_array($curl, [ CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => $headers, CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30, ]); $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: Filter by status and paginate a batch source: | "48290713", "batch_id" => "2048", "status" => "created_pending", "page" => "1", "page_size" => "50", ]; $url .= '?' . http_build_query($params, '', '&', PHP_QUERY_RFC3986); $curl = curl_init($url); curl_setopt_array($curl, [ CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => $headers, CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30, ]); $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: Look up one detail source: | "48290713", "batch_id" => "2048", "line_number" => "2", "page" => "1", ]; $url .= '?' . http_build_query($params, '', '&', PHP_QUERY_RFC3986); $curl = curl_init($url); curl_setopt_array($curl, [ CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => $headers, CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30, ]); $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: Look up by file identifier source: | package main import ( "fmt" "io" "net/http" "net/url" "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/bulk-upload/result" params := url.Values{} params.Set("merchant_id", "48290713") params.Set("file_identifier", "PAY2030001") endpoint += "?" + params.Encode() req, err := http.NewRequest("GET", endpoint, nil) if err != nil { panic(err) } req.Header.Set("Accept", "application/json") req.Header.Set("Authorization", "Bearer " + mustEnv("ACCESS_TOKEN")) 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: Filter by status and paginate a batch source: | package main import ( "fmt" "io" "net/http" "net/url" "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/bulk-upload/result" params := url.Values{} params.Set("merchant_id", "48290713") params.Set("batch_id", "2048") params.Set("status", "created_pending") params.Set("page", "1") params.Set("page_size", "50") endpoint += "?" + params.Encode() req, err := http.NewRequest("GET", endpoint, nil) if err != nil { panic(err) } req.Header.Set("Accept", "application/json") req.Header.Set("Authorization", "Bearer " + mustEnv("ACCESS_TOKEN")) 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: Look up one detail source: | package main import ( "fmt" "io" "net/http" "net/url" "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/bulk-upload/result" params := url.Values{} params.Set("merchant_id", "48290713") params.Set("batch_id", "2048") params.Set("line_number", "2") params.Set("page", "1") endpoint += "?" + params.Encode() req, err := http.NewRequest("GET", endpoint, nil) if err != nil { panic(err) } req.Header.Set("Accept", "application/json") req.Header.Set("Authorization", "Bearer " + mustEnv("ACCESS_TOKEN")) 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: Look up by file identifier 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/bulk-upload/result"; Map params = new LinkedHashMap<>(); params.put("merchant_id", "48290713"); params.put("file_identifier", "PAY2030001"); String encoded = params.entrySet().stream() .map(e -> URLEncoder.encode(e.getKey(), StandardCharsets.UTF_8) + "=" + URLEncoder.encode(e.getValue(), StandardCharsets.UTF_8)) .collect(Collectors.joining("&")); endpoint += "?" + encoded; HttpRequest.Builder builder = HttpRequest.newBuilder(URI.create(endpoint)) .timeout(Duration.ofSeconds(30)) .header("Accept", "application/json"); builder.header("Authorization", "Bearer " + requireEnv("ACCESS_TOKEN")); HttpRequest request = builder.method("GET", HttpRequest.BodyPublishers.noBody()).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: Filter by status and paginate a batch 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/bulk-upload/result"; Map params = new LinkedHashMap<>(); params.put("merchant_id", "48290713"); params.put("batch_id", "2048"); params.put("status", "created_pending"); params.put("page", "1"); params.put("page_size", "50"); String encoded = params.entrySet().stream() .map(e -> URLEncoder.encode(e.getKey(), StandardCharsets.UTF_8) + "=" + URLEncoder.encode(e.getValue(), StandardCharsets.UTF_8)) .collect(Collectors.joining("&")); endpoint += "?" + encoded; HttpRequest.Builder builder = HttpRequest.newBuilder(URI.create(endpoint)) .timeout(Duration.ofSeconds(30)) .header("Accept", "application/json"); builder.header("Authorization", "Bearer " + requireEnv("ACCESS_TOKEN")); HttpRequest request = builder.method("GET", HttpRequest.BodyPublishers.noBody()).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: Look up one detail 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/bulk-upload/result"; Map params = new LinkedHashMap<>(); params.put("merchant_id", "48290713"); params.put("batch_id", "2048"); params.put("line_number", "2"); params.put("page", "1"); String encoded = params.entrySet().stream() .map(e -> URLEncoder.encode(e.getKey(), StandardCharsets.UTF_8) + "=" + URLEncoder.encode(e.getValue(), StandardCharsets.UTF_8)) .collect(Collectors.joining("&")); endpoint += "?" + encoded; HttpRequest.Builder builder = HttpRequest.newBuilder(URI.create(endpoint)) .timeout(Duration.ofSeconds(30)) .header("Accept", "application/json"); builder.header("Authorization", "Bearer " + requireEnv("ACCESS_TOKEN")); HttpRequest request = builder.method("GET", HttpRequest.BodyPublishers.noBody()).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: Look up by file identifier source: | require "net/http" require "uri" base_url = ENV.fetch("BASE_URL").sub(%r{/+$}, "") uri = URI(base_url + "/api/v2/trans/bulk-upload/result") params = { "merchant_id" => "48290713", "file_identifier" => "PAY2030001", } uri.query = URI.encode_www_form(params) request = Net::HTTP::Get.new(uri) request["Accept"] = "application/json" request["Authorization"] = "Bearer " + ENV.fetch("ACCESS_TOKEN") 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: Filter by status and paginate a batch source: | require "net/http" require "uri" base_url = ENV.fetch("BASE_URL").sub(%r{/+$}, "") uri = URI(base_url + "/api/v2/trans/bulk-upload/result") params = { "merchant_id" => "48290713", "batch_id" => "2048", "status" => "created_pending", "page" => "1", "page_size" => "50", } uri.query = URI.encode_www_form(params) request = Net::HTTP::Get.new(uri) request["Accept"] = "application/json" request["Authorization"] = "Bearer " + ENV.fetch("ACCESS_TOKEN") 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: Look up one detail source: | require "net/http" require "uri" base_url = ENV.fetch("BASE_URL").sub(%r{/+$}, "") uri = URI(base_url + "/api/v2/trans/bulk-upload/result") params = { "merchant_id" => "48290713", "batch_id" => "2048", "line_number" => "2", "page" => "1", } uri.query = URI.encode_www_form(params) request = Net::HTTP::Get.new(uri) request["Accept"] = "application/json" request["Authorization"] = "Bearer " + ENV.fetch("ACCESS_TOKEN") 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: BulkUploadResultResponse: type: object properties: code: type: integer description: >- Lookup succeeded; code is still 0 when the batch or individual details have failed. enum: - 0 message: type: string description: Result message; ok on success. example: ok data: type: object properties: request_id: type: string description: >- Tracking identifier for this request; provide it to BillBuddy when requesting assistance. batch: type: object properties: batch_id: type: integer description: Batch identifier for subsequent lookups. format: int64 minimum: 1 upload_request_id: type: string description: >- Tracking identifier for the original upload, distinct from this lookup request_id. merchant_id: type: string description: Merchant identifier associated with the batch. business_id: type: string description: Business identifier associated with the batch. file_identifier: type: string description: >- Ten-character identifier from the file header; letters, digits and underscores only. minLength: 10 maxLength: 10 pattern: ^[A-Za-z0-9_]{10}$ status: type: string description: >- Batch processing status: validation_failed = file format rejected; received = accepted; processing = in progress; completed = transaction creation processing complete; partially_completed = some records could not create transactions; system_failed = batch processing error. completed may still include pending or failed payments. enum: - validation_failed - received - processing - completed - partially_completed - system_failed declared_detail_count: type: integer description: >- Detail count declared in the file trailer; may be 0 for a rejected file. minimum: 0 declared_total_amount_cents: type: integer description: >- Total base amount declared in the file trailer, in cents, excluding surcharges; may be 0 for a rejected file. format: int64 minimum: 0 required: - batch_id - upload_request_id - merchant_id - business_id - file_identifier - status - declared_detail_count - declared_total_amount_cents additionalProperties: false description: Batch information. summary: type: object properties: validation_failed: type: integer description: >- Number of details in the full batch with status validation_failed (detail validation failed; payment processing was not started); unaffected by filtering or pagination. minimum: 0 queued: type: integer description: >- Number of details in the full batch with status queued (awaiting processing); unaffected by filtering or pagination. minimum: 0 processing: type: integer description: >- Number of details in the full batch with status processing (processing); unaffected by filtering or pagination. minimum: 0 created_pending: type: integer description: >- Number of details in the full batch with status created_pending (transaction created without a confirmed success or failure; the transaction may also have expired); unaffected by filtering or pagination. minimum: 0 payment_succeeded: type: integer description: >- Number of details in the full batch with status payment_succeeded (payment succeeded); unaffected by filtering or pagination. minimum: 0 payment_failed: type: integer description: >- Number of details in the full batch with status payment_failed (payment failed); unaffected by filtering or pagination. minimum: 0 system_failed: type: integer description: >- Number of details in the full batch with status system_failed (processing error; verify the payment outcome); unaffected by filtering or pagination. minimum: 0 required: - validation_failed - queued - processing - created_pending - payment_succeeded - payment_failed - system_failed additionalProperties: false description: >- Detail status counts for the entire batch, unaffected by filters or pagination. details: type: array description: >- Filtered and paginated details in ascending logical line order; empty when no details are currently available. items: type: object properties: line_number: type: integer description: >- Logical detail number, starting at 1; positions 115–120 of a D record. minimum: 1 record_line_no: type: integer description: >- Physical line number in the original file, starting at 1 and including the header. minimum: 1 reference_number: type: string description: >- Business reference with trailing padding removed; may be empty for an invalid record. maxLength: 16 account_type: type: string description: >- Record payment type: BC for a bank account, CT for a payment token; invalid records may contain other values. maxLength: 2 amount_cents: type: integer description: >- Base amount in cents, excluding surcharge. Valid values are 1–999999; invalid records may return 0 or an out-of-range value. format: int64 minimum: 0 status: type: string description: >- validation_failed: Detail validation failed; payment processing was not started; queued: Awaiting processing; processing: Processing; created_pending: Transaction created without a confirmed success or failure; the transaction may also have expired; payment_succeeded: Payment succeeded; payment_failed: Payment failed; system_failed: Processing error; verify the payment outcome. enum: - validation_failed - queued - processing - created_pending - payment_succeeded - payment_failed - system_failed failure_reason: type: string description: >- Public failure reason. Validation failures return a field error or Detail validation failed; payment failures return Payment failed; processing errors return System processing error; otherwise an empty string. trans_no: type: string description: >- BillBuddy transaction number for this detail; null when unavailable. This does not establish that another payment is safe. nullable: true transaction_status: type: integer description: >- Associated transaction status: 1 Successful, 2 Failed, 3 Pending, 4 Expired; null when unavailable. Unrecognized numeric values may be returned. nullable: true transaction_status_text: type: string description: >- Successful, Failed, Pending, Expired or Unknown; null when transaction information is unavailable. nullable: true transaction_result: type: string description: >- Payment failed for a failed transaction; an empty string otherwise. enum: - '' - Payment failed required: - line_number - record_line_no - reference_number - account_type - amount_cents - status - failure_reason - trans_no - transaction_status - transaction_status_text - transaction_result additionalProperties: false pagination: type: object properties: page: type: integer description: Current page number, starting at 1. minimum: 1 page_size: type: integer description: Records per page; default 50, range 1–200. minimum: 1 maximum: 200 total: type: integer description: Total detail count after applying filters. minimum: 0 last_page: type: integer description: Total pages; 1 when no details match. minimum: 1 required: - page - page_size - total - last_page additionalProperties: false description: Pagination for the current filtered result. required: - request_id - batch - summary - details - pagination additionalProperties: false description: Response data. required: - code - message - data additionalProperties: false PublicApiError: type: object properties: code: type: integer description: >- 1 for business or authentication errors; 400 for parameter or file property validation errors. enum: - 1 - 400 message: type: string description: Error reason; exact wording depends on the failure. data: description: >- Empty object for business or validation errors; empty array for authentication failures. oneOf: - type: object additionalProperties: false - type: array items: {} maxItems: 0 required: - code - message - data additionalProperties: false 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.