Customer balance transactions

Understand the CustomerBalanceTransaction webhook events for bank transfer payments and when Airwallex sends each one.

CustomerBalanceTransaction applies to bank transfer payments only. This resource is currently in preview. Contact your Airwallex Account Manager to enable it for your account.

For bank transfer payments, the transfer instructions are displayed to your customer, who then manually transfers the funds through their own bank. Because the transfer is completed outside of the Airwallex checkout flow, the received funds may not always match the original Payment Intent or Payment Attempt, for example in cases of overpayment, underpayment, or funds received expiry.

The CustomerBalanceTransaction API resource records every change in the balance of funds that Airwallex holds and returns on behalf of your customer. It gives you clear visibility into each received fund, its status, and any reversal. Airwallex notifies you of these changes through customer_balance_transaction webhook events, so you can reconcile funds and keep your systems up to date without polling.

Transaction types

A CustomerBalanceTransaction has one of the following types, indicated by the type field:

Type Description

bank_transfer Adds bank transfer funds to the customer balance when a transfer is received.

applied_to_payment Applies bank transfer funds from the customer balance to a payment, reducing the available customer balance. If the funds are applied to several payments, a separate CustomerBalanceTransaction is created for each payment.

Type	Description
`bank_transfer`	Adds bank transfer funds to the customer balance when a transfer is received.
`applied_to_payment`	Applies bank transfer funds from the customer balance to a payment, reducing the available customer balance. If the funds are applied to several payments, a separate CustomerBalanceTransaction is created for each payment.
`bank_transfer_reversal`	Reverses a previous bank transfer transaction and deducts the corresponding amount from the customer balance. Airwallex automatically reverses funds back to your customer in the following scenarios: Overpayment: your customer transferred more than the expected amount. Airwallex reverses the excess amount back to them. Underpayment: your customer transferred less than the expected amount, and you have configured your account to decline underpayments. Funds received after expiry: your customer transferred funds after the payment had already expired.

bank_transfer_reversal

Reverses a previous bank transfer transaction and deducts the corresponding amount from the customer balance. Airwallex automatically reverses funds back to your customer in the following scenarios:

Overpayment: your customer transferred more than the expected amount. Airwallex reverses the excess amount back to them.
Underpayment: your customer transferred less than the expected amount, and you have configured your account to decline underpayments.
Funds received after expiry: your customer transferred funds after the payment had already expired.

Webhook events

Airwallex sends customer_balance_transaction webhook events as bank transfer funds are received, reviewed, applied to payments, or returned to the payer. To receive them, set up your webhook endpoint as described in the webhook documentation. Each event delivers the related CustomerBalanceTransaction in data.object; you can also retrieve the latest state at any time using the CustomerBalanceTransaction API API.

When Airwallex sends each event

Bank transfer events track a transfer that your customer sends. Airwallex sends these events as the received funds move through review and are accepted onto the customer balance.

Event	When Airwallex sends it
`customer_balance_transaction.bank_transfer.received`	Airwallex has received a transfer and recorded it as a bank transfer on the customer balance.
`customer_balance_transaction.bank_transfer.pending_review`	The bank transfer requires review before it can be accepted. Airwallex will send you a Request for Information (RFI) — you must respond to the RFI for the fund to be applied to the payment. Review may take several days.
`customer_balance_transaction.bank_transfer.succeeded`	The bank transfer has passed review and been accepted onto the customer balance.
`customer_balance_transaction.bank_transfer.failed`	The bank transfer was rejected during review or by the bank and will not be added to the balance.

Applied-to-payment event tells you when bank transfer funds on the customer balance are matched to a payment.

Event	When Airwallex sends it
`customer_balance_transaction.applied_to_payment`	Bank transfer funds from the customer balance have been applied to a payment. If the funds are applied to several payments, you receive one event for each payment.

Bank transfer reversal events track funds that Airwallex returns to the payer, for example an overpayment or funds that cannot be matched to a payment.

Event	When Airwallex sends it
`customer_balance_transaction.bank_transfer_reversal.created`	A reversal has been initiated to return funds to the payer.
`customer_balance_transaction.bank_transfer_reversal.pending_review`	The reversal requires review before it can proceed. Airwallex will send you a Request for Information (RFI) — you must respond to the RFI for the funds to be returned to the payer. Review may take several days.
`customer_balance_transaction.bank_transfer_reversal.succeeded`	The reversal has succeeded and the funds have been returned to the payer.
`customer_balance_transaction.bank_transfer_reversal.failed`	The reversal was rejected during review or by the bank.

Sample payloads

customer_balance_transaction.bank_transfer.received

JSON

