Add funds via direct debits from Linked Accounts
Direct debit deposits allow you to directly pull funds from an external financial account into your Airwallex account, so it can be used to fund payouts or card expenses.
You will need to first create Linked Accounts, which are external financial accounts linked to your Airwallex account. See Get started on how to create Linked Accounts and retrieve account details.
Create a direct debit mandate
Before you can add funds via direct debit from a Linked Account, you must obtain authorization from the external bank account owner in the form of a signed mandate (or signed agreement). You may have already submitted them when calling Create a Linked Account API. If not, call Update a direct debit mandate API to submit or update a signed mandate for an existing Linked Account.
To create and sign direct debit mandates via API, as a first step, please contact your Airwallex Account Manager to walk you through the direct debit mandate requirements and to enable this capability on your account.
Provide the following mandate details in the request:
email: Email of the signatory. A pdf copy of the mandate will be sent to this email address.signatory: Name of the mandate’s signatory. This should be the external bank account owner.type: Payment methods in different regions. Possible values are:AU_BECS_DEBIT,US_ACH_DEBIT,GB_BACS_DEBIT.version: Version of the signed mandate. The latestAU_BECS_DEBITversion is 1.1.1, and the latestUS_ACH_DEBITandGB_BACS_DEBITversions are both 1.0.preferred_reference: Reference that will show up for all direct debit deposits under this Linked Account. We may add a unique ID after your preferred reference per scheme requirements. Applies only toGB_BACS_DEBIT.address: Address of the signatory. Required only forGB_BACS_DEBIT.
If the mandate is successfully updated, a mandate status of ACTIVE will be returned. You can retrieve the mandate anytime using Get a direct debit mandate API.
Example request
If you are registered as a Scale platform account, you can call this endpoint on behalf of your connected accounts by specifying the open ID in the x-on-behalf-of header.
Example response
Check for funding limits
After creating a Linked Account and authorizing direct debits via a signed mandate, use Get funding limits API to confirm that your existing funding limits are sufficient. Funding limits are the maximum amount of direct debit deposits you can create over a certain period of time. They are shared across all Airwallex accounts under a single legal entity, and may be counted against regular direct debits (flight time 2-5 business days) and Faster Direct Debits (flight time 0-1 business day).
The response will provide all the funding limits currently available to the legal entity associated with your Airwallex account.
Example request
If you are registered as a Scale platform account, you can call this endpoint on behalf of your connected accounts by specifying the open ID in the x-on-behalf-of header.
You can also call this endpoint directly to check funding limits available to the legal entity associated with your own account. Depending on configurations agreed upon with your Account Manager, direct debit deposits created on behalf of your connected accounts may draw from either the platform account or the connected account.
To learn more, see Understanding direct debit flight times and funding limits.
Example response
Check Linked Account balance
If your Linked Account was created using Open Banking, you will be able to use Check available balances API to ensure that the external bank account has sufficient balance for your direct debit.
We recommend checking balances ahead of larger transactions. This is because an overdraft of the Linked Account would still be processed, only to return as REJECTED a few days later.
Example request
Example response
Create a direct debit deposit
After ensuring that you have sufficient limit for the direct debit and that the Linked Account has sufficient balance, use Create a deposit via Direct Debit API to receive funds into your Wallet. You may use this endpoint to create both regular direct debit deposits (flight time 2-4 business days) or Faster Direct Debit deposits (flight time 0-1 business day).
Provide the following parameters in your request:
amount: The amount you want to collect.currency: The currency of the amount in 3-letter ISO-4217 codedeposit_type: The type of deposit you would like to create, either DIRECT_DEBIT or FASTER_DIRECT_DEBIT. If not specified, it will default to DIRECT_DEBIT.funding_source_id: The unique id of your Linked Account as returned in Create a Linked Account API.request_id: A unique ID for this deposit request (should be a valid UUID).reference: An optional reference that will be displayed to the bank account owner on the bank statement. Not applicable toGB_BACS_DEBIT, which uses thepreferred_referencefield when calling Create a Linked Account API or Update a direct debit mandate API.
A successful request will return a PENDING status. The status will be updated to SETTLED and the funds will be added to your available balance after a holding time if the deposit succeeds; to REJECTED if it is rejected by the external bank due to incorrect details or insufficient funds. If the external bank recalls the fund after it has been settled into your Wallet, a new transaction will appear with the status REVERSED to deduct the fund from your balance. If your direct debit limit or Faster Direct Debit Limit is insufficient to honour the deposit, the request will return a 400 error with the code insufficient_quota.
Using the deposit_id returned in the response, you can retrieve further details of a deposit and keep track of the status changes. See Get a deposit by ID API or review status codes to track status transitions for deposits via direct debit from Linked Accounts.
Example request
If you are registered as a Scale platform account, you can call this endpoint on behalf of your connected accounts by specifying the open ID in the x-on-behalf-of header.