Funds Splits

A Funds Split will guide you through the process to divide part of the collected funds to another destination before settling to the account that owns the funds.

You may create multiple Funds Splits for the same source of funds to send money to different destinations. However, one Funds Split will only have one destination.

You may specify the following on a Funds Split.

What is the source of funds? Denoted by source_type.
How much do you want to split? Denoted by amount.
Who will receive the funds? Denoted by destination.

Currently, Funds Split only works when the source of funds is a payment acceptance transaction, and the destinations are connected accounts to the funds owner.

Data Retention Policy: You can query and operate Funds Split resources for a maximum of 2 years since creation.

Endpoints

POST /api/v1/pa/funds_splits/create
GET /api/v1/pa/funds_splits/{id}
GET /api/v1/pa/funds_splits
POST /api/v1/pa/funds_splits/{id}/release

Create a Funds Split

POST /api/v1/pa/funds_splits/create

Copy for LLMView as Markdown

Start dividing the funds you are collecting by creating a Funds Split.

A Funds Split can be created only after the Payment Intent succeeds and before funds settlement. Subscribe to payment_intent.succeeded webhook to confirm if the payment was successful or alternatively provide funds_split_data directly in Create/Confirm/Capture a Payment Intent request.

The destination account has to pass KYC to be able to receive fund splits

The auto_release flag controls at what point the split funds will be released and settled to the destination. The behavior is as follows: * true(default) - Automatically release the split funds following the standard settlement mode. * false - Release split funds as a separate manual process by calling release.

Request body

amountrequiredstring

Amount of this split. Please refer to supported currencies for supported minor units.

destinationrequiredstring

The destination that the money is splitting to. The value could be either:

a connected account ID. Used to split funds when collecting payments directly
a platform account ID. Used to split funds when collecting payments on behalf of connected accounts
a Funds Split Destination ID. Used to split funds to an external destination.

request_idrequiredstring

Unique request identifier specified by the merchant. Maximum length is 64.

source_idrequiredstring

Unique identifier of which source this split would be created from. Currently only payment_intent_id is supported.

source_typerequiredstring

Type of the source for this split. Currently only PAYMENT_INTENT is supported.

auto_releaseboolean

Set it to false if you want to release split manually. true by default.

metadataobject

A set of key-value pairs that you can attach to the Funds Split. You can specify up to 50 keys with key names up to 50 characters long and values up to 500 characters long.

Response body - 201 Created

amountstring

Amount of this split

auto_releaseboolean

Release type of this split

created_atstring

Instant when this split is created at

currencystring

Currency of this split

destinationstring

The destination that the money is splitting to. The value could be either:

a connected account ID. Used to split funds when collecting payments directly
a platform account ID. Used to split funds when collecting payments on behalf of connected accounts

idstring

Unique identifier for the Funds Split

metadataobject

A set of key-value pairs that you can attach to the Funds Split. You can specify up to 50 keys with key names up to 50 characters long and values up to 500 characters long.

request_idstring

Unique request identifier specified by the merchant in the last operation

source_idstring

The source unique identifier of the transaction that this split is created from

source_typestring

Transaction source type, such as PAYMENT_INTENT

statusstring

Status of this split, one of CREATED, RELEASED, SETTLED

Errors

Error status	Description
400	Bad Request. Possible error codes: `validation_error`, `duplicate_request`, `operation_not_supported`
401	Unauthorized. Possible error codes: `unauthorized`
403	Forbidden
404	Not Found. Possible error codes: `not_found`(invalid url)
500	Server Error. Possible error codes: `internal_error`

POST /api/v1/pa/funds_splits/create

$curl --request POST \
>  --url 'https://api.sandbox.airwallex.com/api/v1/pa/funds_splits/create' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "request_id": "b7a93a42-fd15-4529-885f-4d4d7553f2f5",
>  "source_id": "int_hkpdskz7vg1xc7uscdj",
>  "source_type": "PAYMENT_INTENT",
>  "amount": "0.23",
>  "destination": "acct_sjnladsfjklasjd",
>  "metadata": {
>    "foo": "bar"
>  }
>}'

