Create a bank account

post

https://api.sandbox.audd.digital/bank-accounts

Creates a bank account for your company. The same endpoint creates both kinds of account used by the deposit and withdrawal flows, and subType selects which:

subType DEPOSIT, using the bankProviderType value AUDD issues you during onboarding, creates an internal virtual account that receives AUD. The provider allocates bsb, accountNumber, iban and reference, so do not send bank details yourself.
subType WITHDRAWAL with bankProviderType NONE records an external account that AUDD pays out to. You must supply the bank details, and should supply internalBankAccountId to link it to the virtual account holding the funds.

Any other bankProviderType value belongs to a legacy integration and is not available.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

companyId

string

required

Your distributor company id.

nickname

string

required

length ≤ 255

A friendly name for the account. Required. Printable ASCII only.

currency

string

enum

Defaults to AUD

Defaults to AUD when omitted.

Allowed:

type

string

enum

Defaults to DISTRIBUTOR

DISTRIBUTOR, which is also the default when omitted. Other account types exist for AUDD-internal use and are not available to client integrations.

Allowed:

subType

string

enum

Required. DEPOSIT creates an internal virtual account that receives AUD; WITHDRAWAL records an external account AUDD pays out to. Accounts representing the parties who send you funds are created automatically when a deposit arrives, and are not created through this endpoint.

Allowed:

bankProviderType

string

Required. For a DEPOSIT virtual account, use the value AUDD issues you during onboarding; the provider then allocates the bank details. For an external WITHDRAWAL or REMITTER account whose details you supply yourself, use NONE.

bsb

string

^[0-9]{3}-[0-9]{3}$

Australian BSB, including the hyphen. Mutually exclusive with swiftCode. Required, with accountNumber, for a domestic external account. Do not send for a DEPOSIT virtual account: the provider allocates it.

accountNumber

string

^[0-9]+$

Account number, digits only. Do not send for a DEPOSIT virtual account.

swiftCode

string

length ≤ 255

^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$

SWIFT/BIC for an international account. Mutually exclusive with bsb, and must be accompanied by iban or accountNumber.

iban

string

length ≤ 255

^[A-Z]{2}[0-9]{2}[A-Z0-9]{11,30}$

IBAN for an international account, used with swiftCode.

internalBankAccountId

string

For subType WITHDRAWAL, the id of the DEPOSIT virtual account this withdrawal account is linked to, so proceeds settle against the right account. Not currently enforced when bankProviderType is NONE, but supply it: the withdrawal flow depends on the link.

accountHolderName

string

length ≤ 255

Full account holder name for an external account. Used as the preferred creditor name on outgoing payments; when absent, accountHolderFirstname and accountHolderLastname are used, then nickname. On a DEPOSIT virtual account it must also be at most 35 characters and use only letters, digits, / - ? : ( ) . ' and spaces, with no leading space.

accountHolderFirstname

string

length ≤ 255

Given name of the underlying customer. Required for a DEPOSIT virtual account, and optional otherwise. Must match the name on the bank account that will send funds, or deposits may not clear. On a DEPOSIT virtual account: at most 35 characters, only letters, digits, / - ? : ( ) . ' and spaces, no leading space, and critically the provider also caps accountHolderFirstname plus a space plus accountHolderLastname at 35 characters combined. Exceeding the combined limit passes local validation and is then rejected upstream with messageKey bank_account.invalid_customer_details.

accountHolderLastname

string

length ≤ 255

Family name of the underlying customer. Required for a DEPOSIT virtual account, and optional otherwise. Same character, length and combined-name rules as accountHolderFirstname.

addressLine1

string

length ≤ 255

Street address of the underlying customer. On a DEPOSIT virtual account: at most 35 characters, only letters, digits, / - ? : ( ) . ' and spaces, and no leading space. Other account types allow up to 255 characters with no character restriction.

addressLine2

string

length ≤ 255

City and postcode of the underlying customer. Same 35-character and character-set rules as addressLine1 on a DEPOSIT virtual account.

addressLine3

string

length ≤ 255

Country of the underlying customer. On a DEPOSIT virtual account this must be an uppercase ISO 3166-1 alpha-2 code: a country name, a three-letter code or a lowercase code is rejected. The rule is not enforced on other account types, but send a valid code regardless. Take care not to put a state abbreviation here, which would be read as the wrong country.

customerId

string

Optional id of the customer this account belongs to.

payId

string

PayID for the account. Has no effect on provider-issued virtual accounts. Must be unique.

Headers

Authorization

string

required

Bearer JWT obtained from POST /mfa/login. Send as "Bearer ". Expires after 5 minutes.

Responses

400

Invalid input. The body carries a messageKey identifying the rule that failed: bank_account.company_required, bank_account.nickname_required, bank_account.bank_provider_type_required, bank_account.sub_type_required, bank_account.bank_details_required (bankProviderType NONE or subType WITHDRAWAL must carry bsb, or swiftCode with iban or accountNumber), bank_account.bsb_and_swift_mutually_exclusive, bank_account.invalid_bsb_format, bank_account.invalid_account_number, bank_account.invalid_swift_code, bank_account.invalid_iban.

A DEPOSIT virtual account additionally validates customer details, and those failures return an errors array of {field, messageKey, message} objects naming each offending field, with messageKey carrying the human-readable reason rather than a dotted key. Customer details rejected by the provider rather than locally, such as a combined account holder name over 35 characters, return messageKey bank_account.invalid_customer_details with the provider's own message.

401

Unauthorized. The bearer token is missing, expired or invalid.

404

Not found. The companyId, or an internalBankAccountId that was supplied, does not resolve to a record you can see.

409

Bank account already exists. Returned with messageKey bank_account.pay_id_already_exists when the payId is already in use by another account. Note that a duplicate bsb and accountNumber pair is currently accepted on create rather than rejected here.

500

Internal server error

200Success. The account is created and returned. Note that this endpoint returns 200 rather than 201.