BPAY Bill Payments - Australia

Nium supports BPAY bill payments in Australia using the existing Transfer Money API. BPAY is Australia's national bill payment scheme, used by over 60,000 billers across utilities, government agencies, insurance providers, and financial services.

BPAY payments follow the same design as other Nium payouts — authentication, funding, lifecycle statuses, webhooks, and status retrieval remain unchanged. This guide covers only what is specific to BPAY: the required fields, request structure, validation rules, processing behaviour, and sandbox testing.

note

BPAY payments only support inline beneficiaries. Payouts using a pre-created beneficiaryId are not supported.

Initiating a BPAY payment

Initiate BPAY payments through the TransferMoney API by setting payoutMethod to BILL and providing the biller details in the inline beneficiary object.

Required fields

Inside `beneficiary.paymentAccount`

Field	Required	Validation	Description
`payoutMethod`	Yes	Must be `BILL`	Routes the transaction to the BPAY network
`payoutCurrency`	Yes	Must be `AUD`	Currency of the payment

Inside `payout`

Field	Required	Validation	Description
`destinationAmount`	Yes	Min `0.01`; max 2 decimal places	Amount to pay in AUD
`destinationCurrency`	Yes	Must be `AUD`

Inside `beneficiary.beneficiary`

Field	Required	Validation	Description
`accountType`	Yes	Must be `CORPORATE`	Account type for BPAY billers
`billerCode`	Yes	`^[0-9]{1,20}$`	BPAY biller code — found on the bill or from the biller directly
`billReferenceNumber`	Yes	`^[a-zA-Z0-9-\_]{1,50}$`	Customer Reference Number (CRN) printed on the bill

You can also include remitter.name (recommended) and purposeCode — use IR007 for utility payments or IR01801 for general bill payments. See Purpose Codes.

Sample request

{
  "beneficiary": {
    "beneficiary": {
      "accountType": "CORPORATE",
      "billerCode": "857763",
      "billReferenceNumber": "6279059700000505"
    },
    "paymentAccount": {
      "payoutMethod": "BILL",
      "payoutCurrency": "AUD"
    }
  },
  "payout": {
    "sourceCurrency": "USD",
    "destinationAmount": 100,
    "destinationCurrency": "AUD"
  },
  "purposeCode": "IR01801",
  "remitter": {
    "name": "John Doe"
  }
}

Sample response

{
  "message": "Transfer Initiated",
  "payment_id": null,
  "system_reference_number": "RT0886087702",
  "systemReferenceNumber": "RT0886087702"
}

Payout lifecycle

When a BPAY request passes validation and is accepted, Nium marks the transaction as PAID. This reflects that the payment has been successfully submitted to the BPAY network.

In rare cases, a transaction may subsequently move from PAID to RETURN. This typically occurs when a biller enforces strict rules such as rejecting payments after a specific date or requiring an exact amount match. Any such update is delivered through the standard status API or webhook notifications.

Step	Status	Description	Step type
1	`SCHEDULED` `AWAITING_FUNDS` `CANCELLED` `EXPIRED` `FAILED` `INITIATED` `RFI_REQUESTED` `RFI_RESPONDED` `COMPLIANCE_COMPLETED` `REJECTED` `PG_PROCESSING`	Standard payout lifecycle statuses. For definitions, see Track Payouts.	Generic
2	`PAID`	The payment has been accepted and submitted to the BPAY network.	Country-specific
3	`RETURN`	The payout was returned by the BPAY network — typically due to a biller-specific rejection rule.	Country-specific

For more information, see Payout Lifecycle and Payout Webhook Events.

Processing timelines

Submission time (Sydney time)	Processing
Before 3:30 PM on a business day	Submitted to BPAY on the same business day
After 3:30 PM, or on a non-business day	Submitted to BPAY on the next business day

After Nium submits the payment, the biller may take 2–3 additional business days to post the credit to the end customer's account. This is standard BPAY behaviour and does not indicate an issue with the transaction.

Error handling

Nium validates biller information before processing. If any detail is incorrect, the transaction fails before funds are moved and a clear error response is returned.

Nium validates:

Biller code — confirms it is a valid BPAY biller
Customer Reference Number (CRN) — ensures it matches the format expected by that biller
Amount — some billers only accept specific amounts

Scenario	Sample response
Invalid biller code or CRN	`{"status":"BAD_REQUEST","message":"Payment validation failed","errors":["VERIFICATION Biller Verification failed."]}`
Mandatory field missing	`{"status":"BAD_REQUEST","message":"PayoutCurrency is mandatory","errors":["PayoutCurrency is mandatory"]}`
Insufficient wallet funds	`{"status":"BAD_REQUEST","message":"Insufficient funds in wallet","errors":["Insufficient funds in wallet"]}`
BPAY network timeout (retryable)	`{"status":"BAD_REQUEST","message":"Payment validation failed","errors":["VERIFICATION External server error"]}`

Testing in the sandbox environment

Use the following predefined values to simulate BPAY scenarios in sandbox:

Test scenario	`billerCode`	`billReferenceNumber`	`destinationAmount`	Expected result
Successful payment	`857763`	`6279059700000505`	`100`	Transaction moves to `PAID`
Invalid biller combination	`123456`	`987654321`	`100`	Validation error at Nium
Amount not accepted by biller	`857763`	`6279059700000505`	`1`	Validation error at Nium

LLM-ready documentation:: llms.txt and llms-full.txt

Initiating a BPAY payment​

Required fields​

Inside beneficiary.paymentAccount​

Inside payout​

Inside beneficiary.beneficiary​

Sample request​

Sample response​

Payout lifecycle​

Processing timelines​

Error handling​

Testing in the sandbox environment​

Related resources​