PSP Settlement IntentsBeta

A PSP settlement intent represents a settlement with a PSP in a particular currency. Each PSP settlement intent is associated with one or more PSP settlement deposits by settlement_reference. After creating your PSP settlement intent, you can start splitting it, creating one PSP settlement split for each target account. Once you complete splitting your PSP settlement intent, you can submit it and wait for it to be matched with the associated PSP settlement deposit. The sum of the amounts of the PSP settlement splits of a PSP settlement intent should match the sum of the amounts of associated deposits. PSP settlement intents form part of the PSP-agnostic payout solution .

Endpoints

POST /api/v1/psp_settlement_intents/{id}/update
POST /api/v1/psp_settlement_intents/create
GET /api/v1/psp_settlement_intents/{id}
POST /api/v1/psp_settlement_intents/{id}/cancel
POST /api/v1/psp_settlement_intents/{id}/submit
GET /api/v1/psp_settlement_intents

Update a PSP settlement intent

POST /api/v1/psp_settlement_intents/{id}/update

Copy for LLMView as Markdown

Use this endpoint to update a PSP settlement intent data.

PSP settlement intent values can only be updated if the current status is NEW, ACTION_REQUIRED or SUBMITTED.

Updating any of the fields associate_by_deposit_ids, currency, global_account_id or settlement_reference on a PSP settlement intent in status ACTION_REQUIRED changes the status to SUBMITTED.

Parameters

idrequiredstring

Unique identifier of the PSP settlement intent to update

Request body

associate_by_deposit_idsarray

Unique identifiers of the deposits associated with this PSP settlement intent. If present, these will be used instead of the settlement_reference field to associate deposits with this intent.

currencystring

Currency (3-letter ISO-4217 code) of this PSP settlement intent

expected_settlement_datestring

Expected date on which these funds will be deposited by the PSP into the global account, in YYYY-MM-DD format in the UTC timezone

global_account_idstring

Global account unique identifier that will accept the funds for this PSP settlement intent

metadataobject

A set of key-value pairs that you can attach to this PSP settlement intent. This can be useful for storing additional information about it in a structured format.

request_idrequiredstring

Unique request identifier. Max length 50 characters.

settlement_referencestring

The PSP settlement reference field refers to the reference attached by the pay-in PSP when sending the deposit to Airwallex. The pay-in PSP typically also includes this reference in settlement reports. Airwallex uses this field to match the PSP settlement splits you have created with funds received from the PSP. Min length 5 characters. Max length 255 characters.

Response body - 201 Created

associate_by_deposit_idsarray

Unique identifiers of the deposits that should be associated with this PSP settlement intent. If present, these will be used instead of the settlement_reference field to associate deposits with this intent.

associated_deposit_idsarray

Unique identifiers of the deposits currently associated with this PSP settlement intent. If associate_by_deposit_ids is not empty, then these have been associated based on that list. Otherwise, they are associated by reference.

created_atstring

The time this PSP settlement intent was created

currencystring

Currency (3-letter ISO-4217 code) specified in the request

expected_settlement_datestring

Expected date on which these funds will be deposited by the PSP into the global account, in YYYY-MM-DD format in the UTC timezone.

global_account_idstring

The unique identifier of the global account in which this settlement will be deposited.

idstring

Unique identifier for the PSP settlement intent

metadataobject

A set of key-value pairs that you can attach to the PSP settlement intent

request_idstring

Unique request identifier specified in the request

requirementsobject

Further actions required in order to proceed with this settlement intent

requirements.matching_psp_settlement_requiredobject

Funds have been received that correspond to this PSP settlement intent, but the total amounts do not match

requirements.matching_psp_settlement_required.messagestring

Information about this requirement

requirements.reference_disambiguation_requiredobject

PSP settlement deposit reference corresponds to multiple PSP settlement intents

requirements.reference_disambiguation_required.messagestring

settlement_referencestring

The reference value expected to be included by the PSP in its PSP settlement deposit.

statusstring

Status of the PSP settlement intent. One of: NEW, SUBMITTED, ACTION_REQUIRED, MATCHED, SETTLED

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/{id}/update

$curl --request POST \
>  --url 'https://api-demo.airwallex.com/api/v1/psp_settlement_intents/psp_settlement_intent_id/update' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "associate_by_deposit_ids": [],
>  "currency": "USD",
>  "expected_settlement_date": "2022-08-26",
>  "global_account_id": "3f457fe5-daf4-9962-92ec-10332301d9p3",
>  "metadata": {},
>  "request_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",
>  "settlement_reference": "PMT1936398"
>}'

Response (201 Created)

