Hong Kong (HK_FPS_DEBIT)
Before you begin
Check your eligibility
- Onboarding entity: FPS direct debit is only available to Hong Kong customers who are onboarded to Airwallex Hong Kong with a local Hong Kong Bank Account
- Platforms must ensure that only customers onboarded to Airwallex Hong Kong are allowed to set up FPS direct debit
- If you, as the Platform, would also like to use FPS direct debit for your operational purposes, you must also be onboarded to Airwallex Hong Kong
- Industry: Industry restrictions apply. Please reach out to your Airwallex Account Manager for more information
Settlement times
FPS direct debit settles 24/7 in real-time via the FPS clearing system, hence FASTER_DIRECT_DEBIT is not applicable.
Mandate requirements
To add funds via FPS direct debit, your customers must first link their Hong Kong external bank accounts, as outlined in Linked Accounts.
Before any FPS direct debit is processed, the owner of the external bank account must authorize Airwallex to directly debit the account on your behalf, in compliance with the Faster Payment System Rules. A copy of the authorization will be sent by Airwallex via email to the bank account owner, and is stored and made available to be shared with the customer at all times.
The following is a guide to building your native product experience for your customers to link their external bank account and sign the mandate/agreement.
1. Linking an external bank account
The title should clearly inform your customers that they are linking an external bank account to set up direct debit.
You must ask the external bank account owner (or display their previously entered):
- Bank account name
- Bank account number
- Bank code
- Bank account owner email address
- Identification type and number (Your customers should be informed that this needs to be the same identification information that was used for registration with the external bank)
3. Confirmation of direct debit set up
It is recommended that you provide a confirmation page to your customers at the end of the process to inform them that direct debit has been successfully set up for the Linked Bank Account.
API instruction
1. Create Linked Account with direct debit mandate
Referring to Linked Account requirements for direct debit, both BUSINESS and INDIVIDUAL Linked Account types are supported for FPS direct debit in Hong Kong.
Micro-deposit is available as the verification method. Please follow the instructions in Create a Linked Account using micro-deposit verification and submit the required mandate information under the mandate object.
Identification information is compulsory when creating or updating the direct debit mandate for HK_FPS_DEBIT. The following must be provided in the identification_document object:
type: Type of identification that was used for registration with the external bank.- For individual bank accounts, the possible types are
HK_ID,PASSPORTandOTHERS.OTHERSmay include Chinese ID, Driver License etc. - For business bank accounts, the possible types are
BUSINESS_REGISTRATION_NUMBERandCERTIFICATE_OF_INCORPORATION_NUMBER
- For individual bank accounts, the possible types are
value: Value of the identification
The identification information provided above must also be on file with Airwallex.
Example request
If you are registered as a platform account, you can call this endpoint on behalf of your customers by specifying the open ID in the x-on-behalf-of header.
Example response
If you already have a Linked Account created using micro-deposit verification, you may call Update a Direct Debit Mandate API to create the mandate.
Example request
If you are registered as a platform account, you can call this endpoint on behalf of your customers by specifying the open ID in the x-on-behalf-of header.
Example response
2. Create direct debit deposit
Before creating a direct debit deposit, please ensure that you have a sufficient funding limit by checking your available funding limit.
Next, follow the instructions outlined in Create a direct debit deposit. Please note that FPS direct debit in Hong Kong does not support direct debit deposit reference.
Example request
If you are registered as a platform account, you can call this endpoint on behalf of your customers by specifying the open ID in the x-on-behalf-of header.
Example response
Clearing system error codes
To help you handle exceptions systematically, this page provides a comprehensive list of all possible clearing system errors and detailed descriptions when the Linked Accounts or a direct debit deposit from Linked Accounts are in failure statuses.
We recommend using the Airwallex error code or the iso_code for systematic exception handling. The code from provider_failure_details can be used for troubleshooting against the clearing system rules, but it is not advised for systematic handling because the clearing system may update it from time to time.
Direct debit deposit error codes
| code | iso code | provider failure details code | description |
|---|---|---|---|
invalid_debtor_account_number | AC02 | DTAC02, DTAC06 | The payer’s bank account number is invalid. Please confirm the account number with the payer. |
closed_account_number | AC04 | 50603, DTAC01 | The payer’s bank account is closed. Contact the payer to reopen the account, or create a new mandate to charge a different bank account. |
blocked_account | AC06 | 50682, 50604, 53431, PAY20102 | The bank account has been blocked for FPS direct debits. Contact the payer to remove the block, or create a new mandate to charge a different bank account. |
unsuccessful_direct_debit | AG07 | AG07 | The payer's bank account has pending funds that have not cleared yet. Contact the payer’s bank for further information. |
not_allowed_amount | AM02 | AM02, 42404, PAY20006 | The payer sets a limit with its bank and the direct debit deposit amount is greater than the limit. |
insufficient_funds | AM04 | AM04, 42405, PAY20101 | The balance in the Linked Account is insufficient. Please ensure funds are added to the Linked Account and retry. |
requested_by_customer | CUST | CUST, 57301 | Instruction is cancelled by the payer. Contact the payer for further information. |
no_mandate | MD01 | MD01, 55188, 55195, MNDT01, DTL1161 , OTHERS | The direct debit mandate is not present. Please confirm that the payer or payer's bank has not cancelled the mandate before contacting your account manager for further information. |
end_customer_deceased | MD07 | MD07 | You cannot create a direct debit against the payer’s bank account because the payer is deceased. Contact the payer’s bank for further instructions. |
not_specified_reason_customer_generated | MS02 | MNDT05 | The payer refuses the direct debit. Reason has not been specified. Contact the payer for further information. |
other | NARR | NARR | Reason has not been specified. Contact the payer or payer’s for further information. |