Upgrade your issuing integration

Refer to this guide if your integration uses Issuing API versions released prior to `2024-03-31`.

The card and cardholder objects have changed in the API version 2024-03-31. See the API changelog API and for information on the new card programs, see supported card programs.

This guide covers the changes made and instructions for upgrading to this latest version. Use this table to determine the upgrade path for your legacy integration (API version < 2024-03-31).

Legacy integration	Upgrade path	Why you should upgrade
Cardholders	Individual type cardholders	Allows you to create different cardholder types (Individual and Delegate) to suit your business needs.
Individual cards	Personalized commercial cards	Allows you to support Individual cards in your commercial card program. Offers support to update Delegate cardholders to Individual type.
Business/Organization cards	Non-personalized commercial cards	Allows you to add multiple cardholders (Individual or Delegate) to commercial cards. This means you can have up to three registered contacts for 3D Secure authentication.

API versions 2024-03-31 and later support consumer card issuing for customers onboarded as an Individual (not a Business) onto a platform. See create consumer cards.

If you are integrating with Issuing APIs for the first time, see create cardholders and create cards tutorials for instructions on integrating with the latest version.

Cardholders > Individual cardholders

If you have an existing integration for issuing individual cards (see legacy individual cards tutorial), you need to upgrade your integration to create INDIVIDUAL type cardholders as the new cardholder object supports INDIVIDUAL and DELEGATE cardholder types.

Field/Object	API Version < `2024-03-31`	API Version >= `2024-03-31`
`address` object	Available as top-level field	Moved into `individual` object (`individual.address`)
`type` field	N/A	Set to `INDIVIDUAL`
`employers` object	N/A	Optional information about the individual's employers.

Example Request with differences

Shell
1curl --request POST \
2--url 'https://api-demo.airwallex.com/api/v1/issuing/cardholders/create'
3--header 'Authorization: Bearer <your_bearer_token>'
4--data '{
5-  "address": {
6- "city": "Melbourne",
7- "country": "AU",
8- "line1": "44 Gillespie St",
9- "line2": "Unit 2",
10- "postcode": "3121",
11- "state": "VIC"
12-  },
13   "email": "[email protected]",
14   "individual": {
15+ "address": {
16+   "city": "Melbourne",
17+   "country": "AU",
18+   "line1": "44 Gillespie St",
19+   "line2": "Unit 2",
20+   "postcode": "3121",
21+   "state": "VIC"
22+ },
23  "cardholder_agreement_terms_consent_obtained": "yes",
24  "date_of_birth": "1982-11-02",
25+ "employers": [
26+   {
27+     "business_identifiers": [
28+       {
29+         "country_code": "US",
30+         "number": "A1098762872",
31+         "type": "BRN"
32+       }
33+     ],
34+     "business_name": "string"
35+   }
36+ ],
37  "express_consent_obtained": "yes",
38  "identification": {
39    "country": "AU",
40    "document_back_file_id": "NzI3ZDAxM2ItZjMzMC00ZDIyLTk4YTQtMTE3ZTA0MjdhZTUyLHwsaG9uZ2tvbmcsfCxwYXNzcG9ydC5qcGdfMTYwNzY0MDI4OQ==",
41    "document_front_file_id": "NzI3ZDAxM2ItZjMzMC00ZDIyLTk4YTQtMTE3ZTA0MjdhZTUyLHwsaG9uZ2tvbmcsfCxwYXNzcG9ydC5qcGdfMTYwNzY0MDI4OQ==",
42    "expiry_date": "2028-08-28",
43    "gender": "F",
44    "number": "001238243",
45    "state": "NT",
46    "type": "DRIVERS_LICENSE"
47  },
48  "name": {
49    "first_name": "John",
50    "last_name": "Smith",
51    "middle_name": "Fitzgerald",
52    "title": "Mr"
53  },
54  "nationality": "UK",
55  "paperless_notification_consent_obtained": "yes",
56  "privacy_policy_terms_consent_obtained": "yes"
57   },
58   "mobile_number": "61432100100",
59   "postal_address": {
60  "city": "Melbourne",
61  "country": "AU",
62  "line1": "44 Gillespie St",
63  "line2": "Unit 2",
64  "postcode": "3121",
65  "state": "VIC"
66-  }
67+  },
68+  "type": "INDIVIDUAL"
69 }

Example Response with differences

