Issuing

Subscribe to webhook events for card and transaction status changes.

The following webhook events are available for your Issuing integration.

Card status

Event	Description
issuing.card.pending	Card creation is pending and is under review.
issuing.card.failed	The request to create a card using Create a card failed.
issuing.card.active	The card is active and can be used for transactions.
issuing.card.inactive	The card is successfully frozen and cannot be used for transactions. However, it can be unfrozen and used again.
issuing.card.blocked	The card is in a suspended state as Airwallex has blocked the card.
issuing.card.lost	The card is marked as lost.
issuing.card.stolen	The card is reported as stolen.
issuing.card.closed	The card is cancelled. This is a terminal state.
issuing.card.expired	The card has expired.

Card delivery status

Event	Description
issuing.card.modified	For more information, refer to the delivery status descriptions and next steps.

Cardholder status

Event	Description
issuing.cardholder.incomplete	Cardholder needs to provide additional details and pass the review process.
issuing.cardholder.pending	Cardholder needs to pass the review process before accessing card details.
issuing.cardholder.ready	Cardholder has passed the review process and is ready to be issued cards.
issuing.cardholder.disabled	Cardholder has been disabled.
issuing.cardholder.deleted	Cardholder has been deleted from the account.

Reissuance

Event	Description
issuing.reissue.succeeded	Successful reissue of an existing card.

Transactions

Event	Description
issuing.transaction.succeeded	Successful transaction on an issued card.
issuing.transaction.failed	Failed transaction on an issued card.

Transaction lifecycle (beta)

These events are produced when a lifecycle is processed (LifecycleProcessedEvent). Use them with the transaction lifecycle APIs to stay in sync without polling.

Card transaction lifecycle

Event	Description
issuing.card_transaction_lifecycle.created	A new card transaction lifecycle has been created.
issuing.card_transaction_lifecycle.modified	An existing card transaction lifecycle has been modified.

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.

Event	Description
issuing.card_transaction.authorized	The card transaction is authorized.
issuing.card_transaction.verified	The card transaction is verified.
issuing.card_transaction.cleared	The card transaction status changed to cleared.
issuing.card_transaction.reversed	The card transaction status changed to reversed.
issuing.card_transaction.expired	The card transaction status changed to expired.
issuing.card_transaction.declined	The card transaction is declined.
issuing.card_transaction.modified	The card transaction was updated without a status change (other fields on the object changed).

Card transaction events

Event	Description
issuing.card_transaction_event.success	A transaction event was processed successfully.
issuing.card_transaction_event.failed	A transaction event was declined or failed processing.
issuing.card_transaction_event.enriched	Enriched data was added to a transaction event.

Card alerts

Event	Description
issuing.card.low_remaining_transaction_limit	The card's remaining spending limit has fallen below a specified threshold.

Disputes

Event	Description
issuing.transaction_dispute.created	The dispute draft is successfully created. It can be submitted to Airwallex once ready.
issuing.transaction_dispute.expired	There is no dispute rights as the validity period is over.
issuing.transaction_dispute.submitted	The dispute is successfully submitted to Airwallex.
issuing.transaction_dispute.rejected	The dispute is rejected by Airwallex. You may attempt to resubmit based on the feedback provided.
issuing.transaction_dispute.canceled	The dispute is successfully canceled.
issuing.transaction_dispute.accepted	The dispute is submitted to the card scheme.
issuing.transaction_dispute.won	The dispute is won.
issuing.transaction_dispute.lost	The dispute is lost.
issuing.transaction_dispute.modified	The dispute notes is updated and there may be actions to take.

Payload examples

Listed below are the webhook events relevant for Issuing:

issuing.transaction.succeeded
issuing.transaction.failed
issuing.reissue.succeeded

JSON

1{
2    "account_id": "acct_TOslkS7-MnyXlQuV8Lb4og",
3    "created_at": "2018-03-22T16:09:00+0000",
4    "data": object{...},
5    "id": "86b69f91-06f0-3fe8-8faf-4de58954ca8e",
6    "name": "issuing.transaction.succeeded",
7    "source_id": "6c2dc266-09ad-4235-b61a-767c7cd6d6ea",
8    "version": "2019-09-09",
9}

Examples of different issuing event data objects are displayed below.

Authorization and clearing

As described in the Transaction lifecycle docs, card transactions may come to you in two phases:

