Issuing Card Management SDKs migration guide

Checkout.com has upgraded the following Issuing SDKs:

• Card Management Android SDK

• Card Management iOS SDK

You need to migrate using the following guidance:

 Android SDK

SDK functions

From SDK version 3.0.0, all callback methods are deprecated. Update your integration to use suspending methods instead.

Update getCards()

The getCards() method is used to:

• Activate a card in your app.

• Display card details in your app.

Migrate from:

cardManager.getCards(statuses = setOf(CardState.ACTIVE, CardState.REVOKED)) { result: Result<List<Card>> ->
  result.onSuccess {
    // You receive a list of cards that you can display in your UI
    // Returned card details include last four digits of the PAN, expiry date, cardholder name, card state, and card ID
  }.onFailure {
    // If something goes wrong, you receive an error with more information
  }
}
// Get a specific card
cardManager.getCard(cardId: "<card id>") { result: Result<List<Card>> ->
  result.onSuccess {
    // You receive a list of cards that you can display in your UI
    // Returned card details include last four digits of the PAN, expiry date, cardholder name, card state, and card ID
  }.onFailure {
    // If something goes wrong, you receive an error with more information
  }
}

Migrate to:

// Call coroutineBased getCards in the context of a coroutineScope
try {
  // Retrieve all the cardholder's cards
  cardManager.getCards(statuses = setOf(CardState.ACTIVE, CardState.REVOKED))
  
  // Retrieve a specific card
  cardManager.getCard(cardId: "<cardid>")
} catch (e: CardManagementError) {
   when (error) {
        is CardManagementError.Unauthenticated -> // Prompt login
        is CardManagementError.ConnectionIssue -> // Show network error
        else -> // Handle other errors
    }
}

Update Card.possibleStateChanges()

The Card.possibleStateChanges() method is used to activate a card in your app.

Migrate from:

// Returns a list of possible statuses you can change the card to
val possibleNewStates = card.possibleStateChanges

// You can activate the card if the status was returned by possibleStateChanges
if (possibleNewStates.contains(CardState.ACTIVE)) {
  card.activate(completionHandler) 
}

Migrate to:

// Returns a list of possible statuses you can change the card to
val possibleNewStates = card.possibleStateChanges

// You can activate the card if the status was returned by possibleStateChanges
if (possibleNewStates.contains(CardState.ACTIVE)) {
  <coroutineScope> {
    val result = card.activate()
    handleCardStateTransition(result)
  }
}

Update sensitive card details methods

Update the following sensitive card details methods used to display card details in your app:

• Card.getPin() – The personal identification number (PIN) for a physical card

• Card.getPan() – The full PAN

• Card.getSecurityCode() – The security code (CVC2)

• Card.getPANAndSecurityCode() – The full PAN and CVC2

Migrate from:

val singleUseToken = "{Single_use_token_retrieved_after_SCA}"

// Request sensitive data via the card object
card.getPin(singleUseToken) { result: Result<AbstractComposeView> ->
  result
    .onSuccess {
      // If successful, you receive a Compose view containing the sensitive details that you can display to the user
    }.onFailure {
      // If something goes wrong, you receive an error with more information
    }
}

Migrate to:

val singleUseToken = "{Single_use_token_retrieved_after_SCA}"

// Request sensitive data via the card object
when (val result = card.getPin(singleUseToken)) {
    is CardSecureDataResult.Success -> {
      displaySecureView(result.data)
    }
    is CardSecureDataResult.Error -> {
      showError(result.message)
      handleError(result)
    }
}

Update copyPan

The copyPan method is used to copy the card number to clipboard.

Migrate from:

public suspend fun copyPan(singleUseToken: String): Result<Unit>

public fun copyPan(
  singleUseToken: {Single_use_token_retrieved_after_SCA},
  completionHandler: (Result<Unit>) -> Unit
}

Migrate to:

