Retrieve lifecycle and transaction data

To reconcile card activity, build reporting, or power your UI with the three-level transaction model (lifecycles, card transactions, and transaction events), use the Issuing transaction APIs and optional webhooks. This guide shows you how to retrieve lifecycle data, card transactions, and transaction events, and how to receive real-time updates.

Before you begin

• Obtain your API credentials from the Airwallex web app.
• Have at least one active issued card with transaction activity.
• Understand the difference between lifecycles, card transactions, and transaction events so you can choose the right endpoint and filters.

Retrieve lifecycles

Use the lifecycles API when you need a network-level view of a payment and aggregated billing amounts for all related card transactions and events.

1. Call the GET /api/v1/issuing/lifecycles endpoint (see Card transaction lifecycles API in the API reference for your environment).

2. Add query parameters to narrow results (for example, card_id, from_created_date, to_created_date, page_num, page_size), according to the API specification.

3. Send the request:

   Shell

   1curl -G 'https://api-demo.airwallex.com/api/v1/issuing/lifecycles' \
   2  --data-urlencode 'card_id={{CARD_ID}}' \
   3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}'

4. Use the id (lifecycle ID) and billing_amounts from the response. To get all events for a lifecycle, use that lifecycle_id with the transaction events endpoint (see Retrieve transaction events).

A lifecycle response includes billing_amounts (totals for authorized, credited, debited, declined, expired, pending, and reversed amounts per currency), so you can use it for aggregation without summing events yourself.

Retrieve card transactions

Use the card transactions API when you need statuses with guaranteed terminal states (Authorized, Cleared, Reversed, Expired, Declined, Verified) and per-transaction details such as merchant, amounts, and fund direction.

1. Call the GET /api/v1/issuing/card_transactions endpoint (see Card transactions API in the API reference).

2. Add query parameters such as card_id, lifecycle_id, status, from_created_date, to_created_date, and pagination parameters, as supported by the API.

3. Send the request:

   Shell

   1curl -G 'https://api-demo.airwallex.com/api/v1/issuing/card_transactions' \
   2  --data-urlencode 'card_id={{CARD_ID}}' \
   3  --data-urlencode 'status=CLEARED' \
   4  -H 'Authorization: Bearer {{ACCESS_TOKEN}}'

4. Use the lifecycle_id on each card transaction to group related card transactions (for example, purchase and refund). If you need per-event detail or failure reasons for multiple events in one card transaction, call the transaction events endpoint with the card transaction ID.

Retrieve transaction events

Use the transaction events API when you need the most granular data: individual network messages or fund movements, including type, subtype, failure reason, and per-event amounts.

1. Call the GET /api/v1/issuing/transaction_events endpoint (see Card transaction events API in the API reference).

2. Filter by lifecycle_id, card_transaction_id, card_id, date range, and other supported parameters.

3. Send the request:

   Shell

   1curl -G 'https://api-demo.airwallex.com/api/v1/issuing/transaction_events' \
   2  --data-urlencode 'lifecycle_id={{LIFECYCLE_ID}}' \
   3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}'

4. Use the returned events to inspect type and subtype (for example, authorization, incremental authorization, clearing, reversal), process_result, failure_reason, and billing or transaction amounts per event.

Webhooks for real-time updates

To react to lifecycle and event changes without polling, subscribe to the transaction lifecycle webhooks in the Airwallex web app. These events are produced when a lifecycle is processed (LifecycleProcessedEvent). Full event names and descriptions are in Transaction lifecycle (beta) under Issuing webhooks. Summary:

Card transaction lifecycle

Card transaction status

These events are sent when the card transaction status changes to the corresponding status, except issuing.card_transaction.modified, which fires when other fields on the card transaction change but the status does not.

Card transaction events

1. In the Airwallex web app, open the Developer area and go to webhook configuration.

2. Subscribe to the events you need from the tables above.

3. Set your endpoint URL and save. When events occur, Airwallex sends payloads to your URL; use identifiers in the payload (for example, lifecycle or card transaction IDs) to fetch full details from the GET endpoints in this guide if needed.

Next steps

Now that you can retrieve lifecycle and transaction data:

• Retrieve card transactions (if you use the legacy transactions list API).
• Handle transaction disputes.
• Provide fraud feedback.
• Review Transaction lifecycle for status and fund-direction details.