Handle settlements

This page describes how to settle funds into the connected accounts of your sellers using the settlement reports and deposits received from acquiring PSPs.

Before you begin

To implement a PSP-agnostic solution, platforms must:

Set up the required Airwallex accounts and reconciliation database as described in Get started.
Obtain your access token API by authenticating to Airwallex using your unique Client ID and API key. You will need the access token to make API calls.
Maintain an integration with acquiring PSPs and agree in advance on the format of the settlement reference. This enables the platform to share this reference information as part of the PSP settlement intent before the deposit arrives from the PSP.
Instruct acquiring PSPs to settle to a Global Account (in an aggregate settlement, with funds for all sellers grouped into one settlement) at a frequency they may specify.
Subscribe to these webhook events as a minimum, but to explore the full range of supported webhooks, see PSP-agnostic webhook events.
- psp_settlement_intent.action_required
- psp_settlement_intent.matched
- psp_settlement_split.new
- psp_settlement_split.create_failed
- psp_settlement_split.failed
- psp_settlement_split.settled
- psp_settlement_deposit.action_required

Recommended handling

The diagram below shows the end-to-end information flow when processing PSP settlements into sellers' connected accounts using Airwallex APIs.

Handling PSP settlements

After performing the pre-integration steps described in Before you begin, use Airwallex PSP Settlement APIs to process settlements for sellers. The details are described using the steps below.

For detailed information on status changes and webhooks emitted during the PSP settlement process, see PSP settlement statuses.

Step 1: Share settlement data

When the platform receives settlement reports with the predetermined settlement reference from the acquiring PSP, the platform must extract the amount each seller should be paid.

To comply with EU regulations, the platform must share the settlement split data with Airwallex before the PSP funds settle in the platform's Holding Account.

Call Create a new PSP Settlement Intent API with the predetermined reference in the settlement_reference field. This reference will also be passed by the acquiring PSP through the banking rails when the funds are deposited to your Holding Account. You can optionally specify deposits using the associate_by_deposit_ids field. If you do then this field will be used for matching, and the intent’s and deposits’ references will be ignored.
Split the intent using Split the PSP Settlement Intent API. The creation of splits is asynchronous so to check if each split was created successfully, wait for the psp_settlement_split.new webhook notification. If a split creation was unsuccessful, you will receive a psp_settlement_intent.create_failed webhook.
When you receive psp_settlement_split.new webhooks for all the PSP settlement splits in an intent, call Submit the PSP Settlement intent API, in order to make it eligible for matching with the deposits. This should be done before any PSP funds are deposited into your Holding Account.

If a PSP settlement intent is submitted before all the psp_settlement_split.new webhooks are received, some of the splits may not get included.

Handle incorrect data

If the platform shared incorrect data with Airwallex, the platform has three options:

Option 1: Cancel any incorrect PSP settlement split
1. Call Cancel a PSP Settlement Split API with the split identifier. The PSP settlement split status changes to CANCELLED, and a psp_settlement_split.cancelled webhook is sent.
2. Create a new settlement split using Split the PSP Settlement Intent API (unless cancelling a duplicate) immediately after cancellation to ensure all funds in your Holding Account are allocated to a seller.
  Note: Canceling a PSP settlement split causes the corresponding PSP settlement intent status to return to NEW, and, if it had already been submitted, it must be submitted again to be eligible for matching.
Option 2: Cancel the PSP settlement intent and start over
1. Call Cancel a PSP Settlement Intent API with the intent id. The PSP settlement intent status changes to CANCELLED, and a psp_settlement_intent.cancelled webhook is sent.
2. Start with the steps described in Step 1: Share settlement data.
  The status of all PSP settlement splits comprising this PSP settlement intent also change to CANCELLED, but no webhooks are sent.
Option 3: Update the PSP settlement intent
1. Call Update a PSP Settlement Intent API to amend incorrect data.
  Note: Updating a PSP settlement intent in ACTION_REQUIRED status causes the status to change to SUBMITTED, and a psp_settlement_intent.submitted webhook is sent.

Step 2: Wait for intent to match deposit(s)

After submitting the PSP settlement intent, wait for the acquiring PSP to deposit the funds described in the PSP settlement intent into the Holding Account. The PSP deposits funds to a Global Account connected to the platform's Holding Account and includes the predetermined reference in the bank transfer description. When the deposit is successfully created, Airwallex creates a PSP settlement deposit with status NEW, sends a psp_settlement_deposit.new webhook, and starts the matching process.

Airwallex uses the settlement reference to associate unmatched PSP settlement deposits with their corresponding PSP settlement intents. If an association is made, the amount of the splits is calculated and compared with the total amount of the associated deposit (or the total amounts of multiple deposits, if intermediate banks divide the settlement into more than one).

The platform receives the results of matching attempts whether successful or unsuccessful via webhooks. For more information on the deposit matching process, see Deposit matching.

Specifically, wait for the psp_settlement_intent.matched or psp_settlement_intent.action_required webhook because you cannot proceed to release splits until the PSP settlement intent is matched with its corresponding deposit(s).

Step 3: Release settlement splits

When the platform receives a webhook notification indicating that the PSP settlement intent has been successfully matched with the associated PSP settlement deposit(s), then the PSP settlement splits are ready to be released. We recommend subscribing to the psp_settlement_intent.matched webhook for this purpose, but all of the following webhooks are sent together:

psp_settlement_intent.matched
psp_settlement_split.matched
psp_settlement_deposit.matched

When the seller meets platform's criteria for a release, e.g., shopper has received goods, end of billing cycle, or immediately upon successful matching, for each PSP settlement split, call Release a PSP Settlement Split API.

Successful split release

For a CREDIT split, if the Holding Account and Collateral Accounts have sufficient funds, then funds will move from the Holding Account to the seller's connected account wallet.
For a DEBIT split, if the seller's account has sufficient funds, then funds will move from the seller's connected account wallet to the Holding Account.

When a release settles, a psp_settlement_split.settled webhook is sent. When releases have settled for all PSP settlement splits, the statuses of the PSP settlement intent and the PSP settlement deposit(s) also change to SETTLED and the following webhooks are sent.

psp_settlement_intent.settled
psp_settlement_deposit.settled

You can call Create a transfer API to move funds from the seller's connected account Wallet to the external bank account.

Unsuccessful split release

A split release could fail, for example, due to insufficient funds. See Troubleshooting for information on how to handle unsuccessful settlements.