Log inGet started
Airwallex logo
Home
Online Payments
Treasury
Transactional FX
Payouts
Issuing
Scale
Open Banking
Developer Tools
API Reference
Home
Developer Tools
Get started
Make your first no-code API callManage API keys
Event Simulations
Simulate deposits to your Global AccountSimulate payout status transitionSimulate connected account status transition
Generate card issuing transactionsCodeBlock Demo (DON'T PUBLISH!!)

Simulate connected account status transition

Why do we want to simulate the status transition for a connected account?

You can conduct unit and end-to-end testing of your integration with this endpoint. It is key to account for status scenarios as you build out your integration.

Transitioning an account through it’s lifecycle triggers all production scenarios in the demo environment.

What production scenario are we simulating?

A platform account can create individual or business accounts and submit the account for onboarding (link API). This simulation endpoint emulates the connected account status lifecycle scenarios in the demo environment.

Note that this simulation endpoint will transition the account into ACTION_REQUIRED, ACTIVE, SUSPENDED.

A connected account API can be in one of the following statuses: CREATED, SUBMITTED, ACTION_REQUIRED, ACTIVE, and SUSPENDED.

Account status transition simulation endpoint schema

Endpoint definition:

Shell

Before you can use this endpoint, the account must in be in the SUBMITTED status. Use the create API and submit API APIs to move the account into CREATED and SUBMITTED statuses.

The request body supports in the following parameters:

  • next_status (string, mandatory): This input parameter specifies the next status the account status will transition to.
    • If “force” is empty, then the account status will be forced into ACTIVE and SUSPENDED when specified in “next_status”.
    • If “force” is false then this API will not force these statuses. ACTION_REQUIRED may simulated when (1) attempting to move the “next_status” to ACTIVE and (2) at least one of the following conditions are met:
      • Connected account has not agreed to terms and conditions. Behaviour is simulated by setting “customer_agreements.agreed_to_terms_and_conditions” is “false” when creating or updating an account. This applies to both individual and business accounts.
      • Identity file uploaded did not pass verification. Behaviour is simulated by providing the an invalid file_id that canot be validated when creating or updating an account. Use this file_id to not pass verification: NTZiN2NkNWUtYmUxNC00NTE2LTllNGMtZTNjNzU0ZGU2ZmE1LHwsaG9uZ2tvbmcsfCxBaXJ3YWxsZXgtbG9nby5wbmdfMTY0Nzk5NTgwNTIzNw. This applies only to individual accounts.
      • Connected account owner has not approved the scale connection. if the platform account is configured to require this consent. Contact your account manager and solutions engineer to help configure this scenario if you want to simulate it. This applies only to business accounts.
  • force (boolean, optional): This input parameter will force the account into ACTIVE and SUSPENDED statuses if no input is provided. If “force” is false then this API will not force these statuses. ACTION_REQUIRED may simulated when (1) attempting to move the “next_status” to ACTIVE and (2) at least one of the above conditions are met.

Example request body:

JavaScript

Example response body: The response will replicate the response structure of an account schema as seen in the retrieve account details API endpoint.

JavaScript

How to use the Account Status Simulation API?

Account status simulation API sequence diagram

The payment status transition simulation endpoint works with Airwallex public APIs.

Step 1: Use our authentication endpoint API and obtain an access token to call our API endpoints.

Sample request:

Shell

Sample response:

JavaScript

Step 2: Create a connected account with the create account API. The status of this connected account be in the CREATED status.

Sample request:

Shell

Step 3: Submit the connected account for KYC review with the submit connected account endpoint API. In the production environment our onboarding team will review the account through our KYC process. In the demo environment, this simulation endpoint will emulate this process.

Sample request:

Shell

Sample response:

JavaScript

Step 4: Call the connected account status transition simulation endpoint you would like to transition to.

  • If “force” is empty, then the account status will be forced into ACTIVE and SUSPENDED when specified in “next_status”.
  • If “force” is false then this API will not force these statuses. ACTION_REQUIRED may simulated when (1) attempting to move the “next_status” to ACTIVE and (2) at least one of the following conditions are met:
    • Connected account has not agreed to terms and conditions. Behaviour is simulated by setting “customer_agreements.agreed_to_terms_and_conditions” is “false” when creating or updating an account. This applies to both individual and business accounts.
    • Identity file uploaded did not pass verification. Behaviour is simulated by providing the an invalid file_id that canot be validated when creating or updating an account. Use this file_id to not pass verification: NTZiN2NkNWUtYmUxNC00NTE2LTllNGMtZTNjNzU0ZGU2ZmE1LHwsaG9uZ2tvbmcsfCxBaXJ3YWxsZXgtbG9nby5wbmdfMTY0Nzk5NTgwNTIzNw. This applies only to individual accounts.
    • Connected account owner has not approved the scale connection. if the platform account is configured to require this consent. Contact your account manager and solutions engineer to help configure this scenario if you want to simulate it. This applies only to business accounts.

Sample request: In the example below the user attempted to move the account into ACTIVE status. Since the user is not forcing the account into this status the account may be moved to “ACTION_REQUIRED” if more information is required from the account.

Shell

Sample response: The account is moved into the status ACTION_REQUIRED because more info is required. The object “requirements.agreement_to_terms_and_conditions_required” specifies that the customer needs to accept the terms and conditions via API API.

JavaScript