Customer Balance Transactions
A Customer Balance Transaction records a change in the balance of funds that Airwallex holds and returns on behalf of your customer. It is used to notify you when bank transfer funds are received or reversed, including in exceptional scenarios such as overpayment, underpayment, or unmatched funding.
For bank transfer payments , the payment instructions are displayed to the shopper, 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 PaymentIntent or PaymentAttempt. Customer Balance Transactions give you clear visibility into every received fund, its status, and any reversal.
A Customer Balance Transaction has one of the following types:
bank_transfer- Adds bank transfer funds to the customer balance.bank_transfer_reversal- Reverses a previous bank transfer transaction and deducts the corresponding amount from the customer balance.applied_to_payment- Applies bank transfer funds from the customer balance to a payment, reducing the available customer balance.
Airwallex emits customer_balance_transaction webhook events as funds progress. Refer to the product documentation for the full list of events and their payloads.
This resource applies to bank transfer payments only.
GET /api/v1/pa/customer_balance_transactions/{id}
Retrieve a Customer Balance Transaction
GET /api/v1/pa/customer_balance_transactions/{id}
Retrieve a Customer Balance Transaction by unique ID.
Customer Balance Transaction unique ID.
Details of the funds applied to a payment. Present when type is applied_to_payment. If the funds are applied to several payments, a separate Customer Balance Transaction is created for each payment.
Matched payment amount.
Matched payment currency.
ID of the Customer Balance Transaction the funds were applied from.
PaymentAttempt ID that the funds were applied to.
Original amount of the PaymentIntent.
PaymentIntent ID that the funds were applied to.
Details of the bank transfer received. Present when type is bank_transfer.
The bank transfer amount received from the customer. This may be more or less than the expected payment amount, for example in overpayment or underpayment scenarios.
Bank transfer instructions provided by Airwallex for the customer to transfer the funds to.
Account holder name of the Airwallex bank account the customer transfers the funds to.
Account number of the Airwallex bank account the customer transfers the funds to.
Bank name of the Airwallex bank account the customer transfers the funds to.
Payment currency in 3-letter ISO 4217 currency code. Please refer to supported currencies .
Details of the bank transfer payer.
Payer bank account name.
Payer bank account number.
Payer bank name.
Associated Customer ID if the payer is a registered customer.
Payer email address.
Payer name.
Time when the bank transfer funds were received.
Status of the bank transfer. One of:
RECEIVED- The funds have been received.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.FAILED- The bank transfer was rejected during review or by the bank.SUCCEEDED- The bank transfer has been accepted.
RECEIVEDPENDING_REVIEWFAILEDSUCCEEDEDDetails of the bank transfer reversal. Present when type is bank_transfer_reversal.
Reversal amount.
The beneficiary of the bank transfer reversal, that is, the payer who receives the reversed funds.
Beneficiary bank account holder name.
Beneficiary bank account number. Either the account number or the IBAN is provided.
Bank name of the beneficiary's bank account.
Payment currency in 3-letter ISO 4217 currency code. Please refer to supported currencies .
ID of the Customer Balance Transaction (the original bank transfer fund record) being reversed.
The failure code for the bank transfer reversal. Returned only when the reversal failed.
The reason the bank transfer reversal failed. Returned only when the reversal failed.
Associated PaymentAttempt ID.
Associated PaymentIntent ID.
Associated Refund ID.
The remitting bank account that Airwallex sends the reversal from.
Name on the remitting bank account that Airwallex sends the reversal from.
Number of the remitting bank account that Airwallex sends the reversal from.
Reference that the merchant and payer can use to track bank transfer reversal progress with the payer's bank.
Fee charged for this bank transfer reversal.
The reason the bank transfer reversal occurred.
Status of the bank transfer reversal. One of:
CREATED- The reversal has been created.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.FAILED- The reversal failed and the funds were not returned to the payer. It was rejected during Airwallex review or by the bank. Seefailure_reasonandfailure_codefor details.SUCCEEDED- The reversal has succeeded.
CREATEDPENDING_REVIEWFAILEDSUCCEEDEDTime at which the Customer Balance Transaction was created.
Unique ID for the Customer Balance Transaction.
The transaction type. One of:
bank_transfer- Adds bank transfer funds to the customer balance.bank_transfer_reversal- Reverses a previous bank transfer transaction and deducts the corresponding amount from the customer balance.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 Customer Balance Transaction is created for each payment.
bank_transferbank_transfer_reversalapplied_to_paymentTime at which the Customer Balance Transaction was last updated or operated on.
| Error status | Description |
|---|---|
| 400 | Bad Request. Possible error codes: |
| 401 | Unauthorized. Possible error codes: |
| 403 | Forbidden |
| 404 | Not Found. Possible error codes: |
| 500 | Server Error. Possible error codes: |
$curl --request GET \> --url 'https://api.sandbox.airwallex.com/api/v1/pa/customer_balance_transactions/cbt_sgst8pzlnhkkf18vp0a' \> --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \> --header 'Content-Type: application/json'
1{2 "id": "cbt_sgst8pzlnhkkf18vp0a",3 "type": "bank_transfer",4 "created_at": "2024-06-01T10:30:05+00:00",5 "updated_at": "2024-06-01T10:30:05+00:00",6 "bank_transfer": {7 "amount": 100,8 "currency": "USD",9 "received_at": "2024-06-01T10:30:00+00:00",10 "status": "RECEIVED",11 "payer": {12 "customer_id": "cus_sgstcq8tphkfma1574m",13 "payer_name": "John Smith",14 "payer_email": "[email protected]",15 "bank_name": "Bank of America",16 "account_name": "John Smith Checking Account",17 "account_number": "1234567890"18 },19 "bank_transfer_instructions": {20 "bank_name": "Bank of America",21 "account_name": "Merchant Settlement Account",22 "account_number": "9876543210"23 }24 }25}