JSON
1{
2-  "address": {
3- "city": "Melbourne",
4- "country": "AU",
5- "line1": "44 Gillespie St",
6- "line2": "Unit 2",
7- "postcode": "3121",
8- "state": "VIC"
9-  },
10   "cardholder_id": "dbe188bb-71ad-4e3e-b932-9f4a0ff2f3e7",
11   "email": "[email protected]",
12   "individual": {
13+ "address": {
14+   "city": "Melbourne",
15+   "country": "AU",
16+   "line1": "44 Gillespie St",
17+   "line2": "Unit 2",
18+   "postcode": "3121",
19+   "state": "VIC"
20+ },
21  "date_of_birth": "1982-11-02",
22+ "employers": [
23+   {
24+     "business_identifiers": [
25+       {
26+         "country_code": "US",
27+         "number": "A1098762872",
28+         "type": "BRN"
29+       }
30+     ],
31+     "business_name": "string"
32+   }
33+ ],
34  "name": {
35    "first_name": "John",
36    "last_name": "Smith",
37    "middle_name": "Fitzgerald",
38    "title": "Mr"
39  }
40   },
41   "mobile_number": "61-9922334321",
42   "postal_address": {
43  "city": "Melbourne",
44  "country": "AU",
45  "line1": "44 Gillespie St",
46  "line2": "Unit 2",
47  "postcode": "3121",
48  "state": "VIC"
49   },
50-  "status": "PENDING"
51+  "status": "PENDING",
52+  "type": "INDIVIDUAL"
53 }

Individual cards > Personalized commercial cards

If you have an existing integration for issuing individual cards (see legacy individual cards tutorial), you need to upgrade your integration to first create INDIVIDUAL type cardholders (see Individual cardholder requirements), and then link that cardholder to a personalized commercial card.

Field/Object	API Version < `2024-03-31`	API Version >= `2024-03-31`
`issue_to` field	Set to `INDIVIDUAL`.	N/A
`program.purpose` field	N/A	Set to `COMMERCIAL`.
`cardholder_id` field	The ID of the cardholder.	Set this to the ID of the `INDIVIDUAL` cardholder.
`is_personalized` field	N/A	Set this to `true` to issue a personalized commercial card.

Example Request with differences

Shell
1curl --request POST \
2--url 'https://api-demo.airwallex.com/api/v1/issuing/cards/create'
3--header 'Authorization: Bearer <your_bearer_token>'
4--data '{
5   "authorization_controls": {
6  "active_from": "2018-10-31T00:00:00+0800",
7  "active_to": "2018-10-31T00:00:00+0800",
8  "allowed_currencies": [
9    "USD",
10    "AUD"
11  ],
12  "allowed_merchant_categories": [
13    "7531",
14    "7534"
15  ],
16  "allowed_transaction_count": "SINGLE",
17  "transaction_limits": {
18    "currency": "USD",
19    "limits": [
20      {
21        "amount": 1000,
22        "interval": "PER_TRANSACTION"
23      }
24    ]
25  }
26   },
27   "brand": "VISA",
28   "cardholder_id": "dbe188bb-71ad-4e3e-b932-9f4a0ff2f3e7",
29   "created_by": "John Smith",
30   "form_factor": "VIRTUAL",
31+  "is_personalized": true,
32   "nick_name": "travelling",
33   "note": "This is my first card.",
34-  "issue_to": "INDIVIDUAL",
35+  "program": {
36+ "purpose": "COMMERCIAL",
37+ "type": "CREDIT",
38+ "sub_type": "GOOD_FUNDS_CREDIT"
39+  },
40   "request_id": "request-id-sample-1"
41 }'

Example Response with differences

JSON
1{
2  "authorization_controls": {
3      "active_from": "2018-10-30T16:00:00.000+00:00",
4      "active_to": "2018-10-30T16:00:00.000+00:00",
5      "allowed_currencies": [
6          "USD",
7          "AUD"
8      ],
9      "allowed_merchant_categories": [
10          "7531",
11          "7534"
12      ],
13      "allowed_transaction_count": "SINGLE",
14      "transaction_limits": {
15          "currency": "USD",
16          "limits": [
17              {
18                  "amount": 1000.0,
19                  "interval": "PER_TRANSACTION"
20              }
21          ]
22      }
23  },
24  "brand": "VISA",
25  "card_id": "f3fbcdbc-8959-4ad8-8d28-5afdb314879e",
26  "card_status": "PENDING",
27  "cardholder_id": "dbe188bb-71ad-4e3e-b932-9f4a0ff2f3e7",
28  "created_at": "2024-04-18T03:35:46.474+0000",
29  "created_by": "John Smith",
30  "form_factor": "VIRTUAL",
31- "issue_to": "INDIVIDUAL",
32  "name_on_card": "John Smith",
33  "nick_name": "travelling",
34  "note": "This is my first card.",
35  "request_id": "request-id-sample-1",
36- "type": "GOOD_FUNDS_CREDIT",
37  "updated_at": "2024-04-18T03:35:46.474+0000"
38 }

