Push to token requestors (Token Connect)

Push to token requestors (Token Connect)

Use this guide to push a card from the issuer application to a token requestor using Mastercard MDES Token Connect.

Token requestors can include e-commerce merchants and wallet providers.

For Mastercard product documentation, see MDES Token Connect overview.

Overview

With Token Connect, the issuer application:

1. Retrieves the list of eligible token requestors for a card.
2. Requests a push URL for the selected token requestor.
3. Redirects the End User to the token requestor experience to complete Tokenization.

Prerequisites

• The End User is authenticated in the issuer application.
• The issuer application has initialized the D1 SDK and completed login.
• The consumer and card are registered in D1.

End-user experience

The diagram below illustrates a representative Token Connect flow. The same pattern applies to any Token Connect-compliant token requestor.

End-user experience example for pushing a card to a token requestor using Token Connect.

Flow

Retrieve eligible token requestors

Retrieve the eligible token requestors for a card.

Push to a token requestor

Generate a push URL for the selected token requestor and redirect the End User.

Sequence diagrams

1

Get eligible token requestors

The issuer application uses the D1 SDK to retrieve the list of token requestors that support Token Connect for a given card.

Each token requestor includes:

• A display name.
• A brand logo.
• One or more supported provisioning methods (for example, Android, iOS, or web).

Android >= 4.4.0

fun getEligibleTokenRequestors(d1Task: D1Task, cardID: String) {
    activity.lifecycleScope.launch(Dispatchers.Main) {
        try {
            val tkRequestorList = withContext(Dispatchers.IO) {
                d1Task.pushProvisioningService.getTokenRequestorList(
                    cardID
                ).await()
            }

            // Handle tkRequestorList object from server
            // Ex: to display it on the UI as sample image above
            for (tkRequestor : TokenRequestor in tkRequestorList) {
                val tkRequestorID : String = tkRequestor.id
                val tkRequestorName : String = tkRequestor.name
                val tkRequestorAssets : MutableList<AssetContent>? = tkRequestor.assets // Logo of the Token Requester
                val tkrProvisioningMethods : MutableList<ProvisioningMethod> = tkRequestor.provisioningMethods // Provisioning methods of the Token Requester
            }
        } catch (exception: D1Exception) {
            // Refer to D1 SDK Integration – Error Management section
        }
    }
}

Android < 4.4.0

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

        override fun onSuccess(tkRequestorList: List<TokenRequestor>) {
            // Handles tkRequestorList object from server.
            // Example to display it on the UI as sample image above.
            for (tkRequestor : TokenRequestor in tkRequestorList) {
                val tkRequestorID : String = tkRequestor.id
                val tkRequestorName : String = tkRequestor.name
                val tkRequestorAssets : MutableList<AssetContent>? = tkRequestor.assets // Logo of the Token Requestor.
                val tkrProvisioningMethods : MutableList<ProvisioningMethod> = tkRequestor.provisioningMethods // Provisioning methods of the Token Requestor.
            }
        }

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

    d1Task.getTokenRequestorList(cardID, callback)
}

iOS >= 4.4.0

let cardID = "" // obtained e.g. from server
        
do {
    let service = try d1Task.pushProvisioningService()
    let tokenRequestors = try await service.tokenRequestorList(cardID)
    // Display tokenRequestors in the UI
    for tokenRequestor in tokenRequestors {
        print("ID: \(tokenRequestor.id ?? "")")
        print("Name: \(tokenRequestor.name ?? "")")

        if let asset = tokenRequestor.asset?.first,
           let imageData = Data(base64Encoded: asset.encodedData) {
            let image = UIImage(data: imageData)
            _ = image
        }
    }
} catch let d1Error as D1Error {
    // Refer to D1 SDK Integration – Error Management section
} catch let error {
    // Handle other error
}

iOS < 4.4.0

let cardID = "" // Obtained, for example, from your backend

d1Task.tokenRequestorList(cardID) { tokenRequestors, error in
    if let error = error {
        // Refer to the D1 SDK integration error management section
    } else if let tokenRequestors = tokenRequestors {
        // Display tokenRequestors in the UI
        for tokenRequestor in tokenRequestors {
            print("ID: \(tokenRequestor.id ?? "")")
            print("Name: \(tokenRequestor.name ?? "")")

            if let asset = tokenRequestor.asset?.first,
               let imageData = Data(base64Encoded: asset.encodedData) {
                let image = UIImage(data: imageData)
                _ = image
            }
        }
    }
}

2

Push a card to a token requestor

