Aprovisionamiento push mediante TSP

Mastercard Token Connect (MDES Token Connect) es un servicio proporcionado por Mastercard. Los emisores lo usan para enviar tarjetas a los token requestors.

Para participar, los token requestors deben cumplir con el programa de Mastercard y proporcionar los detalles de incorporación a los TSP. Esto permite al TSP determinar cómo se puede enviar una tarjeta a un token requestor determinado.

Por lo general, estos servicios exponen una API que permite a los emisores:

• Consultar a los TSP los token requestors registrados en el programa y los detalles de interfaz disponibles (una aplicación, un sitio web o ambos).

• Consultar a los TSP la URI apropiada (formateada con los datos de la tarjeta) que la aplicación del emisor usa para enviar la tarjeta, después de que el usuario final selecciona una interfaz del token requestor (como un sitio web).

El último paso: enviar la tarjeta al token requestor, sigue siendo responsabilidad de la aplicación del emisor.

Para usar estas API, los emisores deben abrir un proyecto con las redes de pago. De lo contrario, las redes de pago no permitirán el acceso a la API.

La solución Thales Push Provisioning incorpora las API de MDES Token Connect. Esto permite a los emisores acceder a ellas directamente desde la aplicación del emisor a través del SDK.

Nota

Solo son accesibles los token requestors registrados en programas de MDES Token Connect. La disponibilidad varía según la región. Para conocer la lista disponible en su región, consulte con sus contactos de Visa y Mastercard.

Las siguientes secciones proporcionan los detalles:

1. Use el SDK de Thales para solicitar la lista de token requestors elegibles para una tarjeta dada.

2. Seleccione un token requestor de la lista devuelta y use el SDK de Thales para solicitar la URI formateada que se usa para enviar la tarjeta.

3. Envía la tarjeta al token requestor seleccionado.

Nota

La aplicación del emisor siempre envía la tarjeta a la interfaz del token requestor seleccionada.

1. Obtención de los token requestors elegibles

La aplicación del emisor usa el SDK de Push Provisioning para obtener una lista de token requestors compatibles con las tarjetas del emisor y los esquemas de pago asociados.

Este flujo se muestra en la siguiente figura:

Obtener token requestors elegibles para una tarjeta.

• Pasos 1 y 2: El emisor construye los datos cifrados de la tarjeta según el formato esperado por el SDK de Push Provisioning.

• Paso 3: La aplicación del emisor llama al SDK a través de la getEligibleTokenRequestors (Android/iOS) con los datos de la tarjeta.

• Paso 4: El backend de Thales llama al TSP (VTS o MDES) para solicitar los token requestors elegibles.

• Paso 5: La lista se devuelve a la aplicación móvil del emisor.

• Paso 6: La aplicación móvil del emisor obtiene los detalles de cada token requestor y los muestra al usuario final para que se pueda hacer una selección.

Nota

• El paso 6 de la figura muestra una posible interacción con el usuario final.

• La UX general queda fuera del alcance de este documento.

• El emisor es libre de filtrar los token requestors visibles para el usuario final.

• Como puede haber varias decenas de token requestors disponibles, la aplicación debe gestionar la visibilidad de los elementos.

El siguiente fragmento de código muestra cómo solicitar la lista de token requestors elegibles:

Swift

let scheme = "MASTERCARD"
let payload = "PAN cifrado en PKCS7"

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

let publicKeyId = "id"

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

Objective-C

NSString *scheme = @"MASTERCARD";
NSString * payload = @"PAN cifrado en PKCS7";

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) {
        //Manejar TPCError
    } else {
        TokenRequestor *tokenRequestor = tokenRequestorList[0];
        PushMethod *pushMethod = [tokenRequestor pushMethods][0];
        NSString *pushHandler = pushMethod.pushHandler;
    }
}];

Android

