PSP Settlement SplitsBeta

Platforms must share PSP Settlement Split information with Airwallex before funds settle to the holding account, by calling the Split a PSP Settlement Intent API. This data typically originates from the pay-in PSP's reporting feed.

Funds in the holding account are inaccessible to all parties until the funds are released to other connected accounts. A Platform can choose to release a PSP Settlement Split anytime. On release, funds are transferred to a connected account for the recipient, such as a seller.

If a Platform wants to apply a transaction fee to the seller, they can create one split for the amount due to the seller, and can create another split for the fee to the platform's own account. A Platform can trigger a payout from any connected account to an external bank account at any time (for example, at the end of a payout cycle). PSP Settlement Splits form part of the PSP-agnostic payout solution .

Endpoints

POST /api/v1/psp_settlement_intents/{psp_settlement_intent_id}/split
GET /api/v1/psp_settlement_splits/{id}
POST /api/v1/psp_settlement_splits/{id}/release
POST /api/v1/psp_settlement_splits/{id}/cancel
GET /api/v1/psp_settlement_splits

Split a PSP settlement intent

POST /api/v1/psp_settlement_intents/{psp_settlement_intent_id}/split

Copy for LLMView as Markdown

Use this endpoint to share data with Airwallex on the funds to be transferred to or from a target account as part of the PSP Settlement. When settlement_type is CREDIT, this is a payment to the target account. When settlement_type is DEBIT, this is a refund or chargeback.

Data on the amounts within a PSP Settlement should be shared with Airwallex before funds from the pay-in PSP settle in the holding account.

Each PSP settlement split is created with an initial status of NEW.

Parameters

psp_settlement_intent_idrequiredstring

Unique identifier of the PSP settlement intent to split

Request body

request_idrequiredstring

Unique request identifier. Max length 50 characters.

splitsrequiredarray

A (partial) list of PSP Settlement Splits that comprise the PSP Settlement Intent. Maximum 2000 PSP Settlement Splits per call to this endpoint.

splits.amountrequiredstring

Amount of the PSP settlement split, representing how much to disburse to the account. Must always be positive

splits.identifierrequiredstring

A value you select to identify this split, must be unique per PSP settlement intent, max length 40 symbols

splits.settlement_typerequiredstring

Settlement type of the split, One of CREDIT or DEBIT

splits.target_account_idrequiredstring

The Airwallex account receiving the credit or paying the debit

Response body - 200 OK

psp_settlement_intent_idstring

PSP Settlement Intent unique identifier for which this PSP Settlement Split is a part. The value is returned by the API endpoint for creating or getting a PSP Settlement Intent.

request_idstring

Unique request identifier. Max length 50 characters.

Errors

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

POST /api/v1/psp_settlement_intents/{psp_settlement_intent_id}/split

$curl --request POST \
>  --url 'https://api-demo.airwallex.com/api/v1/psp_settlement_intents/psp_settlement_intent_id/split' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "request_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",
>  "splits": [
>    {
>      "amount": "1000.5",
>      "identifier": "PMT1936398",
>      "settlement_type": "CREDIT",
>      "target_account_id": "acct_5SF2d1wFPZ-4WIHUBzOXXw"
>    }
>  ]
>}'

Response (200 OK)

1{
2  "psp_settlement_intent_id": "<string>",
3  "request_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2"
4}

Was this section helpful?

Get a PSP settlement split by ID

GET /api/v1/psp_settlement_splits/{id}

Copy for LLMView as Markdown

Get details for a PSP settlement split by specifying the split unique identifier.

Parameters

idrequiredstring

Unique identifier of the PSP settlement split to retrieve

Response body - 200 OK

amountstring

Amount of the transfer in currency specified in the request

created_atstring

The time this PSP settlement split was created

idstring

Unique identifier for the PSP settlement split

settlement_typestring

settlement type of the split, could be either CREDIT or DEBIT

statusstring

Status of the PSP settlement split. One of: NEW, MATCHED, CANCELLED, PENDING,FAILED,SETTLED

target_account_idstring

Airwallex target account unique identifier specified in the request

Errors

Error status	Description
400	Possible errors: `field_required`, `invalid_argument`
401	Possible errors: `credentials_invalid`, `credentials_expired`
404	NOT FOUND
429	Too many requests
500	Service unavailable

GET /api/v1/psp_settlement_splits/{id}

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

Response (200 OK)

1{
2  "amount": "10000",
3  "created_at": "2022-09-22T16:08:02+1100",
4  "id": "pss_78acasfou09cja",
5  "settlement_type": "CREDIT",
6  "status": "NEW",
7  "target_account_id": "acct_5SF2d1wFPZ-4WIHUBzOXXw"
8}

Was this section helpful?

Release a PSP settlement split by ID

POST /api/v1/psp_settlement_splits/{id}/release

Copy for LLMView as Markdown

Release the split when your Platform considers a seller ready to receive funds (for example, when a shopper has received goods). Funds are deducted from the holding account's balance, and are credited to the available balance of the respective seller connected accounts.

Releasing a credit split results in net movement of funds from the holding account to the seller wallet. Releasing a debit split results in movement of funds in the opposite direction (from the connected account to the holding account).

Status of the split is moved to state PENDING first when we receive the request and then updated as SETTLED when the funds movement between holding account and target account completed successfully.

Parameters

idrequiredstring

