Push provisioning via TSP

Mastercard Token Connect (MDES Token Connect) is a service provided by Mastercard. Issuers use it to push cards to token requestors.

To participate, token requestors must comply with the Mastercard program and provide onboarding details to the TSPs. This lets the TSP determine how a card can be pushed to a given token requestor.

Typically, these services expose an API that allows issuers to:

Query TSPs for the token requestors registered to the program and their available interface details (an application, a website, or both).
Query TSPs for the appropriate URI (formatted with the card details) that the issuer application uses to push the card, after the end user selects a token requestor interface (such as a website).

The last step—pushing the card to the token requestor—remains the responsibility of the issuer application.

To use these APIs, issuers must open a project with the payment networks. Otherwise, the payment networks will not allow API access.

The Thales Push Provisioning solution embeds the MDES Token Connect APIs. This lets issuers access them directly from the issuer application through the SDK.

Note
Only token requestors registered in MDES Token Connect programs are accessible. Availability varies by region. For the list available in your region, check with your Visa and Mastercard contacts.

The following sections provide the details:

Use Thales SDK to request the list of token requestors eligible for a given card.
Select a token requestor from the returned list and use Thales SDK to request the formatted URI that is used to push the card.
Push the card to the selected token requestor.

Note
The issuer application always pushes the card to the selected token requestor interface.

1. Getting the eligible token requestors

The issuer application uses the Push Provisioning SDK to get a list of token requestors that are compatible with the issuer’s cards and the associated payment schemes.

This flow is shown in the following figure:

Steps 1 and 2: The issuer builds the encrypted card details according to the format expected by the Push Provisioning SDK.
Step 3: The issuer application calls the SDK through the getEligibleTokenRequestors (Android/iOS) with the card details.
Step 4: The Thales backend calls the TSP (VTS or MDES) to request the eligible token requestors.
Step 5: The list is returned to the issuer mobile application.
Step 6: The issuer mobile application gets the details for each token requestor and displays them to the end user so that a selection can be made.

Note
Step 6 in the figure shows a possible interaction with the end user.
The overall UX is out of scope for this document.
The issuer is free to filter out the token requestors that are visible to the end user.
As there may be many dozens of token requestors available, the application has to manage the visibility of the items.

The following code snippet shows how to request the list of eligible token requestors:

let scheme = "MASTERCARD"
let payload = "PKCS7 encrypted PAN"

let card = FundingCard(schemeString: scheme,
                        encryptedPayload: payload)

let publicKeyId = "id"

TPCSDK.getEligibleTokenRequestor(card: card,
                                  publicKeyIdentifier: publicKeyId) { (tokenRequestorList, error) in
    if let error = error {
        //Handle TPCError
    } else {
        let tokenRequestor = tokenRequestorList?.first
        let pushMethod = tokenRequestor?.pushMethods?.first
        let pushHandler = pushMethod?.pushHandler // for push provisioning
    }
}

NSString *scheme = @"MASTERCARD";
NSString * payload = @"PKCS7 encrypted PAN";

FundingCard * card = [[FundingCard alloc] initWithSchemeString:scheme
                                              encryptedPayload:payload
                                      primaryAccountIdentifier:nil];

NSString * publicKeyId = @"id";

[TPCSDK getEligibleTokenRequestorWithCard:card
                      publicKeyIdentifier:publicKeyId
                                completion:^(NSArray<TokenRequestor *> * _Nullable tokenRequestorList, NSError * _Nullable error) {
    if (error != nil) {
        //Handle TPCError
    } else {
        TokenRequestor *tokenRequestor = tokenRequestorList[0];
        PushMethod *pushMethod = [tokenRequestor pushMethods][0];
        NSString *pushHandler = pushMethod.pushHandler;
    }
}];

Config config = new Config();
config.setActivity(activity);
config.setIssuerId(ISSUERID);
config.setOemPayType(OEMPayType.NONE); // This one is required to get correct PushProvisioning object
config.setUrl(envUrl);

TPCManager.getInstance().config(config, listener);
TPCManager.getInstance().getTSHProxy().getEligibleTokenRequestors(cardScheme, 
                                                                  encryptedPayload, 
                                                                  publicKeyId, 
                                                                  new TPCSDKListener<TokenRequestor[]>() {
    @Override
    public void onStart() {

    }

    @Override
    public void onSuccess(TPCResult<TokenRequestor[]> tpcResult) {
        TokenRequestor[] tokenRequestors = tpcResult.getResult();
        String pushHandler = tokenRequestors[0].getPushMethods()[0].getPushHandler(); // for push provisioning
    }

    @Override
    public void onError(TPCSDKException exception) {
        listener.onError(exception);
    }
});

Get asset

Using the TPC SDK, the issuer application can obtain the token requestor’s logo image using the string returned by the getEligibleTokenRequestor API.

For the Visa scheme, the image of the token requestor's logo is returned as a URL that the mobile application has to fetch directly.