In the first phase, you would receive an issuing.transaction.succeeded authorization event (matching the AUTHORIZATION event type in the Get Transactions API) with the following payload:

JSON

1{
2  "acquiring_institution_id": "123456",
3  "auth_code": "ABC123",
4  "billing_amount": -100,
5  "billing_currency": "USD",
6  "card_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",
7  "card_nickname": "Recurring payments",
8  "client_data": null,
9  "digital_wallet_token_id": "9011d4ce-1b28-42f0-a608-1062e796b4f2",
10  "failure_reason": null,
11  "masked_card_number": "************4242",
12  "merchant": {
13    "category_code": "4829",
14    "city": "Melbourne",
15    "country": "AUS",
16    "identifier": "012345678910123",
17    "name": "Merchant A"
18  },
19  "network_transaction_id": "3951729271768745",
20  "posted_date": "2018-03-22T16:08:02.000+0000",
21  "retrieval_ref": "909916088001",
22  "status": "PENDING",
23  "transaction_amount": -100,
24  "transaction_currency": "USD",
25  "transaction_date": "2018-03-21T16:08:02.000+0000",
26  "transaction_id": "6c2dc266-09ad-4235-b61a-767c7cd6d6ea",
27  "transaction_type": "AUTHORIZATION"
28}

In the second phase, if your transaction authorization succeeded, you would receive an issuing.transaction.succeeded event (matching the CLEARING event type in the Get Transactions API) within 7 days with the following payload. You can match clearing events to their corresponding authorization events using the matched_authorizations field:

JSON

1{
2  "acquiring_institution_id": "123456",
3  "auth_code": "ABC123",
4  "billing_amount": -100,
5  "billing_currency": "USD",
6  "card_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",
7  "card_nickname": "Recurring payments",
8  "client_data": null,
9  "digital_wallet_token_id": "9011d4ce-1b28-42f0-a608-1062e796b4f2",
10  "failure_reason": null,
11  "masked_card_number": "************4242",
12  "matched_authorizations": ["6c2dc266-09ad-4235-b61a-767c7cd6d6ea"],
13  "merchant": {
14    "category_code": "4829",
15    "city": "Melbourne",
16    "country": "AUS",
17    "identifier": "012345678910123",
18    "name": "Merchant A"
19  },
20  "network_transaction_id": "3951729271768745",
21  "posted_date": "2018-03-22T16:08:03.000+0000",
22  "retrieval_ref": "909916088001",
23  "status": "APPROVED",
24  "transaction_amount": -100,
25  "transaction_currency": "USD",
26  "transaction_date": "2018-03-21T16:08:03.000+0000",
27  "transaction_id": "7d34dae3-acb8-4bd0-95b5-a1ceb76749ca",
28  "transaction_type": "CLEARING"
29}

If your transaction authorization failed, you would receive an issuing.transaction.failed event with the following payload:

JSON

1{
2  "acquiring_institution_id": "123456",
3  "auth_code": "ABC123",
4  "billing_amount": -100,
5  "billing_currency": "HKD",
6  "card_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",
7  "card_nickname": "Recurring payments",
8  "client_data": null,
9  "digital_wallet_token_id": "9011d4ce-1b28-42f0-a608-1062e796b4f2",
10  "failure_reason": "CURRENCY_NOT_ALLOWED",
11  "masked_card_number": "************4242",
12  "merchant": {
13    "category_code": "4829",
14    "city": "Melbourne",
15    "country": "AUS",
16    "identifier": "012345678910123",
17    "name": "Merchant A"
18  },
19  "network_transaction_id": "3951729271768745",
20  "posted_date": "2018-03-22T16:08:02.000+0000",
21  "retrieval_ref": "464665204556",
22  "status": "FAILED",
23  "transaction_amount": -100,
24  "transaction_currency": "HKD",
25  "transaction_date": "2018-03-22T16:08:02.000+0000",
26  "transaction_id": "ec051b12-b642-4aec-828a-2a66657f6ebc",
27  "transaction_type": "AUTHORIZATION"
28}

If your transaction authorization was reversed or has not been cleared before the authorization expires, you would receive an issuing.transaction.succeeded event (matching the REVERSAL event type in the Get Transactions API) with the following payload. The matched_authorizations field indicates the original authorization that was reversed:

JSON

