Create a direct payment

Parameters by transaction operation

Every operation requires trans_func, merchant_id, amount, merchant_order_no and currency. Add the conditional fields below, including when using an existing customer.

trans_func	Operation	Additional required fields
1	Create a token without charging	card.card_number, card.expiration_month, card.expiration_year, card.security_code, first_name, last_name
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
4	Create checkout	return_url
5	Bank account payment	bank_account.bsb, bank_account.account_no, bank_account.account_name; do not supply a non-empty card

is3ds=1 also requires return_url. process_date supports only operations 2, 3 and 5, must be strictly after today in the business timezone, and cannot be combined with is3ds=1. See each field for types, lengths and value limits.

Supports payment token creation, token payments, card payments, hosted checkout and bank account payments. Scheduling is not allowed when is3ds=1. Display the HTML to guide customer authentication only when response data.html is nonempty. If html is empty, handle the returned status; do not assume an authentication page is required. Do not submit a nonempty card when trans_func=5. The processing date must be strictly after today in the service business timezone. data.sign is the response signature; example 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. Example signatures are not valid for real transactions. A payment failure returns top-level code=1, and data contains no transaction details.

A declined payment or failed 3DS authentication returns top-level code=1 and data=[]. See message for the reason. Do not read data.status as if this were a success response.

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/directPay

cURL

Immediate card payment

curl -X POST "${BASE_URL}/api/v2/trans/directPay" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "merchant_id": "48290713",
  "amount": "25.50",
  "merchant_order_no": "BB-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
}'

200

success

{
  "code": 0,
  "message": "ok",
  "data": {
    "business_id": "7294815",
    "merchant_id": "48290713",
    "order_number": "b1893452400000741",
    "merchant_order_no": "BB-20300101-001",
    "trans_func": 3,
    "complete_date": "01/01/2030 10:00:00",
    "currency": "AUD",
    "amount": "25.50",
    "html": "",
    "card_token": "",
    "status": 1,
    "code": 0,
    "remark": "Approved",
    "sign_type": "SHA256",
    "sign": "fc6d0b575bb56a05607a71a8b78fecae9ba07275626bde9d0afed3f959c3910b"
  }
}

Authorizations

Authorization · string · header · required

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

Body

application/json

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.

trans_func · enum<integer> · required

Transaction operation: 1 create a token without charging; 2 token payment; 3 card payment; 4 create a checkout session; 5 bank account payment.

Available options: 1, 2, 3, 4, 5

merchant_id · string · required

Business identifier assigned by BillBuddy.

Required string length: 1 - 20

amount · number string · required

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.

Required range: 0.01 <= x <= 999999.99Must be a multiple of 0.01

merchant_order_no · string · required

Merchant order number. Must be unique within the same merchant. A duplicate request does not return an existing successful order.

Required string length: 1 - 60

currency · string · required

Currency code, such as AUD. Currency support also depends on the merchant's payment channel configuration.

Required string length: 3

card · object

Credit card information.

Show child attributes

card_token · string | null

Payment token returned by BillBuddy. When a customer is supplied, the token must belong to that customer. Required for trans_func=2.

Maximum string length: 255

first_name · string | null

First name. Required for trans_func=1/2/3.

Maximum string length: 50

last_name · string | null

Last name. Required for trans_func=1/2/3.

Maximum string length: 50

email · string<email> | null

Email address.

Maximum string length: 100

phone · string | null

Contact phone number.

Maximum string length: 50

address · string | null

Street address.

Maximum string length: 100

city · string | null

City.

Maximum string length: 50

state · string | null

State or province.

Maximum string length: 100

postcode · string | null

Postcode.

Maximum string length: 4

country_iso2 · string | null

Two-letter country code, such as AU.

Required string length: 2

is3ds · enum<integer> | null · default: 0

Whether to use 3DS: 0 disabled, 1 enabled; omission means 0. Bank account payments do not perform 3DS. Whether to display an authentication page depends on response data.html.

Available options: 1, 0, null

return_url · string | null

Return URL after 3DS authentication or checkout completion. Required when is3ds=1 or trans_func=4. Provide a valid return URL; see the schema for its length limit.

Maximum string length: 255

customer_id · string | null

BillBuddy customer identifier. Must identify a valid customer within the current merchant and business.

Maximum string length: 32

external_customer_id · string | null

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.

Maximum string length: 64

notify_email · boolean enum<integer> enum<string>

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".

notify_sms · boolean enum<integer> enum<string>

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".

bank_account · object

Bank account information.

Show child attributes

process_date · string<date> | null

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.

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 the API request was processed successfully. Token creation, checkout, 3DS and Pending results do not indicate a completed charge; assess data as well.

Available options: 0

message · string · required

Response message.

data · object · required

Payment data or checkout session, depending on the transaction operation.

Option 1

Option 2

Show child attributes