Skip to main content

Migration from CardId to CardToken

On this page, you can get some guidance to migrate to the debiX API cardtoken/v2 variant.

Reason​

SIX has introduced the CardToken as a full equivalent of the ShortCardId. While the ShortCardId contains the card number, the CardToken is a pure technical id referencing a card.

Solution​

The known debiX API Version V2 has been mirrored to a new cardtoken/v2 variant. This new variant offers the same functionalities and endpoints as the known V2 variant but uses consequently CardToken instead of CardId or ShortCardId. For the moment, only the card order endpoint POST /cards still requires a CardId.

The debiX API V2 is now available in two variants, which differ in how the card is referenced:

  • v2 uses the CardId (deprecated)
  • cardtoken/v2 uses the CardToken (recommended)

Both variants offer an endpoint to fetch the CardToken for a ShortCardId: POST /cards/cardToken.

Migration steps​

We recommend the following steps for issuers that want to migrate to the card number free API debiX API cardtoken/v2.

Starting point - current situation​

  • The issuer uses the debiX API v2 variant, that references cards via CardId and
  • orders cards via Worldline DEBOL XML or debiX API v2.

Migration​

  1. Initial load: Fetch the CardToken for each existing card
  • via POST /cards/cardToken on the debiX API v2 variant or
  • from OTIS or the KTB file in the current version.
  1. Store the fetched CardToken with the card data on the issuer's side.
  2. When the CardToken has been fetched for all cards: the issuer is ready to switch to the debiX API cardToken/v2 variant and can start calling the debiX API with the endpoints containing CardToken – instead of the old ones containing CardId or ShortCardId.
  3. The issuer uses the debiX API cardToken/v2 variant and references cards via CardToken.

Target solution​

  • The issuer orders a card via debiX API cardToken/v2.
  • On card creation, the cardToken is delivered to the issuer via debiX PUSH.
  • The CardToken is stored with the card data on the issuer's side.