🏦 External Bank Account Management

External bank accounts are bank accounts outside the AUDD Mint platform that are used to send and receive Australian dollars (AUD). They are managed by banks or other financial institutions, and your AUDD Mint environment interacts with them to process deposits and withdrawals.

There are two types of external bank accounts:

Remitter bank accounts: bank accounts used to send funds into your Virtual Accounts (VAs)
Withdrawal bank accounts: bank accounts used to receive funds out of your VAs

Each type plays a distinct role in the Mint ecosystem, as outlined below.

↪️ Remitter Bank Accounts

When you send funds to your VA for the first time, the system captures the details of the sending bank account - including the Account Name, BSB, and Account Number - and automatically creates a linked Remitter Account. This represents the external bank account used to deposit funds.

Retaining remitter accounts is essential for compliance and operational integrity. If a payment doesn’t meet risk criteria and must be returned, it can only be refunded back to its original sending account. Having a recorded remitter account ensures this is possible. Remitter accounts also support the platform’s whitelisting system, helping validate and approve future payments. For more information, see our Transaction Monitoring guide.

A single remitter account can be linked to multiple VAs. This is useful when a user needs multiple virtual accounts to segment funds across different products, services, or blockchains while maintaining the same source bank account.

💸 Withdrawal Bank Accounts

Create a Withdrawal bank account

Open Recipe

Withdrawal bank accounts are external bank accounts added to your environment to receive funds when withdrawing AUD. When you register a withdrawal bank account, it is linked to a specific VA and inherits the account name of that VA during creation. Because of this, you should only register withdrawal bank accounts against a VA that is directly linked to the intended recipient.

📝 Creating a Withdrawal Bank Account

To create a withdrawal bank account, call the POST /bank-accounts endpoint. The request body must include the following fields:

Field	Type	Required	Description
`companyId`	string	✅	The ID of the distributor company creating the withdrawal account.
`bsb`	string	✅	The BSB (Bank State Branch) number of the external withdrawal bank account.
`accountNumber`	string	✅	The account number of the external withdrawal bank account.
`payId`	string	❌	coming soon not yet supported
`nickname`	string	✅	A friendly label to identify the withdrawal account in Mint.
`currency`	string	✅	The account currency. Currently only `AUD` is supported.
`type`	string	✅	Must be set to `DISTRIBUTOR` for distributor-linked accounts.
`subType`	string	✅	Must be set to `WITHDRAWAL`
`bankProviderType`	string	✅	The provider type. Use `NONE` for external withdrawal accounts.
`internalBankAccountId`	string	✅	The ID of the internal VA that this withdrawal account should be linked to.

📘
Bank Account Formats:
If you’re unfamiliar with how Australian bank accounts are structured, see our AUD Payments guide for more information.

📤 Example Request

{
    "companyId": "company id",
    "bsb": "123-654",
    "accountNumber": "123456789",
    "payId": "",
    "nickname": "example",
    "currency": "AUD",
    "type": "DISTRIBUTOR",
    "subType": "WITHDRAWAL",
    "bankProviderType": "NONE",
    "internalBankAccountId": "deposit bank account id"
}

📥 Example Response