Config config = new Config();
config.setActivity(activity);
config.setIssuerId(ISSUERID);
//Desde Push Provisioning SDK V2.0.0, OEMPayType.NONE ya no es compatible. 
//Solo establezca OEMPayType cuando realice la provisión de OEM Wallet. De lo contrario, deje sin definir el tipo OEM.
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(); // para push provisioning
    }

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

Obtener recurso

Usando el SDK de TPC, la aplicación del emisor puede obtener la imagen del logotipo del token requestor utilizando la cadena devuelta por la getEligibleTokenRequestor API.

Para el esquema Visa, la imagen del logotipo del token requestor se devuelve como una URL que la aplicación móvil debe obtener directamente.

Para el esquema Mastercard, la imagen del logotipo se devuelve como un logoId. Para obtener el logotipo, llame a la getAsset API.

Recuperar el logotipo de un token requestor (solo Mastercard).

Obtención del logotipo del token requestor

Nota

Esto solo está disponible para el esquema Mastercard.

Después de que la aplicación haya obtenido la lista de token requestors, puede solicitar la imagen del logotipo del token requestor.

El siguiente fragmento de código muestra un ejemplo de cómo obtener la imagen del logotipo del token requestor a través del SDK de TPC:

Swift

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

Objective-C

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

Android

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

        @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. Selección del token requestor

Cada elemento devuelto por la getEligibleTokenRequestors (Android/iOS) es un posible token requestor al que se puede enviar la tarjeta.

Un TokenRequestor objeto expondrá las siguientes propiedades:

• id: El ID del token requestor (TRID), que es único para cada token requestor y lo genera el esquema.

• name: El nombre del token requestor que se mostrará.

• logo: El icono visible asociado con el token requestor.

  • Para Mastercard, se puede acceder a esto a través de las logoId y getAsset API.

• pushMethods: Este objeto es una matriz de métodos que se pueden usar para contactar al token requestor dado. Cada elemento de la matriz tiene dos propiedades:

  • platformType: Indica la plataforma en la que está disponible la aplicación del token requestor: ANDROID, IOS, o WEB.

  • pushHandler: Contiene información sobre cómo gestionar la solicitud push al token requestor. Para cada platformType, hay un pushHandler que se utiliza para solicitar la URI con formato de los datos de la tarjeta al TSP, de modo que pueda usarse para llamar al token requestor.

Dado que un token requestor puede ser accesible a través de varias interfaces, preste mucha atención a pushMethods:

• Interfaz de aplicación (cuando platformType=ANDROID o platformType=IOS)

• Interfaz de sitio web (cuando platformType=WEB)

Para una interfaz de aplicación, la aplicación del emisor interactúa con la aplicación del token requestor.

Advertencia

Si la aplicación del token requestor no está instalada, la aplicación del emisor debe manejar los siguientes casos:

• En ANDROID, ActivityNotFoundException debe controlarse al llamar al startActivity método.

• En IOS, la aplicación del emisor debe comprobar si la URL está disponible usando canOpenURL API.

Verificar si la aplicación del token requestor está instalada queda fuera del alcance del SDK de Thales. El token requestor debe proporcionar una URI a los TSP durante la incorporación.

Para una interfaz de sitio web, la aplicación del emisor debe interactuar con el sitio web del token requestor.

Recomendación

Para una experiencia más fluida, admita platformType=WEB. Gestione el flujo en una WebView dentro de la aplicación del emisor, en lugar de redirigir a una aplicación externa.

3. Envío de la tarjeta

Para enviar una tarjeta a un token requestor seleccionado, necesita la URI que activa el token requestor con los datos de la tarjeta correctamente formateados. Consulte esta URI en el TSP.

Este flujo se muestra en la siguiente figura:

Solicitar una URI de envío al TSP.

• Paso 1: El usuario final selecciona un token requestor.

• Paso 2: La aplicación del emisor obtiene la pushHandler propiedad del TokenRequestor objeto y llama al SDK a través de la addCard (Android/iOS) API.

• Paso 3: El SDK interactúa con el backend para solicitar una provisión push.

• Paso 4: El backend de Thales verifica si la solicitud está autorizada.

