Platform Liquidity ProgramsBeta

Manage platform liquidity programs, spending accounts, transactions, and fund deposit and withdrawal.

Endpoints

GET /api/v1/platform_liquidity_programs/{id}
POST /api/v1/platform_liquidity_programs/{id}/deposit
POST /api/v1/platform_liquidity_programs/{id}/withdraw
POST /api/v1/platform_liquidity_programs/{id}/program_spending_accounts/create
GET /api/v1/platform_liquidity_programs/{id}/program_spending_accounts/{spending_account_id}
GET /api/v1/platform_liquidity_programs/{id}/program_spending_accounts
POST /api/v1/platform_liquidity_programs/{id}/program_spending_accounts/{spending_account_id}/adjust_limits
GET /api/v1/platform_liquidity_programs/{id}/transactions

Retrieve a Program

GET /api/v1/platform_liquidity_programs/{id}

Copy for LLMView as Markdown

Retrieve details of a Platform Liquidity Program.

Parameters

idrequiredstring

Unique identifier of the program.

Response body - 200 OK

created_atstring

The time the program was created

idstring

Unique identifier of the Platform Liquidity Program

limit_balancesarray

Array of program balance information

limit_balances.available_amountnumber

Available balance

limit_balances.currencystring

Three-letter ISO 4217 currency code

limit_balances.reserved_amountnumber

Reserved balance

limit_balances.total_amountnumber

Account total balance

namestring

Name of the Platform Liquidity Program

statusstring

Status of the Platform Liquidity Program, either ACTIVE or INACTIVE

supported_currenciesarray

Array of currency configurations

supported_currencies.currencystring

Three-letter ISO 4217 currency code

supported_currencies.low_balance_thresholdnumber

Low balance threshold amount. When the available balance drops below this threshold, the low balance webhook will be triggered.

updated_atstring

The time the program was last updated

Errors

Error status	Description
401	Possible errors: `credentials_invalid`, `credentials_expired`
403	`forbidden`
404	`not_found`
429	`too_many_requests`
500	`service_unavailable`

GET /api/v1/platform_liquidity_programs/{id}

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

Response (200 OK)

1{
2  "created_at": "2023-06-01T15:30:00Z",
3  "id": "123e4567-e89b-12d3-a456-426614174000",
4  "limit_balances": [
5    {
6      "available_amount": 10000,
7      "currency": "HKD",
8      "reserved_amount": 2000,
9      "total_amount": 12000
10    }
11  ],
12  "name": "Merchant A Program",
13  "status": "ACTIVE",
14  "supported_currencies": [
15    {
16      "currency": "HKD",
17      "low_balance_threshold": 1000
18    }
19  ],
20  "updated_at": "2023-06-01T15:45:30Z"
21}

Was this section helpful?

Deposit Funds Into a Program

POST /api/v1/platform_liquidity_programs/{id}/deposit

Copy for LLMView as Markdown

Deposits funds into the program's settlement Airwallex account from the platform's wallet. The program limit balance will increase by the deposited amount.

Parameters

idrequiredstring

Unique identifier of the program.

Request body

amountrequirednumber

Deposit amount, greater than 0.

currencyrequiredstring

Currency in 3-letter ISO-4217 format.

request_idrequiredstring

A unique request identifier specified by the client. It's used by Airwallex for idempotency check. In case of timeout, the client can retry with the same request_id.

Response body - 200 OK

created_atstring

The time the program was created

idstring

Unique identifier of the Platform Liquidity Program

limit_balancesarray

Array of program balance information

limit_balances.available_amountnumber

Available balance

limit_balances.currencystring

Three-letter ISO 4217 currency code

limit_balances.reserved_amountnumber

Reserved balance

limit_balances.total_amountnumber

Account total balance

namestring

Name of the Platform Liquidity Program

statusstring

Status of the Platform Liquidity Program, either ACTIVE or INACTIVE

supported_currenciesarray

Array of currency configurations

supported_currencies.currencystring

Three-letter ISO 4217 currency code

supported_currencies.low_balance_thresholdnumber

Low balance threshold amount. When the available balance drops below this threshold, the low balance webhook will be triggered.

updated_atstring

The time the program was last updated

Errors

Error status	Description
401	Possible errors: `credentials_invalid`, `credentials_expired`
403	`forbidden`
429	`too_many_requests`
500	`service_unavailable`

POST /api/v1/platform_liquidity_programs/{id}/deposit

