Log inGet started
Airwallex logo
Core API
Transactional FX
Back to home
OverviewUnderstanding Payments for PlatformsChoose your Payments for Platforms solution
Use cases
PSP agnostic
Implement your PSP-agnostic solution
Get startedHandle settlements
Deposit matchingTroubleshooting
PSP settlement statusesFunds and data flows
Hold & convert funds

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:

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.

  1. 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.
  2. 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 webhook notification. If a split creation was unsuccessful, you will receive a psp_settlement_intent.create_failed webhook.
  3. When you receive 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 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 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 payout 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.

On this page