• Paso 5: El backend de Thales solicita la carga útil y genera una URL de envío a través del TSP.

• Paso 6: El SDK devuelve la URL de envío a la aplicación del emisor.

• Paso 7: La aplicación del emisor llama a la URL de envío para iniciar el token requestor.

Nota

La URI depende de platformType. pushHandler cambia según si la interfaz es una aplicación o un sitio web.

Para los demás parámetros mostrados en la figura:

• El authorizationCode es necesario para conceder el permiso para enviar la solicitud. Esto debe cumplir con el formato y algoritmo.

• La URL de callback permite que el token requestor llame a la aplicación del emisor al final del flujo. Esto debe configurarse mediante el mecanismo de deep link.

Configuración de una URL de deep link

• Android

• iOS

El siguiente código de ejemplo demuestra cómo obtener la URI del TSP a través del SDK:

Swift

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"

// Este valor se puede obtener de TPCSDK.getEligibleTokenRequestor
// Para Click to Pay, el valor del atributo tokenRequestor.id de MasterCard es 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 {
        // manejar error de TPC
    } else if let pushUrl = pushUrl {
        // iniciar la aplicación del token requestor
        let url = URL(string: pushUrl)!
        if UIApplication.shared.canOpenURL(provisionURL) {
          UIApplication.shared.open(url, options: [:], completionHandler: nil)
        } else {
          // mostrar error de que la aplicación no está instalada
        }
    }
}

Objective-C

NSString *scheme = @"MASTERCARD";
NSString * payload = @"PAN cifrado en PKCS7";

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";

// Este valor se puede obtener de TPCSDK.getEligibleTokenRequestor
// Para Click to Pay, el valor del atributo tokenRequestor.id de MasterCard es 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) {
        // manejar TPCError
    } else {
        // iniciar la aplicación del token requestor
        [[UIApplication sharedApplication] openURL:[NSURL URLWithString:pushUrl] options:@{} completionHandler:nil];
    }
}];

Android

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;

// Este valor se puede obtener de TPCSDK.getEligibleTokenRequestor
// Para Click to Pay, el valor del atributo tokenRequestor.id de MasterCard es 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();

        // Iniciar la aplicación del token requestor
        try {
          getActivity().startActivity(new Intent(Intent.ACTION_VIEW, Uri.parse(pushUrl)));
        } catch (ActivityNotFoundException e) {
          // No hay ninguna Activity disponible para manejar la acción
        }
    }

    @Override
    public void onError(TPCSDKException exception) {
        // Comprobar si hay algún error en la provisión push
    }
});

La siguiente figura muestra un flujo genérico en el que la aplicación del emisor envía la tarjeta a la aplicación del token requestor.

Flujo genérico de push provisioning con un token requestor.

La primera parte del flujo involucra solo a la aplicación del emisor.

En el paso 3, la aplicación del emisor usa la lista devuelta por la getEligibleTokenRequestors API (Android/iOS) para construir la interfaz mostrada al usuario final.

Cuando el usuario final confirma en el paso 4 que desea enviar la tarjeta (o inmediatamente después de la selección en el paso 3), la aplicación del emisor llama al SDK usando el addCard (Android/iOS) para que el SDK pueda consultar al TSP la URI utilizada para enviar la tarjeta.

Envíe la tarjeta iniciando el token requestor.

Una vez que la URI se devuelve en el paso 4, la aplicación del emisor usa la URI para enviar la tarjeta al token requestor.

El token requestor toma el control en el paso 5, y aparecerán varias ventanas emergentes para guiar al usuario final a través del flujo de tokenización.

En este punto, la aplicación del token requestor tiene el control total. Interactúa con el TSP para solicitar la digitalización de la tarjeta, como se muestra en los pasos 6 y 7.

Una vez completada la digitalización, el usuario final puede continuar como se muestra en el paso 7. El control puede volver a la aplicación del emisor si el token requestor usa la URL de callback proporcionada por addCard (Android/iOS) API.