public suspend fun copyPan(singleUseToken: String): Result<Unit>

Update checkoutCardManager.configurePushProvisioning()

The checkoutCardManager.configurePushProvisioning() method is used to configure push provisioning.

Migrate from:

checkoutCardManager.configurePushProvisioning(
    activity = "{Activity_to_handle_the_provision_outcome}",
    cardholderId = "{ID_of_cardholder_performing_operation}",
    configuration = ProvisioningConfiguration(/* */),
    completionHandler = { result: Result<Unit> -> /* Callback after the operation has completed*/ })

MIgrate to:

<coroutineScope> {
    val config = ProvisioningConfiguration(...)
    val result = cardManager.configurePushProvisioning(
        activity = "{Activity_to_handle_the_provision_outcome}",
        cardholderId = "{ID_of_cardholder_performing_operation}",
        configuration = config
    )
    result.onSuccess { /* Configuration complete */ }
          .onFailure { error -> /* Handle error */ }
}

Update card.getDigitizationState()

The card.getDigitizationState() method is used to verify the digitization status of the cardholder's cards. Migrate from:

                          completionHandler:  “Completion Handler returning the outcome digitization status ((CheckoutCardManager.CardDigitizationResult) -> Void)”)

  Migrate to:

  when (val result = card.getDigitizationState(token)) {
      is CardOperationResult.Success -> {
          when (result.data) {
              DigitizationState.DIGITIZED -> showDigitized()
              DigitizationState.NOT_DIGITIZED -> showAddToWallet()
          }
      }
      is CardOperationResult.Error -> showError(result.message)
  }
}

Update card.provision()

The card.provision() method is used to provision cards. 

Migrate from:

card.provision(
    activity = "{Activity_to_handle_the_provision_outcome}",
    token = "{JWT_generated_for_operation}",
    completionHandler = { result: Result<Unit> -> /* Callback after the operation has completed*/ })

Migrate to:

<coroutineScope> {
 when (val result = card.provision(activity, token)) {
      is CardOperationResult.Success -> {
          showSuccess("Card added to wallet")
      }
      is CardOperationResult.Error -> showError(result.message)
  }
}

 iOS SDK

SDK functions

From SDK version 4.0.0, all callback methods are deprecated. Update your integration to use async methods instead. All async methods throw a CardManagementError that you need to handle.

Update getCards()

The getCards() method is used for the following use cases:

• Activate a card in your app.

• Display card details in your app.

Migrate from:

cardManager.getCards(statuses: [.active,.suspended]) { result in
  switch result {
  case .success(let cards):
    // You receive a list of cards that you can display in your UI
    // Returned card details include last four digits of the PAN, expiry date, cardholder name, card state, and card ID
  case .failure(let error):
    // If something goes wrong, you receive an error with more information
  }
}

// Get a specific card
cardManager.getCard(withID: cardId, statuses: [.active,.suspended]) { result in
  switch result {
  case .success(let cards):
    // You receive a list of cards that you can display in your UI
    // Returned card details include last four digits of the PAN, expiry date, cardholder name, card state, and card ID
  case .failure(let error):
    // If something goes wrong, you receive an error with more information
  }
}

Migrate to:

do {
   // Get all the cardholder's cards
   let cards = try await cardManager.getCards(statuses: [.active, .suspended])
   
   // Get a specific card
   let cards = try await cardManager.getCard(withID: cardId, statuses: [.active,.suspended])
} catch let error as CardManagementError {
  switch error {
    case .authenticationFailure:
      // Handle the authentication error
    default: 
      // Handle other errors
  }
}

Update Card.possibleStateChanges()

The Card.possibleStateChanges() method is used for the following use cases:

• Activate a card in your app.

Migrate from:

import CheckoutCardManagement

class YourObject {