1{
2  "acquiring_institution_id": "123456",
3  "auth_code": "ABC123",
4  "billing_amount": 0,
5  "billing_currency": "USD",
6  "card_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",
7  "card_nickname": "Recurring payments",
8  "client_data": null,
9  "digital_wallet_token_id": "9011d4ce-1b28-42f0-a608-1062e796b4f2",
10  "failure_reason": null,
11  "masked_card_number": "************4242",
12  "matched_authorizations": ["6c2dc266-09ad-4235-b61a-767c7cd6d6ea"],
13  "merchant": {
14    "category_code": "4829",
15    "city": "Melbourne",
16    "country": "AUS",
17    "identifier": "012345678910123",
18    "name": "Merchant A"
19  },
20  "network_transaction_id": "6703470125714180",
21  "posted_date": "2018-03-22T16:08:04.000+0000",
22  "retrieval_ref": "684116989665",
23  "status": "CLEARED",
24  "transaction_amount": 100,
25  "transaction_currency": "USD",
26  "transaction_date": "2018-03-22T16:08:04.000+0000",
27  "transaction_id": "122ec0b1-fd6f-4a3f-a2f8-b2b75d202e28",
28  "transaction_type": "REVERSAL"
29}

Single message transactions

Card transactions may come to you in one single message where the authorization and clearing requests are effectively combined into one final message. In this case, you would only receive one issuing.transaction.succeeded event (matching the CLEARING event type in the Get Transactions API) with the following payload:

JSON

1{
2  "acquiring_institution_id": "123456",
3  "auth_code": "ABC123",
4  "billing_amount": -100,
5  "billing_currency": "USD",
6  "card_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",
7  "card_nickname": "Recurring payments",
8  "client_data": null,
9  "digital_wallet_token_id": "9011d4ce-1b28-42f0-a608-1062e796b4f2",
10  "failure_reason": null,
11  "masked_card_number": "************4242",
12  "merchant": {
13    "category_code": "4829",
14    "city": "Melbourne",
15    "country": "AUS",
16    "identifier": "012345678910123",
17    "name": "Merchant A"
18  },
19  "network_transaction_id": "3951729271768745",
20  "posted_date": "2018-03-22T16:08:03.000+0000",
21  "retrieval_ref": "909912081021",
22  "status": "APPROVED",
23  "transaction_amount": -100,
24  "transaction_currency": "USD",
25  "transaction_date": "2018-03-21T16:08:03.000+0000",
26  "transaction_id": "7d34dae3-acb8-4bd0-95b5-a1ceb76749ca",
27  "transaction_type": "CLEARING"
28}

Refunds

In the event of a refund (of a previously cleared transaction), you would receive an issuing.transaction.succeeded event (matching the REFUND event type in the Get Transactions API) with the following payload:

JSON

1{
2  "acquiring_institution_id": "123456",
3  "auth_code": "ABC123",
4  "billing_amount": 100,
5  "billing_currency": "USD",
6  "card_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",
7  "card_nickname": "Recurring payments",
8  "client_data": null,
9  "digital_wallet_token_id": "9011d4ce-1b28-42f0-a608-1062e796b4f2",
10  "failure_reason": null,
11  "masked_card_number": "************4242",
12  "merchant": {
13    "category_code": "4829",
14    "city": "Melbourne",
15    "country": "AUS",
16    "identifier": "012345678910123",
17    "name": "Merchant A"
18  },
19  "network_transaction_id": "0456637287832818",
20  "posted_date": "2018-03-22T16:08:05.000+0000",
21  "retrieval_ref": "157467270162",
22  "status": "APPROVED",
23  "transaction_amount": 100,
24  "transaction_currency": "USD",
25  "transaction_date": "2018-03-22T16:08:05.000+0000",
26  "transaction_id": "0212443b-74cd-4c55-92cd-6823c2e47600",
27  "transaction_type": "REFUND"
28}

Reissue of cards

In the event Airwallex renews an issued card you would receive an issuing.reissue.succeeded event with the following payload. The card ID will remain the same while other details such as the expiry date and CVV will be updated.

JSON

1{
2   "account_business_name": "Account Business Name",
3   "account_id": "00307c40-f999-4b1c-846c-541f2fa3f757",
4   "card_id": "f88b5dc6-e277-4392-beff-53e797651610",
5   "cardholder_first_name": "John Smith",
6   "new_masked_card_number": "************4242",
7   "old_masked_card_number": "************4242",
8   "reissue_reason": "CARD_RENEWAL"
9}

Was this page helpful?