Response (201 Created)

1{
2  "id": "spt_hkpd1k27vg1xc7u",
3  "request_id": "b7a93a42-fd15-4529-885f-4d4d7553f2f5",
4  "source_id": "int_hkpdskz7vg1xc7uscdj",
5  "source_type": "PAYMENT_INTENT",
6  "currency": "USD",
7  "amount": "0.23",
8  "destination": "acct_sjnladsfjklasjd",
9  "status": "CREATED",
10  "auto_release": true,
11  "metadata": {
12    "foo": "bar"
13  },
14  "created_at": "2023-10-01T00:00:00+00:00"
15}

Was this section helpful?

Retrieve a Funds Split

GET /api/v1/pa/funds_splits/{id}

Copy for LLMView as Markdown

Retrieve a Funds Split by unique identifier.

Parameters

idrequiredstring

Funds Split Id.

Response body - 200 OK

amountstring

Amount of this split

auto_releaseboolean

Release type of this split

created_atstring

Instant when this split is created at

currencystring

Currency of this split

destinationstring

The destination that the money is splitting to. The value could be either:

a connected account ID. Used to split funds when collecting payments directly
a platform account ID. Used to split funds when collecting payments on behalf of connected accounts

idstring

Unique identifier for the Funds Split

metadataobject

A set of key-value pairs that you can attach to the Funds Split. You can specify up to 50 keys with key names up to 50 characters long and values up to 500 characters long.

request_idstring

Unique request identifier specified by the merchant in the last operation

source_idstring

The source unique identifier of the transaction that this split is created from

source_typestring

Transaction source type, such as PAYMENT_INTENT

statusstring

Status of this split, one of CREATED, RELEASED, SETTLED

Errors

Error status	Description
400	Bad Request. Possible error codes: `validation_error`
401	Unauthorized. Possible error codes: `unauthorized`
403	Forbidden
404	Not Found. Possible error codes: `not_found`(invalid url), `resource_not_found`
500	Server Error. Possible error codes: `internal_error`

GET /api/v1/pa/funds_splits/{id}

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

Response (200 OK)

1{
2  "id": "spt_hkpd1k27vg1xc7u",
3  "request_id": "b7a93a42-fd15-4529-885f-4d4d7553f2f5",
4  "source_id": "int_hkpdskz7vg1xc7uscdj",
5  "source_type": "PAYMENT_INTENT",
6  "currency": "USD",
7  "amount": "0.23",
8  "destination": "acct_sjnladsfjklasjd",
9  "status": "RELEASED",
10  "auto_release": true,
11  "metadata": {
12    "foo": "bar"
13  },
14  "created_at": "2023-10-01T00:00:00+00:00"
15}

Was this section helpful?

List all Funds Splits

GET /api/v1/pa/funds_splits

Copy for LLMView as Markdown

List all Fund Splits.

Parameters

source_idrequiredstring

Unique identifier of which source this split would be created from. Currently only payment_intent_id is supported.

source_typerequiredstring

Type of the source for this split. Currently only PAYMENT_INTENT is supported.

page_numinteger

Page number starting from 0.

page_sizeinteger

Number of Fund Splits to be listed per page. Default value is 10. Maximum is 1000. The value greater than the maximum will be capped to the maximum.

Response body - 200 OK

has_moreboolean

A flag which identifies whether there are more results.

itemsarray

List items

items.amountstring

Amount of this split

items.auto_releaseboolean

Release type of this split

items.created_atstring

Instant when this split is created at

items.currencystring

Currency of this split

items.destinationstring

The destination that the money is splitting to. The value could be either:

a connected account ID. Used to split funds when collecting payments directly
a platform account ID. Used to split funds when collecting payments on behalf of connected accounts

items.idstring

Unique identifier for the Funds Split

items.metadataobject

