Airwallex logo

Platform Liquidity Programs

Copy for LLMView as Markdown

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 ProgramBeta

GET /api/v1/platform_liquidity_programs/{id}

Retrieve a Program is in beta
We may include major new functionality or changes before general release. Learn more about beta.Docs

Retrieve details of a Platform Liquidity Program.

Path 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_connected_account_regionsarray

Array of two-letter region codes, in ISO 3166-1 alpha-2 format, that determine which connected account regions may onboard to this program.

supported_currenciesarray

(Deprecated) 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 statusDescription
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 "supported_connected_account_regions": [
13 "HK",
14 "SG"
15 ],
16 "name": "Merchant A Program",
17 "status": "ACTIVE",
18 "supported_currencies": [
19 {
20 "currency": "HKD",
21 "low_balance_threshold": 1000
22 }
23 ],
24 "updated_at": "2023-06-01T15:45:30Z"
25}
Was this section helpful?

Deposit Funds Into a ProgramBeta

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

Deposit Funds Into a Program is in beta
We may include major new functionality or changes before general release. Learn more about beta.Docs

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

Path 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_connected_account_regionsarray

Array of two-letter region codes, in ISO 3166-1 alpha-2 format, that determine which connected account regions may onboard to this program.

supported_currenciesarray

(Deprecated) 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 statusDescription
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 "supported_connected_account_regions": [
13 "HK",
14 "SG"
15 ],
16 "name": "Merchant A Program",
17 "status": "ACTIVE",
18 "supported_currencies": [
19 {
20 "currency": "HKD",
21 "low_balance_threshold": 1000
22 }
23 ],
24 "updated_at": "2023-06-01T15:45:30Z"
25}
Was this section helpful?

Withdraw Funds From a ProgramBeta

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

Withdraw Funds From a Program is in beta
We may include major new functionality or changes before general release. Learn more about beta.Docs

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

Path 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_connected_account_regionsarray

Array of two-letter region codes, in ISO 3166-1 alpha-2 format, that determine which connected account regions may onboard to this program.

supported_currenciesarray

(Deprecated) 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 statusDescription
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 "supported_connected_account_regions": [
13 "HK",
14 "SG"
15 ],
16 "name": "Merchant A Program",
17 "status": "ACTIVE",
18 "supported_currencies": [
19 {
20 "currency": "HKD",
21 "low_balance_threshold": 1000
22 }
23 ],
24 "updated_at": "2023-06-01T15:45:30Z"
25}
Was this section helpful?

Create a Program Spending AccountBeta

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

Create a Program Spending Account is in beta
We may include major new functionality or changes before general release. Learn more about beta.Docs

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

Path 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. Use this identifier to link a card to the program's spending account. Refer to Create a Card.

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 statusDescription
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 AccountBeta

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

Retrieve a Program Spending Account is in beta
We may include major new functionality or changes before general release. Learn more about beta.Docs

Retrieve details of a program spending account.

Path 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. Use this identifier to link a card to the program's spending account. Refer to Create a Card.

idstring

Unique identifier of the program spending account.

limit_balancesarray

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 statusDescription
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 AccountsBeta

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

List all Program Spending Accounts is in beta
We may include major new functionality or changes before general release. Learn more about beta.Docs

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

Path parameters
idrequiredstring

Unique identifier of the program.

Query parameters
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. Use this identifier to link a card to the program's spending account. Refer to Create a Card.

items.idstring

Unique identifier of the program spending account.

items.limit_balancesarray

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 statusDescription
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 LimitsBeta

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

Adjust Program Spending Account Limits is in beta
We may include major new functionality or changes before general release. Learn more about beta.Docs

Updates a spending account's spending limits. Set limit_policy to ENFORCED to apply per-currency limits, or BYPASSED to turn them off. When enforcing, you can include limit_adjustments to raise or lower each currency's limit (a positive amount increases it, a negative amount decreases it). Leave limit_adjustments out when limit_policy is BYPASSED.

Path 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. Use this identifier to link a card to the program's spending account. Refer to Create a Card.

idstring

Unique identifier of the program spending account.

limit_balancesarray

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 statusDescription
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 TransactionsBeta

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

List all Program Transactions is in beta
We may include major new functionality or changes before general release. Learn more about beta.Docs

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

Path parameters
idrequiredstring

Unique identifier of the program.

Query parameters
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 to which the spending account is linked. Empty for DC_CREDIT/DEBIT transactions, which represent limit updates resulting from deposits and withdrawals.

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

Unique identifier of the source transaction. For LIQUIDITY_* transactions, this is the Issuing card transaction event identifier, which can be retrieved using Retrieve a Card Transaction Event. For DC_CREDIT and DC_DEBIT transactions, this is the financial transaction identifier, which can be looked up using List Financial Transactions by passing it as the source_id query parameter.

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 statusDescription
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?