View and control digital cards

Tokenization service is required to use Thales D1 SDK for "View&Control" capabilities.

Use this guide to let the End User view and manage digital cards (tokens) created for their cards in xPay Wallets and other token requestors.

In the issuer application, you typically:

• display all digital cards linked to a specific cardId
• show each digital card status (for example, active or suspended)
• support basic life cycle actions such as suspend, resume, delete, and activate

Prerequisites

Make sure that:

• The End User and card are registered in the D1 backend.
• The D1 SDK is integrated into your issuer application and initialized.
• The issuer application has completed the D1 SDK login flow.

For the end-to-end wallet Tokenization flow, see Implement push to digital wallets.

View digital cards

To display existing digital cards for a specific cardId, call getDigitalCardList().

The response contains a list of DigitalCard objects. For Visa Cloud Token Framework (CTF), the DigitalCard object also includes device binding information, which allows the application to view all device bindings associated with each digital card.

The DigitalCard contains the following information:

• Digital card state (for example, active, suspended, or pending activation).
• Digital card expiry date.
• Last four digits of the digital card.
• Device name and type that contain the digital card.
• Token requestor ID (tokenRequestorID).
• Whether the digital card is on the current device (isOnCurrentDevice) for the selected wallet or token requestor (for example, Apple Pay, Google Pay, Samsung Pay, or NFC Wallet).
• Device binding list (since SDK 4.3.0 for Visa CTF). Contains the binding reference, device name, and binding status (APPROVED, DECLINED, or CHALLENGED) for each bound device.

Due to payment network limitations, you cannot always retrieve the token requestor name and logo in real time.

As a best practice, identify the top 5–10 token requestor IDs relevant to your portfolio and hard-code an End User–facing display name and logo in the issuer application.

Flow

High-level flow for listing digital cards for a card.

Sequence diagram

Pre-requisites

• Consumer account and card were registered in D1
• SDK is properly initialized
• Issuer App called D1 SDK login API

Example issuer application UI for listing digital cards.

Examples

Android

fun getDigitalCardList(d1Task: D1Task, cardID: String) {
    val callback: D1Task.Callback<List<DigitalCard>> = object : D1Task.Callback<List<DigitalCard>> {

        override fun onSuccess(digitalCardList: List<DigitalCard>) {
            // Handles the digitalCardList object from server.
            // For example, to display it on the UI as sample image above.
            for (digitalCard in digitalCardList) {
                val digitalCardID = digitalCard.cardID
                val digitalCardState = digitalCard.state // State of current Digital Card.
                val digitalCardExp = digitalCard.expiryDate // Expiry date of current Digital Card.
                val last4 = digitalCard.last4 // Last 4 digits of current Digital Card.
                val tokenRequestorID = digitalCard.tokenRequestorID // Token Requestor ID.
                val isOnCurrentDevice = digitalCard.isOnCurrentDevice //Identifies if the digital card is on the current device.

                // Retrieves device binding list (since SDK 4.3.0 for Visa CTF).
                val deviceBindingList = digitalCard.deviceBindingList
                deviceBindingList?.forEach { binding ->
                    val bindingReference = binding.bindingReference // Binding reference ID.
                    val deviceName = binding.deviceName // Device name.
                    val bindingStatus = binding.bindingStatus // APPROVED, DECLINED, or CHALLENGED.
                }
            }
        }

        override fun onError(exception: D1Exception) {
            // Refer to D1 SDK Integration – Error Management section.
        }
    }
    d1Task.getDigitalCardList(cardID, callback)
}

iOS >= 4.5.0

let cardID = "" // obtained e.g. from server
do {
    let service = try d1Task.digitalCardService()
    let digitalCards = try await service.digitalCardList(cardID)
    // Proceed with subsequent flows e.g. update UI
    for digitalCard in digitalCards {
        print("Digital cardID: \(digitalCard.cardID)")
        print("State: \(digitalCard.state.rawValue)")
        print("Last4: \(digitalCard.last4 ?? "")")
        print("Expiry: \(digitalCard.expiryDate ?? "")")
        print("DeviceID: \(digitalCard.deviceID ?? "")")
        print("Device name: \(digitalCard.deviceName ?? "")")
        print("Device type: \(digitalCard.deviceType ?? "")")
        print("Token Requestor ID: \(digitalCard.tokenRequestorID ?? "")")
        print("Token Requestor name: \(digitalCard.tokenRequestorName ?? "")")
        print("isOnCurrentDevice: \(digitalCard.isOnCurrentDevice)")
        
        // Access device binding list (since SDK 4.3.0)
        if let deviceBindingList = digitalCard.deviceBindingList {
            for binding in deviceBindingList {
                print("Binding Reference: \(binding.bindingReference ?? "")")
                print("Device Name: \(binding.deviceName ?? "")")
                print("Binding Status: \(binding.bindingStatus?.rawValue ?? "")")
            }
        }
    }
} catch let d1Error as D1Error {
    // Refer to D1 SDK Integration – Error Management section
} catch let error {
    // Handle other error
}

