💰 Deposit AUD (Creating Virtual Accounts)

To mint AUDD, you’ll first need to send Australian dollars (AUD) to the AUDD Mint. This process involves creating a Virtual Account (VA) to deposit funds to. Once cleared, your AUD is made available for Minting requests across supported blockchains.

🪄 Create a Virtual Account

Before you can deposit AUD into the Mint, you’ll need to have an active VA set up with a deposit bank account assigned. When creating the VA, you'll be requested to include the senders name as part of this process.

❗️
Name Matching:
The VA accountHolderName/accountHolderFirstname and accountHolderLastName you specify must match the account name sending the payment. If the names don’t align, the deposit will not clear. See our Transaction Monitoring guidance for more information.

To create the VA, use the POST /bank-accounts API endpoint and provide the required details in the request body:

Field	Type	Required	Description
`companyId`	string	✅	The ID of the company creating the bank account. Retrieved from `GET /company`
`bsb`	string	❌	The BSB (Bank State Branch) number for the VA generated.
`accountNumber`	string	❌	The account number for the VA generated.
`payId`	string	❌	coming soon will return blank
`nickname`	string	✅	A friendly label to identify the VA in the Mint (i.e: UUID assigned by your system).
`currency`	string	✅	The account currency. Currently only `AUD` is supported.
`type`	string	✅	Must be set to `DISTRIBUTOR` for distributor-linked accounts.
`subType`	string	✅	Specifies account purpose. Use `DEPOSIT` to create a VA for the purpose of receiving deposits.
`bankProviderType`	string	✅	The provider type for the bank account. Typically `BANKING_CIRCLE`.
`accountHolderName`	string	❌	Company name of the account holder
`accountHolderFirstname`	string	❌	First name of the account holder. Required if creating an account with bank provider type of `BANKING_CIRCLE`
`accountHolderLastname`	string	❌	Last name of the account holder. Required if creating an account with bank provider type of `BANKING_CIRCLE`
`addressLine1`	string	❌	The street address of the customer associated with the account e.g. 123 Example Street. Required if creating an account with bank provider type of `BANKING_CIRCLE`
`addressLine2`	string	❌	The City and Zipcode of the customer associated with the account e.g. Sydney 2000. Required if creating an account with bank provider type of `BANKING_CIRCLE`
`addressLine3`	string	❌	The country code of the underlying customer associated with the account e.g. AU. Required if creating an account with bank provider type of `BANKING_CIRCLE`

📘
Required Customer Detail Fields
The accountHolderFirstname, accountHolderLastname, addressLine1, addressLine2 and addressLine3 fields are required if creating a deposit account with a bank provider type of BANKING_CIRCLE. These fields are passed on to Banking Circle when creating the account as per these docs

✅ Customer Detail Validation

When bankProviderType is BANKING_CIRCLE, the customer-detail fields are validated before the account is created, and the request is rejected with 400 Bad Request (naming the offending field) if any rule fails. The same field-level rules are applied wherever these details are later changed via the Updating Customer Details (PATCH) endpoint below, so a value accepted at creation will also be accepted on update.

Field	Required (`BANKING_CIRCLE`)	Rules
`accountHolderName`	❌ optional	If supplied: allowed characters only; no leading space; max 35 characters.
`accountHolderFirstname`	✅	Must be non-blank; allowed characters only; no leading space; max 35 characters.
`accountHolderLastname`	✅	Must be non-blank; allowed characters only; no leading space; max 35 characters.
`addressLine1`	✅	Must be non-blank; allowed characters only; no leading space; max 35 characters.
`addressLine2`	✅	Must be non-blank; allowed characters only; no leading space; max 35 characters.
`addressLine3`	✅	Must be a valid ISO 3166-1 alpha-2 country code — exactly two uppercase letters, e.g. `AU`.

📘
Allowed characters
accountHolderName, accountHolderFirstname, accountHolderLastname, addressLine1 and addressLine2 may contain only:

letters A–Z / a–z,

digits 0–9,

spaces, and

the symbols / - ? : ( ) . ' +

Values must not begin with a space and are capped at 35 characters (measured after trimming). These constraints come from Banking Circle's customer-detail format — characters outside this set (for example , _ &, or accented letters) and values longer than 35 characters are rejected. addressLine3 is the exception: it must be a two-letter uppercase country code rather than free text.