1{
2  "associate_by_deposit_ids": [],
3  "associated_deposit_ids": [],
4  "created_at": "2022-09-22T16:08:02+1100",
5  "currency": "AUD",
6  "expected_settlement_date": "2022-08-26",
7  "global_account_id": "3f457fe5-daf4-9962-92ec-10332301d9p3",
8  "id": "psi_0iBwL9IuOZaKCz8Kn-01ew",
9  "metadata": {},
10  "request_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",
11  "requirements": {
12    "matching_psp_settlement_required": {
13      "message": "<string>"
14    },
15    "reference_disambiguation_required": {
16      "message": "<string>"
17    }
18  },
19  "settlement_reference": "PMT1936398",
20  "status": "NEW"
21}

Was this section helpful?

Create a new PSP settlement intent

POST /api/v1/psp_settlement_intents/create

Copy for LLMView as Markdown

Use this endpoint to share data with Airwallex on the settlement to be deposited by the PSP.

Data on a PSP Settlement should be shared with Airwallex before the pay-in PSP deposits funds into the holding account.

PSP settlement intent is created with initial status NEW.

Request body

associate_by_deposit_idsarray

Unique identifiers of the deposits associated with this PSP settlement intent. If present, these will be used instead of the settlement_reference field to associate deposits with this intent.

currencyrequiredstring

Currency (3-letter ISO-4217 code) of this PSP settlement intent

expected_settlement_daterequiredstring

Expected date on which these funds will be deposited by the PSP into the global account, in YYYY-MM-DD format in the UTC timezone

global_account_idrequiredstring

Global account unique identifier that will accept the deposit for this PSP settlement intent

metadataobject

A set of key-value pairs that you can attach to this PSP settlement intent. This can be useful for storing additional information about it in a structured format.

request_idrequiredstring

Unique request identifier. Max length 50 characters

settlement_referencerequiredstring

Response body - 201 Created

associate_by_deposit_idsarray

associated_deposit_idsarray

created_atstring

The time this PSP settlement intent was created

currencystring

Currency (3-letter ISO-4217 code) specified in the request

expected_settlement_datestring

Expected date on which these funds will be deposited by the PSP into the global account, in YYYY-MM-DD format in the UTC timezone.

global_account_idstring

The unique identifier of the global account in which this settlement will be deposited.

idstring

Unique identifier for the PSP settlement intent

metadataobject

A set of key-value pairs that you can attach to the PSP settlement intent

request_idstring

Unique request identifier specified in the request

requirementsobject

Further actions required in order to proceed with this settlement intent

requirements.matching_psp_settlement_requiredobject

Funds have been received that correspond to this PSP settlement intent, but the total amounts do not match

requirements.matching_psp_settlement_required.messagestring

Information about this requirement

requirements.reference_disambiguation_requiredobject

PSP settlement deposit reference corresponds to multiple PSP settlement intents

requirements.reference_disambiguation_required.messagestring

settlement_referencestring

The reference value expected to be included by the PSP in its PSP settlement deposit.

statusstring

Status of the PSP settlement intent. One of: NEW, SUBMITTED, ACTION_REQUIRED, MATCHED, SETTLED

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/create

$curl --request POST \
>  --url 'https://api-demo.airwallex.com/api/v1/psp_settlement_intents/create' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "associate_by_deposit_ids": [],
>  "currency": "USD",
>  "expected_settlement_date": "2022-08-26",
>  "global_account_id": "3f457fe5-daf4-9962-92ec-10332301d9p3",
>  "metadata": {},
>  "request_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",
>  "settlement_reference": "PMT1936398"
>}'

Response (201 Created)

1{
2  "associate_by_deposit_ids": [],
3  "associated_deposit_ids": [],
4  "created_at": "2022-09-22T16:08:02+1100",
5  "currency": "AUD",
6  "expected_settlement_date": "2022-08-26",
7  "global_account_id": "3f457fe5-daf4-9962-92ec-10332301d9p3",
8  "id": "psi_0iBwL9IuOZaKCz8Kn-01ew",
9  "metadata": {},
10  "request_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",
11  "requirements": {
12    "matching_psp_settlement_required": {
13      "message": "<string>"
14    },
15    "reference_disambiguation_required": {
16      "message": "<string>"
17    }
18  },
19  "settlement_reference": "PMT1936398",
20  "status": "NEW"
21}

Was this section helpful?

Get a PSP settlement intent by ID

GET /api/v1/psp_settlement_intents/{id}

Copy for LLMView as Markdown

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

Parameters

idrequiredstring

Unique identifier of the PSP settlement intent to retrieve

Response body - 200 OK

associate_by_deposit_idsarray

associated_deposit_idsarray

created_atstring

The time this PSP settlement intent was created

currencystring