1{
2  "id": "evt_hkdmqh6pphkfma1574m_a8z5eg",
3  "name": "customer_balance_transaction.bank_transfer.received",
4  "account_id": "acct_UZFIqlbTMOaiU5ZKcXSC_g",
5  "data": {
6    "object": {
7      "id": "cbt_hkpd12a3456hi7",
8      "type": "bank_transfer",
9      "created_at": "2024-06-01T10:30:05+0000",
10      "updated_at": "2024-06-01T10:30:05+0000",
11      "bank_transfer": {
12        "amount": 100,
13        "currency": "USD",
14        "received_at": "2024-06-01T10:30:00+0000",
15        "status": "RECEIVED",
16        "payer": {
17          "customer_id": "cus_sgstcq8tphkfma1574m",
18          "payer_name": "John Smith",
19          "payer_email": "[email protected]",
20          "bank_name": "Bank of America",
21          "bank_account_name": "John Smith Checking Account",
22          "bank_account_number": "1234567890"
23        },
24        "bank_transfer_instructions": {
25          "bank_name": "Bank of America",
26          "bank_account_name": "Merchant Settlement Account",
27          "bank_account_number": "9876543210"
28        }
29      }
30    }
31  },
32  "created_at": "2024-06-01T10:30:05+0000"
33}

customer_balance_transaction.applied_to_payment

JSON

1{
2  "id": "evt_hkdmqh6pphkfma1574m_c1d7gi",
3  "name": "customer_balance_transaction.applied_to_payment",
4  "account_id": "acct_UZFIqlbTMOaiU5ZKcXSC_g",
5  "data": {
6    "object": {
7      "id": "cbt_hkpd45x6789cd0",
8      "type": "applied_to_payment",
9      "created_at": "2024-06-01T10:31:00+0000",
10      "updated_at": "2024-06-01T10:31:00+0000",
11      "applied_to_payment": {
12        "customer_balance_transaction_id": "cbt_hkpd12a3456hi7",
13        "customer_balance_transaction_type": "bank_transfer",
14        "payment_intent_id": "int_sgstrdhvphbgua8z5eg",
15        "payment_attempt_id": "att_sgstrdhvphbguab8ma1_a8z5eg",
16        "payment_intent_amount": 80,
17        "amount": 80,
18        "currency": "USD"
19      }
20    }
21  },
22  "created_at": "2024-06-01T10:31:00+0000"
23}

customer_balance_transaction.bank_transfer_reversal.succeeded

JSON

1{
2  "id": "evt_hkdmqh6pphkfma1574m_b9c6fh",
3  "name": "customer_balance_transaction.bank_transfer_reversal.succeeded",
4  "account_id": "acct_UZFIqlbTMOaiU5ZKcXSC_g",
5  "data": {
6    "object": {
7      "id": "cbt_hkpd98z7654ba3",
8      "type": "bank_transfer_reversal",
9      "created_at": "2024-06-03T09:15:00+0000",
10      "updated_at": "2024-06-03T09:15:00+0000",
11      "bank_transfer_reversal": {
12        "customer_balance_transaction_id": "cbt_hkpd12a3456hi7",
13        "amount": 20,
14        "currency": "USD",
15        "reversal_fee": 2,
16        "reversal_reason": "overpayment",
17        "status": "SUCCEEDED",
18        "payment_intent_id": "int_sgstrdhvphbgua8z5eg",
19        "payment_attempt_id": "att_sgstrdhvphbguab8ma1_a8z5eg",
20        "remitter": {
21          "bank_account_name": "Merchant Settlement Account",
22          "bank_account_number": "9876543210",
23          "bank_reference": "W8VUMC"
24        },
25        "beneficiary": {
26          "bank_name": "Bank of America",
27          "bank_account_name": "John Smith Checking Account",
28          "bank_account_number": "1234567890"
29        }
30      }
31    }
32  },
33  "created_at": "2024-06-03T09:15:00+0000"
34}

Retrieve a customer balance transaction

To fetch the full details and all response fields of a CustomerBalanceTransaction by its ID, use the Retrieve a CustomerBalanceTransaction API API.

Shell

1curl -G 'https://api-demo.airwallex.com/api/v1/pa/customer_balance_transactions/cbt_hkpd12a3456hi7' \
2  -H 'Authorization: Bearer {{ACCESS_TOKEN}}'

Accept bank transfer payments

Learn how to initialize, confirm, and track a bank transfer payment.

Dedicated account per customer

Understand how received funds are reconciled when each customer has a dedicated account.

CustomerBalanceTransaction API

See the full API reference for the CustomerBalanceTransaction resource.

API

Was this page helpful?

Customer balance transactions

Webhook events

When Airwallex sends each event

Sample payloads

Retrieve a customer balance transaction

Related resources