Hosted Flows

Airwallex Hosted Flows enable a Platform to redirect end users into Airwallex-hosted web pages to complete a variety of activity flows. Platforms can deliver hosted flows via a secure, short-lived link unique to each connected account. After completion of a flow, the user is redirected back to the platform. Hosted flows are available for accounts created via API.

Currently supported flows:

onboarding – Submit KYC information needed to activate the account.

Contact your Airwallex Account Manager to start using hosted flows.

Your Account Manager will create a flow template, which defines the series of steps the end user will proceed through. Then, you can create a flow instance for a particular connected account and direct users to the provided URL.

Endpoints

POST /api/v1/hosted_flows/create
GET /api/v1/hosted_flows/{id}
POST /api/v1/hosted_flows/{id}/authorize

Create flow

POST /api/v1/hosted_flows/create

Copy for LLMView as Markdown

Create a hosted flow instance for an account. Specify the account_id of the connected account for which you are creating the flow, and the hosted flow template provided by Airwallex.

Request body

account_idrequiredstring

Account unique identifier of the connected account for which the hosted flow instance is created

error_urlstring

If set, the user will be redirected to this URL if an error occurs, with an extra query parameter ahfi_id

metadataobject

A set of key-value pairs that you can attach to the hosted flow

return_urlstring

The user be redirected to this URL after finishing the flow, with an extra query parameter ahfi_id, this field is only required if Airwallex is hosting the experience

templaterequiredstring

Unique identifier of the template that the created flow instance will follow

Response body - 201 Created

idstring

Unique identifier of the hosted flow instance.

metadataobject

The metadata set when creating the flow

resultobject

The result of the flow execution, containing optional additional information for each flow action if status is FINISHED. It is usually empty.

statusstring

The status of the flow instance. One of INIT, PROCESSING or FINISHED

urlstring

The URL by which only users with Airwallex login credentials can enter the flow. For your own users, make sure to authorize the flow next. This link is unique to the connected account_id specified in the request and expires after 15 seconds.

Errors

Error status	Description
400	["Your account does not have a flow template" ,"Account does not exist." "Invalid value for return_url." ]
401	Possible errors: `credentials_invalid`, `credentials_expired`
429	Too many requests
500	Service unavailable

POST /api/v1/hosted_flows/create

$curl --request POST \
>  --url 'https://api-demo.airwallex.com/api/v1/hosted_flows/create' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "account_id": "acct_wst1AJZWbOx2Ijf-PDS123w",
>  "error_url": "<string>",
>  "metadata": {},
>  "return_url": "<string>",
>  "template": "<string>"
>}'

Response (201 Created)

1{
2  "id": "ahfi_Y9_AbPkQQQe0K81XcHLy5w",
3  "metadata": {},
4  "result": {},
5  "status": "INIT",
6  "url": "<string>"
7}

Was this section helpful?

Get flow

GET /api/v1/hosted_flows/{id}

Copy for LLMView as Markdown

Get the AWX Hosted Flow instance by its unique identifier

Parameters

idrequiredstring

Unique identifier of the hosted flow instance

Response body - 200 OK

idstring

Unique identifier of the hosted flow instance.

metadataobject

The metadata set when creating the flow

resultobject

The result of the flow execution, containing optional additional information for each flow action if status is FINISHED. It is usually empty.

statusstring

The status of the flow instance. One of INIT, PROCESSING or FINISHED

urlstring

Errors

Error status	Description
401	Possible errors: `credentials_invalid`, `credentials_expired`
429	Too many requests
500	Service unavailable

GET /api/v1/hosted_flows/{id}

$curl --request GET \
>  --url 'https://api-demo.airwallex.com/api/v1/hosted_flows/hosted_flow_id' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json'

Response (200 OK)

1{
2  "id": "ahfi_Y9_AbPkQQQe0K81XcHLy5w",
3  "metadata": {},
4  "result": {},
5  "status": "INIT",
6  "url": "<string>"
7}

Was this section helpful?

Authorize flow

POST /api/v1/hosted_flows/{id}/authorize

Copy for LLMView as Markdown

Explicitly authorize the user to access a created hosted flow instance. You can then redirect the user to the url link in the response.

Parameters

idrequiredstring

Unique identifier of the hosted flow instance

Request body

identitystring

The platform’s identifier for the user, such as a user unique identifier, session unique identifier, or access token.

Response body - 201 Created

authorization_codestring

This is a unique code embedded in url to authorize the user into the hosted flow. This code expires after 15 seconds.

idstring

Unique identifier of the hosted flow instance.

metadataobject

A set of key-value pairs that were specified in the request

resultobject

The result of the flow execution, null if status is not FINISHED

statusstring

The status of the flow instance. One of INIT, PROCESSING or FINISHED

urlstring

The URL by which your authorized user can enter the hosted flow. This link is unique to the connected account id specified in the request and expires after 15 seconds.

Errors

Error status	Description
401	Possible errors: `credentials_invalid`, `credentials_expired`
429	Too many requests
500	Service unavailable

POST /api/v1/hosted_flows/{id}/authorize

$curl --request POST \
>  --url 'https://api-demo.airwallex.com/api/v1/hosted_flows/hosted_flow_id/authorize' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "identity": "<string>"
>}'

Response (201 Created)

1{
2  "authorization_code": "<string>",
3  "id": "<string>",
4  "metadata": {},
5  "result": {},
6  "status": "INIT",
7  "url": "<string>"
8}

Was this section helpful?