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. |
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. |
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. |