For the Mastercard scheme, the logo image is returned as a logoId. To fetch the logo, call the getAsset API.

Getting the logo of token requestor

Note
This is only available for the Mastercard scheme.

After the application has obtained the list of token requestors, it can request to get the image of the token requestor's logo.

The following code snippet shows an example of how to get the token requestor’s logo image via the TPC SDK:

func getTokenRequestorWithAssetId(id: String) {
    TPCSDK.getTokenRequestorAsset(assetId: id) {
      (tokenRequestorAsset, error) in
    }
  }


- (void) getTokenRequestorWithAssetId: (NSString *) id {
  [TPCSDK getTokenRequestorAssetWithAssetId:id
                                 completion:^(NSArray<TokenRequestorAsset *> * _Nullable tokenRequestorAsset, NSError * _Nullable error) {
  }];
}



try {
    TPCManager.getInstance().getTSHProxy().getAsset(assetId,
 	   new TPCSDKListener<MediaData[]>() {
        @Override
        public void onStart() {
            // Do nothing
        }

        @Override
        public void onSuccess(TPCResult<MediaData[]> result) {                
		    		MediaData[] mediaData = result.getResult();
            Log.d("TAG", "get Asset request success"); 
        }

        @Override
        public void onError(TPCSDKException exception) {
            Log.e("TAG", "get Asset request failed");
        }
      });
} catch (TPCSDKException exception) {
    Log.e("TAG", "TSHProxy Exception " +exception.getMessage());
}

2. Selecting the token requestor

Each element that is returned by the getEligibleTokenRequestors (Android/iOS) is a potential token requestor to which the card can be pushed.

A TokenRequestor object will expose the following properties:

id: The Token Requestor ID (TRID) which is unique as per token requestor and is generated by the scheme.
name: The name of the token requestor to be displayed.
logo: The displayable icon that is associated with the token requestor.
- For Mastercard, this can be accessed through the logoId and getAsset APIs.
pushMethods: This object is an array of methods that can be used to contact the given token requestor. Each element of the array has two properties:
- platformType: Indicates the platform the token requestor application is available on: ANDROID, IOS, or WEB.
- pushHandler: Contains information about how to manage the push request to the token requestor. For each platformType, there is a pushHandler which is used to request the URI formatted with the card details from the TSP so that it can be used to call the token requestor.

Because a token requestor may be accessible through multiple interfaces, pay close attention to pushMethods:

Application interface (when platformType=ANDROID or platformType=IOS)
Website interface (when platformType=WEB)

For an application interface, the issuer application interacts with the token requestor application.

Warning
If the token requestor application is not installed, the issuer application must handle the following cases:
In ANDROID, ActivityNotFoundException has to be handled when calling the startActivity method.
In IOS, the issuer application has to check if the URL is available using the canOpenURL API.
Verifying whether the token requestor application is installed is outside the Thales SDK scope. The token requestor must provide a URI to the TSPs during onboarding.

For website interface, the issuer application has to interact with the website of the token requestor.

Recommendation
For a streamlined experience, support platformType=WEB. Handle the flow in a WebView within the issuer application, instead of redirecting to an external application.

3. Pushing the card

To push a card to a selected token requestor, you need the URI that triggers the token requestor with correctly formatted card details. Query this URI from the TSP.

This flow is depicted in the following figure:

Step 1: The end user selects a token requestor.
Step 2: The issuer application gets the pushHandler property from the TokenRequestor object and calls the SDK through the addCard (Android/iOS) API.
Step 3: The SDK interacts with the backend to request a push provisioning.
Step 4: The Thales backend verifies whether the request is authorized.
Step 5: The Thales backend requests the payload and generates a push URL through the TSP.
Step 6: The SDK returns the push URL to the issuer application.
Step 7: The issuer application calls the push URL to launch the token requestor.

Note
The URI depends on platformType. pushHandler changes based on whether the interface is an application or a website.

For the other parameters shown in the figure:

The authorizationCode is required to grant the permission to send the request. This has to be compliant with the format and algorithm.
The callback URL allows the token requestor to call the issuer application at the end of the flow. This has to be configured using the deep link mechanism.

Setting up a deep link URL
Android
iOS

The following sample code demonstrates how to get the URI from the TSP through the SDK:

let scheme = "MASTERCARD"
let payload = "3080xxx"

let card = FundingCard(schemeString: scheme,
                    encryptedPayload: payload)

let publicKeyId = "id"
let code = "code"
let callbackUrl = "tpcsdk://com.thalesgroup.tpc.demo/tokenRequestorsPage"
let base64EncodedCallbackUrl = callbackUrl.data(using: .utf8)!.base64EncodedString()
let callbackType = "IOS"

// This value can be retrieved from TPCSDK.getEligibleTokenRequestor
// For Click to Pay , the MasterCard tokenRequestor.id attribute value is 50123197928.
let pushHandler = "handler"