A set of key-value pairs that you can attach to the Funds Split. You can specify up to 50 keys with key names up to 50 characters long and values up to 500 characters long.

items.request_idstring

Unique request identifier specified by the merchant in the last operation

items.source_idstring

The source unique identifier of the transaction that this split is created from

items.source_typestring

Transaction source type, such as PAYMENT_INTENT

items.statusstring

Status of this split, one of CREATED, RELEASED, SETTLED

Errors

Error status	Description
400	Bad Request. Possible error codes: `validation_error`
401	Unauthorized. Possible error codes: `unauthorized`
403	Forbidden
404	Not Found. Possible error codes: `not_found`(invalid url)
500	Server Error. Possible error codes: `internal_error`

GET /api/v1/pa/funds_splits

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

Response (200 OK)

1{
2  "has_more": false,
3  "items": [
4    {
5      "id": "spt_hkpd1k27vg1xc7u",
6      "request_id": "b7a93a42-fd15-4529-885f-4d4d7553f2f5",
7      "source_id": "int_hkpdskz7vg1xc7uscdj",
8      "source_type": "PAYMENT_INTENT",
9      "currency": "USD",
10      "amount": "0.23",
11      "destination": "acct_sjnladsfjklasjd",
12      "status": "CREATED",
13      "auto_release": true,
14      "metadata": {
15        "foo": "bar"
16      },
17      "created_at": "2023-10-01T00:00:00+00:00"
18    }
19  ]
20}

Was this section helpful?

Release a Funds Split

POST /api/v1/pa/funds_splits/{id}/release

Copy for LLMView as Markdown

Call this endpoint when you are ready to let the funds arrive at the destination. A Funds Split is capturable if auto_release=false.

Parameters

idrequiredstring

Fund Split Id.

Request body

request_idrequiredstring

Unique request identifier specified by the merchant. Maximum length is 64.

Response body - 200 OK

amountstring

Amount of this split

auto_releaseboolean

Release type of this split

created_atstring

Instant when this split is created at

currencystring

Currency of this split

destinationstring

The destination that the money is splitting to. The value could be either:

a connected account ID. Used to split funds when collecting payments directly
a platform account ID. Used to split funds when collecting payments on behalf of connected accounts

idstring

Unique identifier for the Funds Split

metadataobject

A set of key-value pairs that you can attach to the Funds Split. You can specify up to 50 keys with key names up to 50 characters long and values up to 500 characters long.

request_idstring

Unique request identifier specified by the merchant in the last operation

source_idstring

The source unique identifier of the transaction that this split is created from

source_typestring

Transaction source type, such as PAYMENT_INTENT

statusstring

Status of this split, one of CREATED, RELEASED, SETTLED

Errors

Error status	Description
400	Bad Request. Possible error codes: `validation_error`, `duplicate_request`, `operation_not_supported`, `invalid_status_for_operation`
401	Unauthorized. Possible error codes: `unauthorized`
403	Forbidden
404	Not Found. Possible error codes: `not_found`(invalid url), `resource_not_found`
500	Server Error. Possible error codes: `internal_error`

POST /api/v1/pa/funds_splits/{id}/release

$curl --request POST \
>  --url 'https://api.sandbox.airwallex.com/api/v1/pa/funds_splits/spt_hkpd1k27vg1xc7u/release' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "request_id": "5894cf98-f4e4-49f6-9179-cb50e79beff5"
>}'

Response (200 OK)

1{
2  "id": "spt_hkpd1k27vg1xc7u",
3  "request_id": "5894cf98-f4e4-49f6-9179-cb50e79beff5",
4  "source_id": "int_hkpdskz7vg1xc7uscdj",
5  "source_type": "PAYMENT_INTENT",
6  "currency": "USD",
7  "amount": "0.23",
8  "destination": "acct_sjnladsfjklasjd",
9  "status": "RELEASED",
10  "auto_release": true,
11  "metadata": {
12    "foo": "bar"
13  },
14  "created_at": "2023-10-01T00:00:00+00:00"
15}

Was this section helpful?