After the End User selects a token requestor, the issuer application requests a push URL by calling addDigitalCardToScheme().

The issuer application then redirects the End User to the token requestor using the returned push URL.

Android >= 4.4.0

fun pushCardToTokenRequestor(d1Task: D1Task, cardID: String, tokenRequestor: TokenRequestor) {
    val appURL = "d1demoapp://com.thalesgroup.gemalto.d1.validation/PushToSchemeResult" // The issuer app's custom URL that the token requester calls back upon completion of digitization flow
    val tcsAccepted = true

    // For Click to Pay , the Mastercard tokenRequester.id attribute value is 50123197928.
    activity.lifecycleScope.launch(Dispatchers.Main) {
        try {
            val pushUrl = withContext(Dispatchers.IO) {
                d1Task.pushProvisioningService.addDigitalCardToScheme(
                    cardID,
                    tokenRequestor,
                    appURL,
                    tcsAccepted
                ).await()
            }
            // Launch token requester application
            activity.startActivity(Intent(Intent.ACTION_VIEW, Uri.parse(pushUrl)))
        } catch (exception: D1Exception) {
            // Refer to D1 SDK Integration – Error Management section
        }
    }
}

Android < 4.4.0

//cardID: Received with getConsumerDetails API.
//tokenRequestor: User selected.
fun pushCardToTokenRequestor(d1Task: D1Task, cardID: String, tokenRequestor: TokenRequestor) {
    val appURL = "d1demoapp://com.thalesgroup.gemalto.d1.validation/PushToSchemeResult" // The issuer app's custom URL that the token requester calls back upon completion of digitization flow.
    val tcsAccepted = true

    val callback: D1Task.Callback<String> = object : D1Task.Callback<String> {

        override fun onSuccess(pushUrl: String) {
            // Launches the token requester application.
            getActivity().startActivity(Intent(Intent.ACTION_VIEW, Uri.parse(pushUrl)))
        }

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

    // For Click to Pay, the Mastercard tokenRequestor.id attribute value is 50123197928.
    d1Task.addDigitalCardToScheme(
        cardID,
        tokenRequestor,
        appURL,
        tcsAccepted,
        callback
    )
}

iOS >= 4.4.0

let provisionMethod = PushProvisioningService.ProvisioningMethod(pushHandler: "pushHandler", platformType: "iOS")
let tokenRequestor = PushProvisioningService.TokenRequestor(id: "test", name: "test", asset: nil, provisioningMethods: [provisionMethod])
let cardID = "" // obtained e.g. from server
let appURL = "test://sample.com.demo/tokenRequestorsPage"
// the issuer appURL, which is configured using deep link mechanism.
// The token requestor app will call back this URL to pass the push card info result.
do {
    let service = try d1Task.pushProvisioningService()
    let provisionString = try await service.addDigitalCardToScheme(cardID,
                                                                   tokenRequestor: tokenRequestor,
                                                                   appURL: appURL,
                                                                   termsAndConditionsAccepted: true)
    if let provisionURL = URL(string: provisionString) {
        if await UIApplication.shared.canOpenURL(provisionURL) {
            await UIApplication.shared.open(provisionURL)
        }
    }
} catch let d1Error as D1Error {
    // Refer to D1 SDK Integration – Error Management section
} catch let error {
    // Handle other error
}

iOS < 4.4.0

let cardID = "" // Obtained, for example, from your backend

// The issuer application's deep link URL that the token requestor calls after the Tokenization flow.
let appURL = "test://sample.com.demo/tokenRequestorsPage"

// tokenRequestor is selected by the End User and returned by tokenRequestorList().

d1Task.addDigitalCardToScheme(
    cardID,
    tokenRequestor: tokenRequestor,
    appURL: appURL,
    termsAndConditionsAccepted: true
) { provisionString, error in
    if let error = error {
        // Refer to the D1 SDK integration error management section
    } else if let provisionString = provisionString,
              let pushUrl = URL(string: provisionString),
              UIApplication.shared.canOpenURL(pushUrl) {
        UIApplication.shared.open(pushUrl)
    }
}

What happens next

• The D1 SDK returns a push URL.
• The issuer application opens the push URL in the token requestor application or in a web view.
• The token requestor performs the Tokenization flow.
• When the flow completes, the token requestor redirects the End User back to the issuer application using the appURL.

• To configure appURL, implement deep links in your issuer application: Android, iOS.
• The token requestor returns the Tokenization result to the issuer application. For details, see the Mastercard guide: Receive response from token requestor.

Mastercard streamlined activation is not supported.

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