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.
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.
- Step 1: Share settlement data
- Step 2: Wait for intent to match deposits
- Step 3: Release settlement split
For detailed information on status changes and webhooks emitted during the PSP settlement process, see PSP settlement statuses.
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.