Autenticación en la app para Visa CTF

Se requiere un servicio de tokenización para usar el SDK Thales D1 para el flujo de autenticación en la aplicación.

Visa Cloud Token Framework (CTF) es un marco de Visa diseñado para aumentar la confianza en las tarjetas digitales de comercio electrónico después de la tokenización.

CTF define dos flujos: vinculación del dispositivo y verificación del titular de la tarjeta.

Estos flujos permiten al comerciante aumentar la confianza en una tarjeta digital al activar un flujo de autenticación reforzada del titular de la tarjeta con el emisor.

Para obtener más detalles sobre los flujos completos y Visa Cloud Token Framework (CTF), consulta la sección marco de tokenización en la nube de Visa de la documentación de Tokenización.

El flujo de autenticación en la aplicación para Visa CTF es muy similar al flujo descrito en Autenticación en la aplicación.

Los pasos [01] a [10] son esencialmente los mismos.

La principal diferencia es el formato de la carga útil, que se muestra en la siguiente tabla:

Vinculación del dispositivo - carga útil	Verificación del titular de la tarjeta - carga útil
{ "panReferenceID": "V-3815023863409817870482", "tokenRequestorID": "42301999123", "tokenReferenceID": "DNITHE381502386342002358", "panLast4": "1234", "deviceID": "DEiOiJBMjU2R_0NNS1-ciLCJiI", "walletAccountID": "AiOiJBMjU-2_R0NNS1ciLCJiI6", "deviceIndex": "1", "reasonCode": "TOKEN_DEVICE_BINDING" }	{ "panReferenceID": "V-3815023863409817870482", "tokenRequestorID": "42301999123", "tokenReferenceID": "DNITHE381502386342002358", "panLast4": "1234", "deviceID": "null", "walletAccountID": "AiOiJBMjU-2_R0NNS1ciLCJiI6", "deviceIndex": "null", "reasonCode": "CARDHOLDER_STEPUP" }

En comparación con la autenticación estándar de tokenización, la aplicación del emisor debe inspeccionar:

• reasonCode: identifica el motivo de la autenticación CTF.

  • TOKEN_DEVICE_BINDING: flujo de vinculación del dispositivo.
  • CARDHOLDER_STEPUP: flujo de verificación del titular de la tarjeta.
• deviceIndex: se usa para el flujo de vinculación del dispositivo. Esta es la referencia del dispositivo Visa. En el SDK D1, se asigna a bindingReference.

Cuando te refieras al diagrama de secuencia en Autenticación en la aplicación, reemplaza los pasos [11] y [12] con una nueva llamada a la API.

En este caso, no hay activación de la tarjeta digital. En su lugar, el resultado de la autenticación debe propagarse a Visa VTS.

El SDK D1 expone las siguientes API para que la aplicación del emisor pueda informar del resultado:

1. Para TOKEN_DEVICE_BINDING, llame a DigitalCardService.approveBinding con digitalCardID y deviceIndex.
2. Para CARDHOLDER_STEPUP, llame a DigitalCardService.approveCardholderVerification con digitalCardID.

El SDK D1 también te permite:

1. Recuperar la lista de dispositivos vinculados como deviceBindingList cuando getDigitalCardList() se llama. Para más detalles, consulta Ver y controlar tarjetas digitales.
2. Desvincula un dispositivo llamando a DigitalCardService.unbindDevice. Consulta Desvinculación de dispositivos.

Los siguientes ejemplos muestran cómo analizar la carga útil y aprobar una solicitud de vinculación.

Nota

Se aplica el siguiente mapeo de campos:

• tokenReferenceID = digitalCardID
• deviceIndex = bindingReference

Android

private const val VISA_STEPUP_RESULT_RESPONSE = "STEP_UP_RESPONSE"
private const val STEPUP_RESULT_APPROVED = "approved"
private const val STEPUP_RESULT_DECLINED = "declined"
private const val STEPUP_RESULT_FAILED = "failure"

val visaPayload = intent.getStringExtra(Intent.EXTRA_TEXT) ?: return

val payloadJson = try {
    val decodedPayload = String(Base64.decode(visaPayload, Base64.DEFAULT), Charsets.UTF_8)
    JSONObject(decodedPayload)
} catch (_: IllegalArgumentException) {
    // Carga útil base64 no válida
    return
} catch (_: JSONException) {
    // Carga útil JSON no válida
    return
}

val reasonCode = payloadJson.optString("reasonCode", "")
val digitalCardID = payloadJson.optString("tokenReferenceID", "") // tokenReferenceID -> digitalCardID
val bindingReference = payloadJson.optString("deviceIndex", "") // deviceIndex -> bindingReference

if ("TOKEN_DEVICE_BINDING" == reasonCode &&
    digitalCardID.isNotEmpty() &&
    bindingReference.isNotEmpty()) {

    d1Task.digitalCardService().approveBinding(
        digitalCardID,
        bindingReference,
        DigitalCardService.BindingApprovalReason.USER_DECISION,
        object : D1Task.Callback<Void> {
            override fun onSuccess(data: Void?) {
                sendResultToTokenRequestorApp(activity, null)
            }

            override fun onError(e: D1Exception) {
                sendResultToTokenRequestorApp(activity, e)
            }
        }
    )
} else {
    // Otros flujos (p. ej., activación)
}