Unique identifier of the PSP settlement split to release

Request body

request_idrequiredstring

Unique request identifier. 1-50 characters long.

Response body - 200 OK

amountstring

Amount of the transfer in currency specified in the request

created_atstring

The time this PSP settlement split was created

idstring

Unique identifier for the PSP settlement split

settlement_typestring

settlement type of the split, could be either CREDIT or DEBIT

statusstring

Status of the PSP settlement split. One of: NEW, MATCHED, CANCELLED, PENDING,FAILED,SETTLED

target_account_idstring

Airwallex target account unique identifier specified in the request

Errors

Error status	Description
400	Possible errors: `field_required`, `invalid_argument`
401	Possible errors: `credentials_invalid`, `credentials_expired`
404	NOT FOUND
429	Too many requests
500	Service unavailable

POST /api/v1/psp_settlement_splits/{id}/release

$curl --request POST \
>  --url 'https://api-demo.airwallex.com/api/v1/psp_settlement_splits/psp_settlement_split_id/release' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "request_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2"
>}'

Response (200 OK)

1{
2  "amount": "10000",
3  "created_at": "2022-09-22T16:08:02+1100",
4  "id": "pss_78acasfou09cja",
5  "settlement_type": "CREDIT",
6  "status": "NEW",
7  "target_account_id": "acct_5SF2d1wFPZ-4WIHUBzOXXw"
8}

Was this section helpful?

Cancel a PSP settlement split by ID

POST /api/v1/psp_settlement_splits/{id}/cancel

Copy for LLMView as Markdown

If the PSP settlement split has not yet been matched, it can be cancelled (for example, if data had been shared wrongly previously.) After cancelling, the associated PSP settlement intent status becomes NEW. A new PSP settlement split should be created after cancellation to ensure all funds in the holding account are allocated to a seller, and the PSP settlement intent should be submitted again.

Parameters

idrequiredstring

Unique identifier of the PSP settlement split to cancel

Response body - 200 OK

amountstring

Amount of the transfer in currency specified in the request

created_atstring

The time this PSP settlement split was created

idstring

Unique identifier for the PSP settlement split

settlement_typestring

settlement type of the split, could be either CREDIT or DEBIT

statusstring

Status of the PSP settlement split. One of: NEW, MATCHED, CANCELLED, PENDING,FAILED,SETTLED

target_account_idstring

Airwallex target account unique identifier specified in the request

Errors

Error status	Description
400	Possible errors: `field_required`, `invalid_argument`
401	Possible errors: `credentials_invalid`, `credentials_expired`
404	NOT FOUND
429	Too many requests
500	Service unavailable

POST /api/v1/psp_settlement_splits/{id}/cancel

$curl --request POST \
>  --url 'https://api-demo.airwallex.com/api/v1/psp_settlement_splits/psp_settlement_split_id/cancel' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json'

Response (200 OK)

1{
2  "amount": "10000",
3  "created_at": "2022-09-22T16:08:02+1100",
4  "id": "pss_78acasfou09cja",
5  "settlement_type": "CREDIT",
6  "status": "NEW",
7  "target_account_id": "acct_5SF2d1wFPZ-4WIHUBzOXXw"
8}

Was this section helpful?

Get list of PSP settlement splits

GET /api/v1/psp_settlement_splits

Copy for LLMView as Markdown

Get list of PSP settlement splits created by your account. The splits returned are sorted by creation time in descending order.

Parameters

from_created_atstring

The start date of created_at in ISO8601 format (inclusive)

global_account_idstring

Global account unique identifier that accepted the deposit for the splits

holding_account_idstring

Airwallex holding account unique identifier

identifierstring

The value you select to identify while creating the split

page_numinteger

Page number, starts from 0

page_sizeinteger

Number of results per page. Default value is 100, minimum 10, maximum 100

psp_settlement_intent_idstring

Unique identifier of the PSP settlement intent associated with the PSP settlement splits

settlement_typestring

PSP Settlement Split settlement type. Could be either CREDIT or DEBIT

statusstring

PSP Settlement Split status. One of NEW, RELEASED, PENDING, FAILED, SETTLED or CANCELLED

target_account_idstring

Airwallex target account unique identifier

to_created_atstring

The end date of created_at in ISO8601 format (inclusive)

Response body - 200 OK

has_moreboolean

A flag which identifies whether there are more results.

itemsarray

Paged results.

items.amountstring

Amount of the transfer in currency specified in the request

items.created_atstring

The time this PSP settlement split was created

items.idstring

Unique identifier for the PSP settlement split

items.settlement_typestring

settlement type of the split, could be either CREDIT or DEBIT

items.statusstring

Status of the PSP settlement split. One of: NEW, MATCHED, CANCELLED, PENDING,FAILED,SETTLED

items.target_account_idstring

Airwallex target account unique identifier specified in the request

Errors

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

GET /api/v1/psp_settlement_splits

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

Response (200 OK)

1{
2  "has_more": false,
3  "items": [
4    {
5      "amount": "10000",
6      "created_at": "2022-09-22T16:08:02+1100",
7      "id": "pss_78acasfou09cja",
8      "settlement_type": "CREDIT",
9      "status": "NEW",
10      "target_account_id": "acct_5SF2d1wFPZ-4WIHUBzOXXw"
11    }
12  ]
13}

Was this section helpful?