  // Returns a list of possible statuses you can change the card to
let possibleNewStates = card.possibleStateChanges

// You can activate the card if the status was returned by possibleStateChanges
if possibleNewStates.contains(.active) {
    card.activate(completionHandler: cardStateChangeCompletion)
  }
}

Migrate to:

import CheckoutCardManagement

class YourObject {

  // Returns a list of possible statuses you can change the card to
let possibleNewStates = card.possibleStateChanges

// You can activate the card if the status was returned by possibleStateChanges
if possibleNewStates.contains(.active) {
    do {
       try await cardManager.activate()
    } catch let error as CardManagementError {
      // activation failed - handle error accordingly
    }
  }
}

Update sensitive card details methods

Update the following sensitive card details methods:

• Card.getPin() – The personal identification number (PIN) for a physical card

• Card.getPan() – The full PAN

• Card.getSecurityCode() – The security code (CVC2)

• Card.getPANAndSecurityCode() – The full PAN and CVC2

These are used to display card details in your app.

Migrate from:

let singleUseToken = "{Single_use_token_retrieved_from_your_backend_after_SCA}"

// Request sensitive details using the card object
card.getPin(singleUseToken: singleUseToken) { result in
    switch result {
    case .success(let pinView):
        // If successful, you receive a UI component that you can display to the cardholder
    case .failure(let error):
        // If something goes wrong, you receive an error with more information
    }
}

Migrate to:

let singleUseToken = "{Single_use_token_retrieved_from_your_backend_after_SCA}"

// Request sensitive details using the card object
do {
   let pin = try await card.getPin(reason: reason)
   // Handle the PIN view here - This is a UI component that you can display to the user
} catch let error as CardManagementError {
  // Request failed - Handle the error
}

Update copyPan

The copyPan method is used to copy the card number to clipboard.

Migrate from:

func copyPan(singleUseToken: {Single_use_token_retrieved_after_SCA},
             completionHandler: @escaping ((CheckoutCardManager.CardDetailCopyResult) -> Void))

Migrate to:

func copyPan(singleUseToken: String) async throws

Update checkoutCardManager.configurePushProvisioning()

The checkoutCardManager.configurePushProvisioning() method is used to configure push provisioning.

Migrate from:

cardManager.configurePushProvisioning(cardholderID: "{Id_of_cardholder_performing_operation}",
                                      appGroupId: "{Your_Apple_App_Group_Id}",
                                      configuration: ProvisioningConfiguration(/* */),
                                      walletCards: "List of cards and UI images for the Apple Wallet app to use [(Card, UIImage)]",
                                      completionHandler: "Completion handler that returns the configuration operation result ((CheckoutCardManager.OperationResult) -> Void)")

MIgrate to:

do {
    try await cardManager.configurePushProvisioning(cardholderID: "{ID_of_cardholder_performing_operation}",
                                                    appGroupId: "{ID_of_project_group_containing_app_and_extensions}",
                                                    configuration: configuration,
                                                    walletCards: walletCardsList)
} catch let error as CardManagementError {
   // Handle the error 
}

Update card.getDigitizationState()

The card.getDigitizationState() method is used to verify the digitization status of the cardholder's cards. Migrate from:

                          completionHandler: "Completion handler that returns the digitization result ((CheckoutCardManager.CardDigitizationResult) -> Void)")

  Migrate to:

    let cardDigitizationData = try await card.getDigitizationState(provisioningToken: {JWT_generated_for_operation})
    // Handle the card digitization result data
} catch let error as CardManagementError {
    // Handle the error
}

Update card.provision()

The card.provision() method is used to provision cards. 

Migrate from:

card.provision(provisioningToken: "{JWT_generated_for_operation}"),
               completionHandler: "Completion handler that returns the provisioning operation result ((CheckoutCardManager.OperationResult) -> Void)")

Migrate to:

do {
    try await card.provision(provisioningToken: {JWT_generated_for_operation})
    // Handle the provisioning attempt
} catch let error as CardManagementError {
    // Handle the error
}