Currency (3-letter ISO-4217 code) specified in the request

expected_settlement_datestring

Expected date on which these funds will be deposited by the PSP into the global account, in YYYY-MM-DD format in the UTC timezone.

global_account_idstring

The unique identifier of the global account in which this settlement will be deposited.

idstring

Unique identifier for the PSP settlement intent

metadataobject

A set of key-value pairs that you can attach to the PSP settlement intent

request_idstring

Unique request identifier specified in the request

requirementsobject

Further actions required in order to proceed with this settlement intent

requirements.matching_psp_settlement_requiredobject

Funds have been received that correspond to this PSP settlement intent, but the total amounts do not match

requirements.matching_psp_settlement_required.messagestring

Information about this requirement

requirements.reference_disambiguation_requiredobject

PSP settlement deposit reference corresponds to multiple PSP settlement intents

requirements.reference_disambiguation_required.messagestring

settlement_referencestring

The reference value expected to be included by the PSP in its PSP settlement deposit.

statusstring

Status of the PSP settlement intent. One of: NEW, SUBMITTED, ACTION_REQUIRED, MATCHED, SETTLED

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_intents/{id}

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

Response (200 OK)

1{
2  "associate_by_deposit_ids": [],
3  "associated_deposit_ids": [],
4  "created_at": "2022-09-22T16:08:02+1100",
5  "currency": "AUD",
6  "expected_settlement_date": "2022-08-26",
7  "global_account_id": "3f457fe5-daf4-9962-92ec-10332301d9p3",
8  "id": "psi_0iBwL9IuOZaKCz8Kn-01ew",
9  "metadata": {},
10  "request_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",
11  "requirements": {
12    "matching_psp_settlement_required": {
13      "message": "<string>"
14    },
15    "reference_disambiguation_required": {
16      "message": "<string>"
17    }
18  },
19  "settlement_reference": "PMT1936398",
20  "status": "NEW"
21}

Was this section helpful?

Cancel a PSP settlement intent by ID

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

Copy for LLMView as Markdown

Use this endpoint to cancel a PSP Settlement intent.

If the PSP settlement intent has been cancelled already or matched or settled with the corresponding PSP settlement deposit, then it cannot be cancelled.

Parameters

idrequiredstring

Unique identifier of the PSP settlement intent to cancel

Response body - 200 OK

associate_by_deposit_idsarray

associated_deposit_idsarray

created_atstring

The time this PSP settlement intent was created

currencystring

Currency (3-letter ISO-4217 code) specified in the request

expected_settlement_datestring

Expected date on which these funds will be deposited by the PSP into the global account, in YYYY-MM-DD format in the UTC timezone.

global_account_idstring

The unique identifier of the global account in which this settlement will be deposited.

idstring

Unique identifier for the PSP settlement intent

metadataobject

A set of key-value pairs that you can attach to the PSP settlement intent

request_idstring

Unique request identifier specified in the request

requirementsobject

Further actions required in order to proceed with this settlement intent

requirements.matching_psp_settlement_requiredobject

Funds have been received that correspond to this PSP settlement intent, but the total amounts do not match

requirements.matching_psp_settlement_required.messagestring

Information about this requirement

requirements.reference_disambiguation_requiredobject

PSP settlement deposit reference corresponds to multiple PSP settlement intents

requirements.reference_disambiguation_required.messagestring

settlement_referencestring

The reference value expected to be included by the PSP in its PSP settlement deposit.

statusstring

Status of the PSP settlement intent. One of: NEW, SUBMITTED, ACTION_REQUIRED, MATCHED, SETTLED

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_intents/{id}/cancel

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

Response (200 OK)

1{
2  "associate_by_deposit_ids": [],
3  "associated_deposit_ids": [],
4  "created_at": "2022-09-22T16:08:02+1100",
5  "currency": "AUD",
6  "expected_settlement_date": "2022-08-26",
7  "global_account_id": "3f457fe5-daf4-9962-92ec-10332301d9p3",
8  "id": "psi_0iBwL9IuOZaKCz8Kn-01ew",
9  "metadata": {},
10  "request_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",
11  "requirements": {
12    "matching_psp_settlement_required": {
13      "message": "<string>"
14    },
15    "reference_disambiguation_required": {
16      "message": "<string>"
17    }
18  },
19  "settlement_reference": "PMT1936398",
20  "status": "NEW"
21}

Was this section helpful?

Submit a PSP settlement intent by ID

POST /api/v1/psp_settlement_intents/{id}/submit

Copy for LLMView as Markdown

Submit a PSP settlement intent.

This means all PSP settlement split information for a PSP settlement intent has been provided, and it is ready to be matched with a PSP settlement deposit.