$curl --request POST \
>  --url 'https://api.sandbox.airwallex.com/api/v1/platform_liquidity_programs/platform_liquidity_program_id/deposit' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "amount": 500,
>  "currency": "USD",
>  "request_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2"
>}'

Response (200 OK)

1{
2  "created_at": "2023-06-01T15:30:00Z",
3  "id": "123e4567-e89b-12d3-a456-426614174000",
4  "limit_balances": [
5    {
6      "available_amount": 10000,
7      "currency": "HKD",
8      "reserved_amount": 2000,
9      "total_amount": 12000
10    }
11  ],
12  "name": "Merchant A Program",
13  "status": "ACTIVE",
14  "supported_currencies": [
15    {
16      "currency": "HKD",
17      "low_balance_threshold": 1000
18    }
19  ],
20  "updated_at": "2023-06-01T15:45:30Z"
21}

Was this section helpful?

Withdraw Funds From a Program

POST /api/v1/platform_liquidity_programs/{id}/withdraw

Copy for LLMView as Markdown

Withdraws funds from the program's settlement Airwallex account into the platform's wallet. The program limit balance will decrease by the withdrawn amount.

Parameters

idrequiredstring

Unique identifier of the program.

Request body

amountrequirednumber

Withdraw amount, greater than 0.

currencyrequiredstring

Currency in 3-letter ISO-4217 format.

request_idrequiredstring

A unique request identifier specified by the client. It's used by Airwallex for idempotency check. In case of timeout, the client can retry with the same request_id.

Response body - 200 OK

created_atstring

The time the program was created

idstring

Unique identifier of the Platform Liquidity Program

limit_balancesarray

Array of program balance information

limit_balances.available_amountnumber

Available balance

limit_balances.currencystring

Three-letter ISO 4217 currency code

limit_balances.reserved_amountnumber

Reserved balance

limit_balances.total_amountnumber

Account total balance

namestring

Name of the Platform Liquidity Program

statusstring

Status of the Platform Liquidity Program, either ACTIVE or INACTIVE

supported_currenciesarray

Array of currency configurations

supported_currencies.currencystring

Three-letter ISO 4217 currency code

supported_currencies.low_balance_thresholdnumber

Low balance threshold amount. When the available balance drops below this threshold, the low balance webhook will be triggered.

updated_atstring

The time the program was last updated

Errors

Error status	Description
401	Possible errors: `credentials_invalid`, `credentials_expired`
403	`forbidden`
429	`too_many_requests`
500	`service_unavailable`

POST /api/v1/platform_liquidity_programs/{id}/withdraw

$curl --request POST \
>  --url 'https://api.sandbox.airwallex.com/api/v1/platform_liquidity_programs/platform_liquidity_program_id/withdraw' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "amount": 500,
>  "currency": "USD",
>  "request_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2"
>}'

Response (200 OK)

1{
2  "created_at": "2023-06-01T15:30:00Z",
3  "id": "123e4567-e89b-12d3-a456-426614174000",
4  "limit_balances": [
5    {
6      "available_amount": 10000,
7      "currency": "HKD",
8      "reserved_amount": 2000,
9      "total_amount": 12000
10    }
11  ],
12  "name": "Merchant A Program",
13  "status": "ACTIVE",
14  "supported_currencies": [
15    {
16      "currency": "HKD",
17      "low_balance_threshold": 1000
18    }
19  ],
20  "updated_at": "2023-06-01T15:45:30Z"
21}

Was this section helpful?

Create a Program Spending Account

POST /api/v1/platform_liquidity_programs/{id}/program_spending_accounts/create

Copy for LLMView as Markdown

Creates a spending account for a program, allowing access to program funds when transacting.

Parameters

idrequiredstring

Unique identifier of the program.

Request body

connected_account_idrequiredstring

Unique identifier of the Connected Account that the spending account is linked to.

Response body - 201 Created

connected_account_idstring

Unique identifier of the Connected Account that the spending account is linked to

created_atstring

The time the spending account was created

funding_source_idstring

Unique identifier of the funding source. The unique identifier can be used to link a card to this program's spending account. Refer to Create Card API.

idstring

Unique identifier of the program spending account

statusstring

Status of the spending account, either ACTIVE or INACTIVE

updated_atstring

The time the spending account was last updated

Errors

Error status	Description
401	Possible errors: `credentials_invalid`, `credentials_expired`
403	`forbidden`
429	`too_many_requests`
500	`service_unavailable`