🚧
Validation only runs for Banking Circle accounts
These customer-detail rules apply only when bankProviderType is BANKING_CIRCLE. For other provider types the fields are not required and are not format-checked. Because named-account Virtual Accounts are always created with bankProviderType BANKING_CIRCLE, the rules above always apply to them.

📤 Example Request

{
    "companyId": "b8763ec9-3218-42f9-9baf-51706cff8bfd",
    "bsb": "",
    "accountNumber": "",
    "payId": "",
    "nickname": "UUID 846685458641",
    "currency": "AUD",
    "type": "DISTRIBUTOR",
    "subType": "DEPOSIT",
    "bankProviderType": "BANKING_CIRCLE",
    "accountHolderName": "KANGAROO PTY LTD",
    "accountHolderFirstname": "JOHN",
    "accountHolderLastname": "HOWARD",
    "addressLine1": "123 Example Street",
    "addressLine2": "Sydney 2000",
    "addressLine3": "AU
}

📥 Example Response

{
    "id": "virtual account id",
    "bsb": "252-000",
    "accountNumber": "123456789",
    "payId": null,
    "reference": "bank account reference",
    "company": {
        "id": "b8763ec9-3218-42f9-9baf-51706cff8bfd",
        "name": "company name",
        "types": null
    },
    "createdBy": {
        "id": "user id",
        "firstName": "first name",
        "lastName": "last name",
        "email": "email",
        "phone": "111222333"
    },
    "currency": "AUD",
    "type": "DISTRIBUTOR",
    "depositFee": {
        "amount": null,
        "percentage": null
    },
    "depositFeeResolved": {
        "amount": 0.01,
        "percentage": 0
    },
    "withdrawFee": {
        "amount": null,
        "percentage": null
    },
    "withdrawFeeResolved": {
        "amount": 0,
        "percentage": 0.01
    },
    "nickname": "UUID 846685458641",
    "subType": "DEPOSIT",
    "palmsManaged": false,
    "zeptoManaged": false,
    "bankingCircleManaged": true,
    "contactId": null,
    "balance": 0,
    "transactionHistories": [],
    "extCustomerId": "customer id",
    "linkedAccounts": [],
    "status": "ACTIVE",
    "sourceAccount": null,
    "accountHolderName": "KANGAROO PTY LTD",
    "accountHolderFirstname": "JOHN",
    "accountHolderLastname": "HOWARD",
    "metadata": {
        "creationDatetime": "timestamp"
    },
    "providerType": "BANKING_CIRCLE",
    "createdAt": "timestamp",
    "nameMatchingEnabled": null,
    "autoMintEnabled": false,
    "autoBurnEnabled": null,
    "referenceCheckingEnabled": null,
    "nameMatchingEnabledResolved": true,
    "referenceCheckingEnabledResolved": true
}

❗️
Save your Virtual Account ID:
The id response will be required in later functions - such as Minting AUDD. Keep this handy, as it may become difficult to find again if you have registered multiple VAs.

💸 Making a Deposit

In the staging environment, you can use the Mock Deposit Form to simulate AUD deposits. This lets you run through realistic deposit scenarios and confirm that your integration with the AUDD Mint works as expected before moving to production.

When you’re ready to go live, you’ll need a local AUD bank account to make real payments into your VA. Deposits made here follow the same validation process outlined earlier, ensuring funds are securely received.

📘
Fees & Charges:
Deposit amounts may be reduced by applicable fees, which are deducted automatically. For more information, refer to the Fees and Charges guide.

🔄 Updating Customer Details

For BANKING_CIRCLE named accounts, the customer name and address held against the Virtual Account must stay in sync with Banking Circle — the sender name on the VA is what deposits are matched against. Customer details are set when the VA is created (see above); if a customer later changes their name or address, push the update through with the PATCH /bank-accounts/{id} endpoint, where {id} is the VA id returned at creation.

Each request carries a changes array. Every item in the array describes exactly one change category — an individual name (first + last), a company name, or an address (all three lines) — together with the reason for the change.

❗️
Name Matching still applies:
Updating the name on a VA changes what future deposits are matched against. After a name change, the sending account name must match the new accountHolderName / accountHolderFirstName + accountHolderLastName, or the deposit will not clear.

Request Body

