Simulate connected account status transition

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.

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.

Endpoint definition:

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 be 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:

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

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:

Sample response:

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

Sample request:

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:

Sample response:

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.

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.