Parameters

idrequiredstring

Unique identifier of the PSP settlement intent to submit

Response body - 200 OK

associate_by_deposit_idsarray

associated_deposit_idsarray

created_atstring

The time this PSP settlement intent was created

currencystring

Currency (3-letter ISO-4217 code) specified in the request

expected_settlement_datestring

Expected date on which these funds will be deposited by the PSP into the global account, in YYYY-MM-DD format in the UTC timezone.

global_account_idstring

The unique identifier of the global account in which this settlement will be deposited.

idstring

Unique identifier for the PSP settlement intent

metadataobject

A set of key-value pairs that you can attach to the PSP settlement intent

request_idstring

Unique request identifier specified in the request

requirementsobject

Further actions required in order to proceed with this settlement intent

requirements.matching_psp_settlement_requiredobject

Funds have been received that correspond to this PSP settlement intent, but the total amounts do not match

requirements.matching_psp_settlement_required.messagestring

Information about this requirement

requirements.reference_disambiguation_requiredobject

PSP settlement deposit reference corresponds to multiple PSP settlement intents

requirements.reference_disambiguation_required.messagestring

settlement_referencestring

The reference value expected to be included by the PSP in its PSP settlement deposit.

statusstring

Status of the PSP settlement intent. One of: NEW, SUBMITTED, ACTION_REQUIRED, MATCHED, SETTLED

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_intents/{id}/submit

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

Response (200 OK)

1{
2  "associate_by_deposit_ids": [],
3  "associated_deposit_ids": [],
4  "created_at": "2022-09-22T16:08:02+1100",
5  "currency": "AUD",
6  "expected_settlement_date": "2022-08-26",
7  "global_account_id": "3f457fe5-daf4-9962-92ec-10332301d9p3",
8  "id": "psi_0iBwL9IuOZaKCz8Kn-01ew",
9  "metadata": {},
10  "request_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",
11  "requirements": {
12    "matching_psp_settlement_required": {
13      "message": "<string>"
14    },
15    "reference_disambiguation_required": {
16      "message": "<string>"
17    }
18  },
19  "settlement_reference": "PMT1936398",
20  "status": "NEW"
21}

Was this section helpful?

Get a list of PSP settlement intents

GET /api/v1/psp_settlement_intents

Copy for LLMView as Markdown

Get a list of PSP settlement intents created by your account. The intents 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 of the PSP settlement intents

page_numinteger

Page number, starts from 0

page_sizeinteger

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

settlement_referencestring

Settlement reference that has been specified while creating PSP settlement intents

statusstring

PSP Settlement Intent status. One of NEW, SUBMITTED, MATCHED, ACTION_REQUIRED, SETTLED, CANCELLED

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.associate_by_deposit_idsarray

items.associated_deposit_idsarray

items.created_atstring

The time this PSP settlement intent was created

items.currencystring

Currency (3-letter ISO-4217 code) specified in the request

items.expected_settlement_datestring

Expected date on which these funds will be deposited by the PSP into the global account, in YYYY-MM-DD format in the UTC timezone.

items.global_account_idstring

The unique identifier of the global account in which this settlement will be deposited.

items.idstring

Unique identifier for the PSP settlement intent

items.metadataobject

A set of key-value pairs that you can attach to the PSP settlement intent

items.request_idstring

Unique request identifier specified in the request

items.requirementsobject

Further actions required in order to proceed with this settlement intent

items.requirements.matching_psp_settlement_requiredobject

Funds have been received that correspond to this PSP settlement intent, but the total amounts do not match

items.requirements.matching_psp_settlement_required.messagestring

Information about this requirement

items.requirements.reference_disambiguation_requiredobject

PSP settlement deposit reference corresponds to multiple PSP settlement intents

items.requirements.reference_disambiguation_required.messagestring

items.settlement_referencestring

The reference value expected to be included by the PSP in its PSP settlement deposit.

items.statusstring

Status of the PSP settlement intent. One of: NEW, SUBMITTED, ACTION_REQUIRED, MATCHED, SETTLED

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_intents

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

Response (200 OK)

1{
2  "has_more": false,
3  "items": [
4    {
5      "associate_by_deposit_ids": [],
6      "associated_deposit_ids": [],
7      "created_at": "2022-09-22T16:08:02+1100",
8      "currency": "AUD",
9      "expected_settlement_date": "2022-08-26",
10      "global_account_id": "3f457fe5-daf4-9962-92ec-10332301d9p3",
11      "id": "psi_0iBwL9IuOZaKCz8Kn-01ew",
12      "request_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",
13      "settlement_reference": "PMT1936398",
14      "status": "NEW"
15    }
16  ]
17}

Was this section helpful?