Field	Type	Required	Description
`changes`	array	✅	1–2 change items. Each item is a single change category. No two items may target the same category.
`changes[].reason`	string	✅	Reason code for the change. Must match the category being changed — see the reason-code table below.
`changes[].accountHolderCompanyName`	string	❌	New company name. Provide only for a company-name change.
`changes[].accountHolderFirstName`	string	❌	New first name. Provide together with `accountHolderLastName` for an individual-name change.
`changes[].accountHolderLastName`	string	❌	New last name. Provide together with `accountHolderFirstName`.
`changes[].addressLine1`	string	❌	Street address, e.g. `456 Example Street`. Required (with lines 2 and 3) for an address change.
`changes[].addressLine2`	string	❌	City and postcode, e.g. `Melbourne 3000`. Required (with lines 1 and 3) for an address change.
`changes[].addressLine3`	string	❌	ISO 3166-1 alpha-2 country code, e.g. `AU`. Required (with lines 1 and 2) for an address change.

📘
One category per change item
Each item in changes must contain exactly one of the following, and the reason must match it:

Individual name — both accountHolderFirstName and accountHolderLastName.

Company name — accountHolderCompanyName.

Address — all three of addressLine1, addressLine2 and addressLine3.

Mixing categories in a single item (e.g. a name field and an address line) is rejected. To change both a name and an address in one call, send two items — one per category (max 2 items per request, at most one of each category).

Reason Codes

`reason`	Applies to	Use when
`INDIVIDUAL_NAME_CHANGE`	Individual name	The individual account holder's name has changed.
`COMPANY_NAME_CHANGE`	Company name	The company's registered name has changed.
`COMPANY_OWNERSHIP_CHANGE`	Company name	The company name changes as a result of a change of ownership.
`INDIVIDUAL_ADDRESS_CHANGE`	Address	An individual account holder's address has changed.
`COMPANY_ADDRESS_CHANGE`	Address	A company account holder's address has changed.

🚧
Field rules

Field format: name, company-name and address lines 1–2 may contain only letters, digits, spaces and / - ? : ( ) . ' +, must not start with a space, and are limited to 35 characters. addressLine3 must be a valid ISO 3166-1 alpha-2 country code (two uppercase letters, e.g. AU).

Individual name changes require the VA to already have an individual first and last name on file (i.e. it was created as a named individual account). You cannot introduce individual names onto a company-only account with this endpoint.

Field casing: note the customer-detail fields on the PATCH body use accountHolderFirstName / accountHolderLastName (capital N), unlike the POST create body which uses accountHolderFirstname / accountHolderLastname.

Modification limit: Banking Circle caps how many times a VA's customer details can be modified. Once the limit is reached, further updates are rejected with a modification limit exceeded error.

📤 Example Request — change an individual's name and address in one call

{
    "changes": [
        {
            "reason": "INDIVIDUAL_NAME_CHANGE",
            "accountHolderFirstName": "JANE",
            "accountHolderLastName": "SMITH"
        },
        {
            "reason": "INDIVIDUAL_ADDRESS_CHANGE",
            "addressLine1": "456 Example Street",
            "addressLine2": "Melbourne 3000",
            "addressLine3": "AU"
        }
    ]
}

📤 Example Request — change a company name only

{
    "changes": [
        {
            "reason": "COMPANY_NAME_CHANGE",
            "accountHolderCompanyName": "WALLABY PTY LTD"
        }
    ]
}

📥 Response

On success the endpoint returns the updated bank account in the same shape as the POST /bank-accounts response, with the new accountHolderName, accountHolderFirstname, accountHolderLastname and address reflected. For an individual-name change, accountHolderName is kept in sync as "<firstName> <lastName>".

❗️
Updates are confirmed synchronously
The PATCH submits the change to Banking Circle and waits for it to be confirmed before returning. If Banking Circle rejects the change or does not confirm in time, no change is persisted and an error is returned — the VA keeps its previous customer details. Errors you may see:

Status Meaning
400 Invalid customer details — validation failed (wrong category count, mismatched reason, or a field-format violation).
400 Customer detail modification limit exceeded — Banking Circle will not accept further changes to this VA.
502 / 504 A transient Banking Circle failure or timeout. The update was not applied; retry the request.

🪄 Create a Virtual Account

Name Matching:

Required Customer Detail Fields

✅ Customer Detail Validation

Allowed characters

Validation only runs for Banking Circle accounts

📤 Example Request

📥 Example Response

Save your Virtual Account ID:

💸 Making a Deposit

Fees & Charges:

🔄 Updating Customer Details

Name Matching still applies:

Request Body

One category per change item

Reason Codes

Field rules

📤 Example Request — change an individual's name and address in one call

📤 Example Request — change a company name only

📥 Response

Updates are confirmed synchronously

What’s Next