POST /api/v1/platform_liquidity_programs/{id}/program_spending_accounts/create

$curl --request POST \
>  --url 'https://api.sandbox.airwallex.com/api/v1/platform_liquidity_programs/platform_liquidity_program_id/program_spending_accounts/create' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "connected_account_id": "ACCT_123e4567"
>}'

Response (201 Created)

1{
2  "connected_account_id": "ACCT_123e4567",
3  "created_at": "2023-06-01T15:30:00Z",
4  "funding_source_id": "123e4567-e89b-12d3-a456-426614174001",
5  "id": "123e4567-e89b-12d3-a456-426614174000",
6  "status": "ACTIVE",
7  "updated_at": "2023-06-01T15:45:30Z"
8}

Was this section helpful?

Retrieve a Program Spending Account

GET /api/v1/platform_liquidity_programs/{id}/program_spending_accounts/{spending_account_id}

Copy for LLMView as Markdown

Retrieve details of a program spending account.

Parameters

idrequiredstring

Unique identifier of the program.

spending_account_idrequiredstring

Program Spending Account unique identifier.

Response body - 200 OK

connected_account_idstring

Unique identifier of the Connected Account that the spending account is linked to

created_atstring

The time the spending account was created

funding_source_idstring

Unique identifier of the funding source. The unique identifier can be used to link a card to this program's spending account. Refer to Create Card API.

idstring

Unique identifier of the program spending account

limit_balancesarray | null

Per-currency balances when limit_policy is ENFORCED; null when limit_policy is BYPASSED

limit_balances.available_amountnumber

Amount available for new spending

limit_balances.currencystring

Three-letter ISO 4217 currency code

limit_balances.reserved_amountnumber

Amount reserved by pending spending

limit_balances.total_amountnumber

Sum of available_amount and reserved_amount

limit_policystring

Policy controlling whether local spending limits are enforced

BYPASSED

ENFORCED

statusstring

Status of the spending account, either ACTIVE or INACTIVE

updated_atstring

The time the spending account was last updated

Errors

Error status	Description
401	Possible errors: `credentials_invalid`, `credentials_expired`
403	`forbidden`
404	`not_found`
429	`too_many_requests`
500	`service_unavailable`

GET /api/v1/platform_liquidity_programs/{id}/program_spending_accounts/{spending_account_id}

$curl --request GET \
>  --url 'https://api.sandbox.airwallex.com/api/v1/platform_liquidity_programs/platform_liquidity_program_id/program_spending_accounts/spending_account_id' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json'

Response (200 OK)

1{
2  "connected_account_id": "ACCT_123e4567",
3  "created_at": "2023-06-01T15:30:00Z",
4  "funding_source_id": "123e4567-e89b-12d3-a456-426614174001",
5  "id": "123e4567-e89b-12d3-a456-426614174000",
6  "limit_balances": [
7    {
8      "available_amount": 1300,
9      "currency": "USD",
10      "reserved_amount": 120,
11      "total_amount": 1420
12    }
13  ],
14  "limit_policy": "ENFORCED",
15  "status": "ACTIVE",
16  "updated_at": "2023-06-01T15:45:30Z"
17}

Was this section helpful?

List all Program Spending Accounts

GET /api/v1/platform_liquidity_programs/{id}/program_spending_accounts

Copy for LLMView as Markdown

Retrieve a list of spending accounts associated with a Platform Liquidity Program.

Parameters

idrequiredstring

Unique identifier of the program.

pagestring

Page marker to retrieve the previous or next page of results. Set this field to the value returned by page_before or page_after to retrieve the previous or next page, respectively.

page_sizeinteger

The number of items to return per page, range [10, 100], default to 10.

Response body - 200 OK

itemsarray

Array of program spending accounts

items.limit_policystring

Policy controlling whether local spending limits are enforced

BYPASSED

ENFORCED

items.connected_account_idstring

Unique identifier of the Connected Account that the spending account is linked to

items.created_atstring

The time the spending account was created

items.funding_source_idstring

Unique identifier of the funding source. The unique identifier can be used to link a card to this program's spending account. Refer to Create Card API.

items.idstring

Unique identifier of the program spending account

items.limit_balancesarray | null

Per-currency balances when limit_policy is ENFORCED; null when limit_policy is BYPASSED

items.limit_balances.available_amountnumber

Amount available for new spending

items.limit_balances.currencystring

Three-letter ISO 4217 currency code