Business cards > Non-personalized commercial cards

If you have an existing integration for issuing business cards (see legacy business cards tutorial, you need to upgrade your integration to first create a DELEGATE cardholder (see Delegate cardholder requirements), and then link that cardholder to a non-personalized commercial card.

Field/Object	API Version < `2024-03-31`	API Version >= `2024-03-31`
`issue_to` field	Set to `ORGANISATION`.	N/A
`program.purpose` field	N/A	Set to `COMMERCIAL`.
`cardholder_id` field	Not required for business cards.	Set this to the ID of the `DELEGATE` cardholder.
`additional_cardholder_ids` field	N/A	Optional. You can add up to two cardholders.
`is_personalized` field	N/A	Set this to `false` to issue a non-personalized commercial card.

Example Request with differences

Shell
1curl --request POST \
2--url 'https://api-demo.airwallex.com/api/v1/issuing/cards/create'
3--header 'Authorization: Bearer <your_bearer_token>'
4--data '{
5+  "additional_cardholder_ids": [
6+ "794edb10-f706-4211-9f0f-1f8b6d903cc9",
7+ "501c0c19-8cad-4787-948e-b2945396a79f"
8+  ],
9   "authorization_controls": {
10  "active_from": "2018-10-31T00:00:00+0800",
11  "active_to": "2018-10-31T00:00:00+0800",
12  "allowed_currencies": [
13    "USD",
14    "AUD"
15  ],
16  "allowed_merchant_categories": [
17    "7531",
18    "7534"
19  ],
20  "allowed_transaction_count": "SINGLE",
21  "transaction_limits": {
22    "currency": "USD",
23    "limits": [
24      {
25        "amount": 1000,
26        "interval": "PER_TRANSACTION"
27      }
28    ]
29  }
30   },
31+  "brand": "VISA",
32+  "cardholder_id": "dbe188bb-71ad-4e3e-b932-9f4a0ff2f3e7",
33   "created_by": "John Smith",
34   "form_factor": "VIRTUAL",
35-  "issue_to": "ORGANISATION",
36+  "is_personalized": false,
37   "nick_name": "travelling",
38   "note": "This is my first card.",
39-  "primary_contact_details": {
40- "email": "[email protected]",
41- "full_name": "John Smith",
42- "mobile_number": "619922334321"
43+  "program": {
44+ "purpose": "COMMERCIAL",
45+ "type": "CREDIT",
46+ "sub_type": "GOOD_FUNDS_CREDIT"
47   },
48   "purpose": "BUSINESS_EXPENSES",
49-  "request_id": "request-id-sample-1",
50-  "type": "GOOD_FUNDS_CREDIT"
51+  "request_id": "request-id-sample-1"
52 }'

Example Response with differences

JSON
1{
2  "authorization_controls": {
3      "active_from": "2018-10-30T16:00:00.000+00:00",
4      "active_to": "2018-10-30T16:00:00.000+00:00",
5      "allowed_currencies": [
6          "USD",
7          "AUD"
8      ],
9      "allowed_merchant_categories": [
10          "7531",
11          "7534"
12      ],
13      "allowed_transaction_count": "SINGLE",
14      "transaction_limits": {
15          "currency": "USD",
16          "limits": [
17              {
18                  "amount": 1000.0,
19                  "interval": "PER_TRANSACTION"
20              }
21          ]
22      }
23  },
24  "brand": "VISA",
25  "card_id": "1510d505-82dc-477f-b726-3e545aa84731",
26  "card_status": "PENDING",
27+ "cardholder_id": "dbe188bb-71ad-4e3e-b932-9f4a0ff2f3e7",
28  "created_at": "2024-04-18T02:47:07.652+0000",
29  "created_by": "John Smith",
30  "form_factor": "VIRTUAL",
31- "issue_to": "ORGANISATION",
32  "name_on_card": "John Smith",
33  "nick_name": "travelling",
34  "note": "This is my first card.",
35- "primary_contact_details": {
36-     "email": "[email protected]",
37-     "full_name": "John Smith",
38-     "mobile_number": "61-9922334321"
39- },
40  "purpose": "BUSINESS_EXPENSES",
41  "request_id": "request-id-sample-1",
42- "type": "GOOD_FUNDS_CREDIT",
43  "updated_at": "2024-04-18T02:47:07.652+0000"
44 }

Was this page helpful?