Funds Splits

A FundsSplit 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 FundsSplits for the same source of funds to send money to different destinations. However, one FundsSplit will only have one destination.

You may specify the following on a FundsSplit.

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, FundsSplit 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 FundsSplit 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 FundsSplit

POST /api/v1/pa/funds_splits/create

Copy for LLMView as Markdown

Start dividing the funds you are collecting by creating a FundsSplit.

A FundsSplit can be created only after the PaymentIntent 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 PaymentIntent 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.

auto_releaseboolean

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

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 FundsSplitDestination ID. Used to split funds to an external destination.

metadataobject

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

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

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 FundsSplit

metadataobject

A set of key-value pairs that you can attach to the FundsSplit. 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-demo.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 FundsSplit

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

Copy for LLMView as Markdown

Retrieve a FundsSplit by unique identifier

Parameters

idrequiredstring

FundsSplit 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 FundsSplit

metadataobject

A set of key-value pairs that you can attach to the FundsSplit. 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-demo.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?

Get list of FundsSplits

GET /api/v1/pa/funds_splits

Copy for LLMView as Markdown

Retrieve list of FundSplits

Parameters

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.

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

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 FundsSplit

items.metadataobject

A set of key-value pairs that you can attach to the FundsSplit. 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-demo.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 FundsSplit

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 FundsSplit is capturable if auto_release=false.

Parameters

idrequiredstring

FundSplit 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 FundsSplit

metadataobject

A set of key-value pairs that you can attach to the FundsSplit. 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-demo.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?