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.

POST /api/v2/trans/batchDirectPay

cURL

cURL

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"
    }
  ]
}'

200

partial

{
  "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"
      }
    ]
  }
}

Authorizations

Authorization · string · header · required

OAuth2 client_credentials authorization. Obtain a new access_token when it expires.

Body

application/json

Request parameters.

merchant_id · string · required

Business identifier assigned by BillBuddy.

Required string length: 1 - 20

transactions · object[] · required

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.

Required array length: 1 - 100 elements

Show child attributes

Response

200

application/json

HTTP 200. Distinguish success, business errors, validation errors and business authentication errors using the response body code.

Option 1

Option 2

Success response.

code · enum<integer> · required

0 means batch request processing is complete. Check each accepted/rejected result; accepted does not indicate payment success.

Available options: 0

message · string · required

Response message.

data · object · required

Processing summary.

Show child attributes