Developer Tools

Issuing

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 Purchase 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?

On this page

Was this page helpful?