items.limit_balances.reserved_amountnumber

Amount reserved by pending spending

items.limit_balances.total_amountnumber

Sum of available_amount and reserved_amount

items.statusstring

Status of the spending account, either ACTIVE or INACTIVE

items.updated_atstring

The time the spending account was last updated

page_afterstring

A marker for retrieving the next page of results. Include this value in the page request parameter to retrieve subsequent pages.

page_beforestring

A marker for retrieving the previous page of results. Include this value in the page request parameter to retrieve previous pages.

Errors

Error status	Description
401	Possible errors: `credentials_invalid`, `credentials_expired`
403	`forbidden`
429	`too_many_requests`
500	`service_unavailable`

GET /api/v1/platform_liquidity_programs/{id}/program_spending_accounts

$curl --request GET \
>  --url 'https://api.sandbox.airwallex.com/api/v1/platform_liquidity_programs/platform_liquidity_program_id/program_spending_accounts' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json'

Response (200 OK)

1{
2  "items": [
3    {
4      "connected_account_id": "ACCT_123e4567",
5      "created_at": "2023-06-01T15:30:00Z",
6      "funding_source_id": "123e4567-e89b-12d3-a456-426614174001",
7      "id": "123e4567-e89b-12d3-a456-426614174000",
8      "limit_balances": [
9        {
10          "available_amount": 1300,
11          "currency": "USD",
12          "reserved_amount": 120,
13          "total_amount": 1420
14        }
15      ],
16      "limit_policy": "ENFORCED",
17      "status": "ACTIVE",
18      "updated_at": "2023-06-01T15:45:30Z"
19    }
20  ],
21  "page_after": "eyJpZCI6ImIxMjM0NSJ9",
22  "page_before": "eyJpZCI6ImEzNTUzMiJ9"
23}

Was this section helpful?

Adjust Program Spending Account Limits

POST /api/v1/platform_liquidity_programs/{id}/program_spending_accounts/{spending_account_id}/adjust_limits

Copy for LLMView as Markdown

Atomically sets limit_policy and optionally applies signed per-currency adjustments. limit_adjustments must be omitted for BYPASSED and, when supplied for ENFORCED, must be non-empty.

Parameters

idrequiredstring

Unique identifier of the program.

spending_account_idrequiredstring

Program Spending Account unique identifier.

Request body

limit_policyrequiredstring

Target limit policy.

BYPASSED

ENFORCED

request_idrequiredstring

A globally unique UUID specified by the client to ensure idempotency. If the request times out, retry with the same request_id.

limit_adjustmentsarray

Non-empty signed per-currency adjustments for ENFORCED; omitted for BYPASSED.

limit_adjustments.amountrequirednumber

Amount to adjust the available limit. Positive values increase the limit; negative values decrease it. Supports up to two decimal places.

limit_adjustments.currencyrequiredstring

Supported uppercase three-letter ISO 4217 currency code.

Response body - 200 OK

connected_account_idstring

Unique identifier of the Connected Account that the spending account is linked to

created_atstring

The time the spending account was created

funding_source_idstring

Unique identifier of the funding source. The unique identifier can be used to link a card to this program's spending account. Refer to Create Card API.

idstring

Unique identifier of the program spending account

limit_balancesarray | null

Per-currency balances when limit_policy is ENFORCED; null when limit_policy is BYPASSED

limit_balances.available_amountnumber

Amount available for new spending

limit_balances.currencystring

Three-letter ISO 4217 currency code

limit_balances.reserved_amountnumber

Amount reserved by pending spending

limit_balances.total_amountnumber

Sum of available_amount and reserved_amount

limit_policystring

Policy controlling whether local spending limits are enforced

BYPASSED

ENFORCED

statusstring

Status of the spending account, either ACTIVE or INACTIVE

updated_atstring

The time the spending account was last updated

Errors

Error status	Description
400	`validation_error`
401	Possible errors: `credentials_invalid`, `credentials_expired`
403	`forbidden`
404	`not_found`
409	`already_exists`
429	`too_many_requests`
500	Possible errors: `internal_error`, `service_unavailable`

POST /api/v1/platform_liquidity_programs/{id}/program_spending_accounts/{spending_account_id}/adjust_limits