iOS < 4.5.0

let cardID = "" // Obtained for example, from server.
d1Task.digitalCardList(cardID) { digitalCards, error in
    if let error = error {
        // Refer to D1 SDK Integration – Error Management section.
    } else if let digitalCards = digitalCards {
        // Proceeds with subsequent flows. For example, update UI.
        for digitalCard in digitalCards {
            print("Digital cardID: \(digitalCard.cardID)")
            print("State: \(digitalCard.state.rawValue)")
            print("Last4: \(digitalCard.last4 ?? "")")
            print("Expiry: \(digitalCard.expiryDate ?? "")")
            print("DeviceID: \(digitalCard.deviceID ?? "")")
            print("Device name: \(digitalCard.deviceName ?? "")")
            print("Device type: \(digitalCard.deviceType ?? "")")
            print("TokenRequestorID: \(digitalCard.tokenRequestorID ?? "")")
            print("isOnCurrentDevice: \(digitalCard.isOnCurrentDevice)")

            // Retrieves device binding list (since SDK 4.3.0 for Visa CTF).
            if let deviceBindingList = digitalCard.deviceBindingList {
                for binding in deviceBindingList {
                    print("Binding Reference: \(binding.bindingReference ?? "")")
                    print("Device Name: \(binding.deviceName ?? "")")
                    print("Binding Status: \(binding.bindingStatus?.rawValue ?? "")")
                }
            }
        }
    }
}

Control digital cards

The issuer application can allow the End User to manage each digital card state.

Supported actions include:

• Suspend a digital card when the current state is active: d1Task.updateDigitalCard(cardID, digitalCard, CardAction.SUSPEND, callback)
• Resume a digital card when the current state is suspended: d1Task.updateDigitalCard(cardID, digitalCard, CardAction.RESUME, callback)
• Delete a digital card: d1Task.updateDigitalCard(cardID, digitalCard, CardAction.DELETE, callback)
• Activate a digital card (for example, after step-up authentication): d1PushWallet.activateDigitalCard(digitalCard.getCardID(), callback)

Sequence diagram

Pre-requisites

• Consumer account and card were registered in D1
• SDK is properly initialized
• Issuer App called D1 SDK login API

Example issuer application UI for controlling a digital card state.

Examples

Android

//digitalCard: retrieved from getDigitalCardList API
fun controlDigitalCard(d1Task: D1Task, cardID: String, digitalCard: DigitalCard) {
    val callback: D1Task.Callback<Boolean> = object : D1Task.Callback<Boolean> {

        override fun onSuccess(isSuccess: Boolean) {
            if (isSuccess) {
                // Digital Card State has been successfully updated.
                // Application can update the UI.
            } else {
                // Updating Digital Card State has failed.
            }
        }

        override fun onError(exception: D1Exception) {
            // Refer to D1 SDK Integration – Error Management section.
        }
    }

    // If current state of Digital Card is ACTIVE
    d1Task.updateDigitalCard(cardID, digitalCard, CardAction.SUSPEND, callback)
}

iOS >= 4.5.0

let cardID = "" // obtained e.g. from server
// If current state of Digital Card is ACTIVE
// digitalCard is retrieved from D1Task.digitalCardList API
do {
    let service = try d1Task.digitalCardService()
    try await service.updateDigitalCard(cardID, digitalCard: digitalCard, action: .suspend)
} catch let d1Error as D1Error {
    // Refer to D1 SDK Integration – Error Management section
} catch let error {
    // Handle other error
}

iOS < 4.5.0

let cardID = "" // obtained e.g. from server
// If current state of Digital Card is ACTIVE
// digitalCard is retrieved from D1Task.digitalCardList API
d1Task.updateDigitalCard(cardID, digitalCard: digitalCard, action: .suspend) { isSuccess, error in
    if let error = error {
        // Refer to D1 SDK Integration – Error Management section
    } else {
        if isSuccess {
            // Proceed with subsequent flows e.g. update UI
        } else {
            // Failure might be because of invalid state e.g. updating active card to active state
        }
    }
}

For a full access to the D1 SDK, please check API reference.