private fun sendResultToTokenRequestorApp(activity: Activity, exception: D1Exception?) {
    val result = Intent()
    // posibles valores: "approved", "declined" o "failure"
    val stepupResult = if (exception == null) STEPUP_RESULT_APPROVED else STEPUP_RESULT_FAILED
    result.putExtra(VISA_STEPUP_RESULT_RESPONSE, stepupResult)
    // aplicable si el emisor utiliza activación mediante código de autenticación
    activity.setResult(Activity.RESULT_OK, result)
    activity.finish()
}

private static final String VISA_STEPUP_RESULT_RESPONSE = "STEP_UP_RESPONSE";
private static final String STEPUP_RESULT_APPROVED = "approved";
private static final String STEPUP_RESULT_DECLINED = "declined";
private static final String STEPUP_RESULT_FAILED = "failure";

String visaPayload = getIntent().getStringExtra(Intent.EXTRA_TEXT);
if (visaPayload == null) {
    return;
}

JSONObject payloadJson;
try {
    byte[] decodedPayloadBytes = Base64.decode(visaPayload, Base64.DEFAULT);
    String decodedPayload = new String(decodedPayloadBytes, StandardCharsets.UTF_8);
    payloadJson = new JSONObject(decodedPayload);
} catch (IllegalArgumentException | JSONException e) {
    // Carga útil base64/JSON no válida
    return;
}

String reasonCode = payloadJson.optString("reasonCode", "");
String digitalCardID = payloadJson.optString("tokenReferenceID", ""); // tokenReferenceID -> digitalCardID
String bindingReference = payloadJson.optString("deviceIndex", ""); // deviceIndex -> bindingReference

if ("TOKEN_DEVICE_BINDING".equals(reasonCode) &&
        !digitalCardID.isEmpty() &&
        !bindingReference.isEmpty()) {

    d1Task.digitalCardService().approveBinding(
            digitalCardID,
            bindingReference,
            DigitalCardService.BindingApprovalReason.USER_DECISION,
            new D1Task.Callback<Void>() {
                @Override
                public void onSuccess(Void data) {
                    sendResultToTokenRequestorApp(activity, null);
                }

                @Override
                public void onError(@NonNull D1Exception exception) {
                    sendResultToTokenRequestorApp(activity, exception);
                }
            });
} else {
    // Otros flujos (p. ej., activación)
}

private void sendResultToTokenRequestorApp(Activity activity, D1Exception exception) {
    Intent result = new Intent ();
    // posibles valores: "approved", "declined" o "failure"
    String stepupResult = (exception == null) ? STEPUP_RESULT_APPROVED : STEPUP_RESULT_FAILED;
    result.putExtra(VISA_STEPUP_RESULT_RESPONSE, stepupResult);
    // aplicable si el emisor utiliza activación mediante código de autenticación
    activity.setResult(RESULT_OK, result);
    activity.finish();
}

iOS

// Para admitir la redirección de la app desde Wallet.
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    guard let components = URLComponents(url: url, resolvingAgainstBaseURL: true) else { return false }

    let queryDict = components.queryItems?.reduce(into: [String: String]()) { dict, item in
        dict[item.name] = item.value
    } ?? [:]

    switch components.host {
    // Nombre de servicio de ejemplo que gestiona Visa app-to-app
    case "visaCTF":
        guard let wpCallback = queryDict["wpcallback"]?.removingPercentEncoding,
              let encodedPayload = queryDict["a2apayload"],
              let payloadData = Data(base64Encoded: encodedPayload.replacingOccurrences(of: " ", with: "+")),
              let json = try? JSONSerialization.jsonObject(with: payloadData) as? [String: Any],
              let reasonCode = json["reasonCode"] as? String else {
            return false
        }

        switch reasonCode {
        case "TOKEN_DEVICE_BINDING":
            guard let digitalCardID = json["tokenReferenceID"] as? String,
                  let bindingReference = json["deviceIndex"] as? String else {
                return false
            }

            Task {
                do {
                    try await d1Task.digitalCardService().approveBinding(
                        digitalCardID,
                        bindingReference: bindingReference,
                        reason: nil
                    )
                    sendResultToApp(wpCallback: wpCallback, stepupResult: "Approved")
                } catch {
                    sendResultToApp(wpCallback: wpCallback, stepupResult: "Failure")
                }
            }

        default:
            return false
        }

        return true
    default:
        return false
    }
}

private func sendResultToApp(wpCallback: String, stepupResult: String) {
    guard var components = URLComponents(string: wpCallback) else { return }

    var items = components.queryItems ?? []
    items.append(URLQueryItem(name: "stepupresponse", value: stepupResult))
    components.queryItems = items

    if let callbackURL = components.url {
        UIApplication.shared.open(callbackURL)
    }
}

Para obtener acceso completo al SDK de D1, consulte referencia de la API.