$curl --request POST \
>  --url 'https://api.sandbox.airwallex.com/api/v1/platform_liquidity_programs/platform_liquidity_program_id/program_spending_accounts/spending_account_id/adjust_limits' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "limit_adjustments": [
>    {
>      "amount": -300,
>      "currency": "USD"
>    }
>  ],
>  "limit_policy": "ENFORCED",
>  "request_id": "550e8400-e29b-41d4-a716-446655440002"
>}'

Response (200 OK)

1{
2  "connected_account_id": "ACCT_123e4567",
3  "created_at": "2023-06-01T15:30:00Z",
4  "funding_source_id": "123e4567-e89b-12d3-a456-426614174001",
5  "id": "123e4567-e89b-12d3-a456-426614174000",
6  "limit_balances": [
7    {
8      "available_amount": 1300,
9      "currency": "USD",
10      "reserved_amount": 120,
11      "total_amount": 1420
12    }
13  ],
14  "limit_policy": "ENFORCED",
15  "status": "ACTIVE",
16  "updated_at": "2023-06-01T15:45:30Z"
17}

Was this section helpful?

List all Program Transactions

GET /api/v1/platform_liquidity_programs/{id}/transactions

Copy for LLMView as Markdown

Retrieve a list of transactions that contributed to the balance in the Platform Liquidity Program.

Parameters

idrequiredstring

Unique identifier of the program.

connected_account_idstring

Unique identifier of the Connected Account that the spending account is linked to.

currencystring

The transaction currency in 3-letter ISO-4217 format.

from_post_atstring

The start date (inclusive) of the date range during which balance activity occurred in your program fund balance. If not specified, from_post_at defaults to 7 days before to_post_at.

pagestring

Page marker to retrieve the previous or next page of results. Set this field to the value returned by page_before or page_after to retrieve the previous or next page, respectively.

page_sizeinteger

Page size, range [10, 1000], default to 100.

to_post_atstring

The end date (exclusive) of the date range during which the balance activity occurred in your program fund balance. Defaults to today if neither this field nor from_post_at are specified. If from_post_at is specified, then to_post_at defaults to 7 days after the from_post_at date.

Response body - 200 OK

itemsarray

Array of program transactions

items.amountnumber

The transaction amount

items.available_limitnumber

The available limit after this transaction

items.connected_account_idstring

Unique identifier of the Connected Account that the spending account is linked to. It will be empty for DC_CREDIT/DEBIT transactions which represent limit updates due to deposit and withdrawal.

items.currencystring

The transaction currency in 3-letter ISO-4217 format

items.idstring

Unique identifier of the transaction object

items.posted_atstring

Timestamp of the transaction posted to balance

items.source_idstring

The source transaction unique identifier. For LIQUIDITY_* related transactions, it refers to the issuing transaction unique identifier.

items.transaction_typestring

The transaction type. Can be one of: LIQUIDITY_AUTH_CREDIT / LIQUIDITY_AUTH_DEBIT: Limit balance movement between Platform Liquidity Program and program spending account for card auth and release; LIQUIDITY_FUNDING_CREDIT / LIQUIDITY_FUNDING_DEBIT: Limit balance movement between Platform Liquidity Program and program spending account for card capture and refund; DC_CREDIT: Program limit credit; DC_DEBIT: Program limit debit

page_afterstring

A marker for retrieving the next page of results. Include this value in the page request parameter to retrieve subsequent pages.

page_beforestring

A marker for retrieving the previous page of results. Include this value in the page request parameter to retrieve previous pages.

Errors

Error status	Description
401	Possible errors: `credentials_invalid`, `credentials_expired`
403	`forbidden`
404	`not_found`
429	`too_many_requests`
500	`service_unavailable`

GET /api/v1/platform_liquidity_programs/{id}/transactions

$curl --request GET \
>  --url 'https://api.sandbox.airwallex.com/api/v1/platform_liquidity_programs/platform_liquidity_program_id/transactions' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json'

Response (200 OK)

1{
2  "items": [
3    {
4      "amount": 500,
5      "available_limit": 9500,
6      "connected_account_id": "ACCT_123e4567",
7      "currency": "USD",
8      "id": "123e4567-e89b-12d3-a456-426614174000",
9      "posted_at": "2023-06-01T15:30:00Z",
10      "source_id": "123e4567-e89b-12d3-a456-426614174000",
11      "transaction_type": "LIQUIDITY_AUTH_DEBIT"
12    }
13  ],
14  "page_after": "eyJpZCI6ImIxMjM0NSJ9",
15  "page_before": "eyJpZCI6ImEzNTUzMiJ9"
16}

Was this section helpful?