Search...
Log inGet started
Airwallex logo
Home
Core API
Payments
Transactional FX
Payouts
Issuing
Embedded Finance
Global Treasury
Banking as a Service
Payments for Platforms
Developer Tools
Trust Center
Business Account Help Center
API Reference
Back to home
OverviewUnderstanding Payments for PlatformsChoose your Payments for Platforms solution
Airwallex gateway
PSP agnostic
PSP-agnostic solution overviewImplement your PSP-agnostic solution
Get startedHandle settlementsDeposit matching
Troubleshooting
PSP settlement statuses
Hold & convert funds
Pay out funds
Connected accounts
Platform operations
Risk

Deposit matching

Airwallex uses the settlement reference to match PSP settlement deposits with their corresponding PSP settlement intents. This section describes the matching process and how to get notified when matching succeeds or fails.

Matching process

At a regular time interval, Airwallex checks all unmatched PSP settlement deposits (in status NEW or ACTION_REQUIRED) and associates them with PSP settlement intents, based on the deposit reference. If the amount of the PSP settlement deposits is the same as the amount of the associated intent, it's a match.

Note the following about the matching process:

  • The settlement reference in the PSP settlement intent and the deposit reference included in the PSP settlement deposit need not be an exact match. Since intermediate banks may append additional text before or after the deposit reference, it need only include the intent’s settlement reference within it for a match. For example, if the PSP settlement intent has "settlement_reference": "hello", and the PSP settlement deposit has "reference": "123hello456", these will match.
  • While Airwallex normally expects a settlement amount to be sent to a Global Account as a single deposit, intermediate banks may choose to divide it into multiple deposits. As long as these deposits all have a deposit reference that matches the settlement reference of the same PSP settlement intent, and the sum of their amounts matches the amount of the intent, then the deposits will all be matched with the intent.
  • The platform must submit the PSP settlement intent with its PSP settlement splits before the associated deposit (or deposits) arrive in order to be compliant with EU regulations.

Airwallex will notify the platform of the results of whether matching was successful or not using webhooks notifications.

Success notifications

If the amounts match, the status of the matched intent, splits, and deposits will all be changed to MATCHED, and webhooks will be sent of type:

  • psp_settlement_intent.matched
  • psp_settlement_split.matched
  • psp_settlement_deposit.matched

After matching, the settlement can no longer be changed. Any deposits that arrive afterwards with a reference that matches this intent’s settlement reference will not be associated with this intent, but will only be eligible for matching with the settlement references of unmatched intents.

Failure notifications

There are several situations which can cause an unsuccessful match, and they all result in ACTION_REQUIRED statuses and action_required webhooks, with further details provided in the requirements field. The webhooks sent in each scenario are described in the table below.

You can retrieve the API response payload, including the status and requirements of the intent and deposit, anytime using Get a PSP settlement intent API and Get a list of PSP settlement deposits API

Scenario Emitted webhook Next steps
A PSP settlement deposit has arrived, but there is no PSP settlement intent with a matching settlement reference. The PSP settlement deposit status will be set to ACTION_REQUIRED. psp_settlement_deposit.action_required, containing the requirement psp_settlement_intent_required Check if the deposit reference includes the reference passed in the intent's settlement_reference field.
  • If yes, and if the intent's status is NEW then proceed to submit the intent.
  • If no, check if the PSP settlement intent has already been created for this deposit with the wrong reference.
    • If yes, update the PSP settlement intent, or cancel it and create a new one.
    • Otherwise, create a new PSP settlement intent with the same settlement_reference as the deposit OR use the associate_by_deposit_ids field to specify the deposit id(s) that should be associated with the intent. The deposit ID currently associated with an intent can be found in the associated_deposit_ids field of the PSP intent’s webhook payload, and the PSP settlement intent IDs associated with any deposits can be found in the psp_settlement_intent_id field of any PSP settlement deposit’s webhook payload.
The amount of the PSP settlement intent (that is, the sum of the amounts of all its PSP settlement splits) does not match the amount of the associated PSP settlement deposit(s). The statuses of both intent and deposit will be set to ACTION_REQUIRED. psp_settlement_deposit.action_required, containing the requirement matching_psp_settlement_required

psp_settlement_intent.action_required, containing the requirement matching_psp_settlement_required		 If you are expecting other deposits to arrive with the same reference, you can wait until you receive webhooks for all the deposits of this settlement.

If you are not expecting other deposits to arrive,
  • Check if there are PSP settlement splits that should not be in this PSP settlement intent. If yes, cancel the split OR cancel the intent and create a new one, and then submit it.
  • Check if any PSP settlement splits are missing from the intent. If yes, add them by splitting the PSP settlement intent OR cancel the intent and create a new one, and then submit it.
  • Check if the deposit is associated with the wrong PSP settlement intent. If yes, update the intent or cancel it, and create/submit a new one, with the correct deposit id(s) in the associate_by_deposit_id field.
psp_settlement_deposit.action_required, containing the requirement reference_disambiguation_required

psp_settlement_intent.action_required, containing the requirement reference_disambiguation_required		 More than one submitted PSP settlement intent has a settlement reference that matches the same PSP settlement deposit. The statuses of intents and deposit(s) both will be set to ACTION_REQUIRED. Check for any erroneous PSP settlement intents, and if found, cancel them.

Otherwise, use the PSP settlement intent's associate_by_deposit_ids field to specify the deposit id(s) that should be associated with the intent, and then submit the intent. The deposit IDs currently associated with an intent can be found in the associated_deposit_ids field of the PSP intent’s webhook payload, and the PSP settlement intent IDs associated with any deposits can be found in the psp_settlement_intent_id field of any PSP settlement deposit’s webhook payload.
On this page
  • Matching process
  • Success notifications
  • Failure notifications