{
    "id": "whitelisted bank account id",
    "bsb": "123-654",
    "accountNumber": "123456789",
    "payId": null,
    "reference": "whitelisted bank account reference",
    "company": {
        "id": "company id",
        "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,
        "percentage": 0
    },
    "withdrawFee": {
        "amount": null,
        "percentage": null
    },
    "withdrawFeeResolved": {
        "amount": 0,
        "percentage": 0
    },
    "nickname": "example",
    "subType": "WITHDRAWAL",
    "palmsManaged": false,
    "zeptoManaged": false,
    "bankingCircleManaged": false,
    "contactId": null,
    "balance": 0,
    "transactionHistories": [],
    "extCustomerId": "customer id",
    "linkedAccounts": [
        {
            "id": "remitter bank account id",
            "bsb": "123-456",
            "accountNumber": "123456789",
            "payId": null,
            "reference": null,
            "currency": "AUD",
            "type": "DISTRIBUTOR",
            "company": {
                "id": "company id",
                "name": "company name",
                "types": null
            },
            "depositFee": {
                "amount": null,
                "percentage": null
            },
            "withdrawFee": {
                "amount": null,
                "percentage": 0
            },
            "nickname": "example",
            "subType": "REMITTER",
            "contactId": null,
            "balance": 0,
            "sourceAccount": null,
            "status": "ACTIVE",
            "accountHolderName": "example name",
            "accountHolderFirstname": null,
            "accountHolderLastname": null,
            "providerType": "NONE",
            "createdAt": "timestamp",
            "nameMatchingEnabled": null,
            "autoMintEnabled": false,
            "autoBurnEnabled": false
        },
        {
            "id": "deposit bank account id",
            "bsb": "252-000",
            "accountNumber": "123456789",
            "payId": null,
            "reference": "deposit bank account reference",
            "currency": "AUD",
            "type": "DISTRIBUTOR",
            "company": {
                "id": "company id",
                "name": "company name",
                "types": null
            },
            "depositFee": {
                "amount": null,
                "percentage": null
            },
            "withdrawFee": {
                "amount": null,
                "percentage": 0
            },
            "nickname": "example",
            "subType": "DEPOSIT",
            "contactId": null,
            "balance": 100,
            "sourceAccount": null,
            "status": "ACTIVE",
            "accountHolderName": "example",
            "accountHolderFirstname": "",
            "accountHolderLastname": "",
            "providerType": "BANKING_CIRCLE",
            "createdAt": "timestamp",
            "nameMatchingEnabled": null,
            "autoMintEnabled": false,
            "autoBurnEnabled": false
        }
    ],
    "status": "ACTIVE",
    "sourceAccount": {
        "id": "deposit bank account id",
        "bsb": "252-000",
        "accountNumber": "123456789",
        "payId": null,
        "reference": "deposit bank account reference",
        "currency": "AUD",
        "type": "DISTRIBUTOR",
        "company": {
            "id": "company id",
            "name": "company name",
            "types": null
        },
        "depositFee": {
            "amount": null,
            "percentage": null
        },
        "withdrawFee": {
            "amount": null,
            "percentage": 0
        },
        "nickname": "example",
        "subType": "DEPOSIT",
        "contactId": null,
        "balance": 100,
        "sourceAccount": null,
        "status": "ACTIVE",
        "accountHolderName": "example",
        "accountHolderFirstname": "",
        "accountHolderLastname": "",
        "providerType": "BANKING_CIRCLE",
        "createdAt": "timestamp",
        "nameMatchingEnabled": null,
        "autoMintEnabled": false,
        "autoBurnEnabled": false
    },
    "accountHolderName": null,
    "accountHolderFirstname": null,
    "accountHolderLastname": null,
    "metadata": {},
    "providerType": "NONE",
    "createdAt": "timestamp",
    "nameMatchingEnabled": null,
    "autoMintEnabled": false,
    "autoBurnEnabled": null,
    "referenceCheckingEnabled": null,
    "nameMatchingEnabledResolved": true,
    "referenceCheckingEnabledResolved": true
}

✏️ Updating Bank Accounts

Always double-check bank account details before creating them, as sending withdrawals to the wrong account could result in lost funds.

If you ever need to update a bank account, you can call the PUT /bank-accounts/{id} endpoint, with id denoting the bank account you want to update. This uses the same request body schema as when creating a bank account, allowing you to change fields like the BSB or account number if needed.

🗑️ Deleting Bank Accounts

If a withdrawal bank account is no longer valid or needed, you can remove it from your environment. To do this, simply call the DELETE /bank-accounts/{id} endpoint. Once removed, the account can no longer be used for withdrawals.