TPCSDK.schemePushProvision(card: card,
                            publicKeyIdentifier: publicKeyId,
                            authorizationCode: code,
                            termsAndConditionsAccepted: true,
                            callbackUrl: base64EncodedCallbackUrl,
                            callbackType: callbackType,
                            pushHandler: pushHandler) { (pushUrl, error) in
    if let error = error {
        // handle TPC Error
    } else if let pushUrl = pushUrl {
        // launch the token requestor app
        let url = URL(string: pushUrl)!
        if UIApplication.shared.canOpenURL(provisionURL) {
          UIApplication.shared.open(url, options: [:], completionHandler: nil)
        } else {
          // show error that Application is not installed
        }
    }
}


NSString *scheme = @"MASTERCARD";
NSString * payload = @"PKCS7 encrypted PAN";

FundingCard * card = [[FundingCard alloc] initWithSchemeString:scheme
                                              encryptedPayload:payload
                                      primaryAccountIdentifier:nil];

NSString * publicKeyId = @"id";
NSString * code = @"code";
NSString * callbackUrl = @"tpcsdk://com.thalesgroup.tpc.demo/tokenRequestorsPage";
NSString * base64EncodedCallbackUrl = [[NSString alloc] initWithData:[[callbackUrl dataUsingEncoding:NSUTF8StringEncoding] base64EncodedDataWithOptions:NSDataBase64EncodingEndLineWithLineFeed] encoding:NSUTF8StringEncoding];
NSString * callbackType = @"IOS";

// This value can be retrieved from TPCSDK.getEligibleTokenRequestor
// For Click to Pay , the MasterCard tokenRequestor.id attribute value is 50123197928.
NSString * pushHandler = @"handler";

[TPCSDK schemePushProvisionWithCard:card
                publicKeyIdentifier:publicKeyId
                  authorizationCode:code
          termsAndConditionsAccepted:TRUE
                        callbackUrl:base64EncodedCallbackUrl
                        callbackType:callbackType
                        pushHandler:pushHandler
                          completion:^(NSString * _Nullable pushUrl, NSError * _Nullable error) {
    if (error != nil) {
        // handle TPCError
    } else {
        // launch the token requestor app
        [[UIApplication sharedApplication] openURL:[NSURL URLWithString:pushUrl] options:@{} completionHandler:nil];
    }
}];



CardInfo cardInfo = new CardInfo();
cardInfo.setScheme("MASTERCARD");
cardInfo.setEncryptedPayload(encryptedPayload);
cardInfo.setAuthorizationCode(authorizationCode);

CallbackObject callback = new CallbackObject();
String callbackUrl = "tpcsdk://com.thalesgroup.tpc.demo/tokenRequestorsPage";
String callbackUrlInBase64 = Base64.encodeToString(callbackUrl.getBytes(), Base64.NO_WRAP | Base64.URL_SAFE);
callback.setUrl(callbackUrlInBase64);
callback.setType("ANDROID");

String publicKeyId = "id";
boolean tcsAccepted = true;

// This value can be retrieved from TPCSDK.getEligibleTokenRequestor
// For Click to Pay , the MasterCard tokenRequestor.id attribute value is 50123197928.
String pushHandler = "handler";

TPCManager.getInstance().getTSHProxy().addCard(cardInfo, 
                                               publicKeyId, 
                                               tcsAccepted, 
                                               callback, 
                                               pushHandler, 
                                               new TPCSDKListener<String>() {
    @Override
    public void onStart() {

    }

    @Override
    public void onSuccess(TPCResult<String> result) {
        String pushUrl = result.getResult();

        // Launch token requestor application
        try {
          getActivity().startActivity(new Intent(Intent.ACTION_VIEW, Uri.parse(pushUrl)));
        } catch (ActivityNotFoundException e) {
          // No Activity available to handle action
        }
    }

    @Override
    public void onError(TPCSDKException exception) {
        // Check if there's any error in the push provisioning
    }
});

The following figure depicts a generic flow where the issuer application pushes the card to the token requestor application.

The first part of the flow involves only the issuer application.

In step 3, the issuer application uses the list returned by the getEligibleTokenRequestors API (Android/iOS) to build the interface displayed to the end user.

When the end user confirms in step 4 that they want to push the card (or immediately after the selection in step 3), the issuer application calls the SDK using the addCard (Android/iOS) so the SDK can query the TSP for the URI used to push the card.

Once the URI is returned from step 4, the issuer application uses the URI to push the card to the token requestor.

The token requestor takes control in step 5, and there will be several pop-ups to drive the end user through the tokenization flow.

At this point, the token requestor application is in full control. It interacts with the TSP to request card digitization, as shown in steps 6 and 7.

Once digitization completes, the end user can proceed as shown in step 7. Control can return to the issuer application if the token requestor uses the callback URL provided by addCard (Android/iOS) API.

PreviousPush Provisioning Extensions NextView & Control

Last updated 3 months ago

Was this helpful?