Implementar pago remoto DSRP

Descripción general

Utilice el pago remoto Mastercard DSRP para generar datos de pago para la aceptación remota (por ejemplo, comercio electrónico).

En este flujo, su aplicación de billetera digital genera los datos de pago. Luego, pasa esos datos a su sistema de comercio o pasarela de pago para su autorización.

Antes de implementar pagos remotos DSRP, complete Tokenización. Consulte Tokenizar una tarjeta.

El SDK de NFC Wallet admite el pago remoto DSRP para Mastercard tarjetas digitales con el perfil MCBP 2.x solo.

Si necesita el pago remoto DSRP para un perfil o red de pago diferente, póngase en contacto con su equipo de entrega de Thales.

Integración del SDK

Comprueba los requisitos previos

Confirme que la tarjeta digital admite el pago remoto DSRP mediante DigitalCard.Details.isPaymentTypeSupported() con PaymentType.dsrp.

func checkCardSupportForDSRP(card: DigitalCard) async throws -> Bool {
    return try await card.details.isPaymentTypeSupported(.dsrp)
}

Crear los datos de entrada de pago DSRP

Antes de generar datos de pago DSRP, debe proporcionar los datos de entrada en RemotePaymentInputData.

func buildRemoteInputData() -> RemotePaymentSession.RemotePaymentInputData  {
    let amount = "000000500030"  // 5000.30 EUR en unidades menores
    let currencyCode = "978"     // numérico ISO 4217
    let countryCode = "840"      // numérico ISO 3166-1 (ejemplo: US)
    let unpredictableNumber = "12345"
    
    return RemotePaymentSession.RemotePaymentInputData(
        amount: amount,
        currencyCode: currencyCode,
        transactionType: .purchase,
        unpredictableNumber: unpredictableNumber,
        countryCode: countryCode,
        cryptogramType: .de55
    )
}

RemotePaymentSession.RemotePaymentInputData tiene los siguientes campos:

Datos de entrada	Tipo	Formato	Descripción
amount	Cadena	Numérico, en unidades menores	Obligatorio Importe de la transacción en unidades menores (sin separador decimal). Por ejemplo, 119.00 USD es 11900 (luego añada ceros a la izquierda si su integración requiere longitud fija).
currencyCode	Cadena	Numérico ISO 4217 de 3 dígitos	Obligatorio Código de moneda de la transacción. Por ejemplo, USD es 840.
countryCode	Cadena	Numérico ISO 3166-1 de 3 dígitos	Obligatorio Código de país del comerciante. Por ejemplo, Estados Unidos es 840.
transactionType	Enum	.purchase	Obligatorio Tipo de transacción financiera. Para pagos DSRP, use .purchase.
cryptogramType	Enum	.ucaf o .de55	Obligatorio Formato de datos del criptograma devuelto por el SDK.
unpredictableNumber	Cadena	Numérico	Obligatorio Número aleatorio generado por el comerciante o la pasarela de pago.

Generar datos de pago DSRP

En su aplicación de billetera digital, llame a RemotePaymentSession.generateRemotePayment().

Esta API puede generar un error. Consulte Maneja los errores.

Si tiene éxito, la API devuelve RemotePaymentOutputData con los siguientes campos:

Parámetro	Descripción
cryptogramData	Matriz de bytes que contiene la respuesta formateada. Esto puede ser datos UCAF o TLV para que el comerciante complete DE-55.
pan	PAN con cualquier F relleno eliminado (si lo hay).
panSequenceNumber	Número de secuencia del PAN (PSN) de la tarjeta utilizada.
track2EquivalentData	Elementos de datos de la pista 2 según ISO/IEC 7813 (excluyendo el sentinel de inicio, el sentinel de fin y el LRC): PAN, separador de campo (D), fecha de expiración (AAMM), código de servicio, datos discrecionales y F relleno opcional.
par	Referencia de cuenta de pago (PAR), si la proporciona la red de pago.
expirationDate	Fecha de expiración de la tarjeta.
cryptogramDataType	Formato del criptograma devuelto (UCAF o DE55).

Maneja los errores

Si generateRemotePayment() lanza un error, considere que el pago ha fallado. Restablezca el estado de su interfaz. Guíe al usuario final hacia la siguiente mejor acción.

Error	Descripción
deviceEnvironmentUnsafe	El dispositivo no cumple los requisitos de seguridad.
sessionInProgress	Otra sesión de pago aún se está ejecutando.
invalidInputData	Uno o más campos en RemotePaymentInputData faltan o tienen un formato incorrecto.
noPaymentKeys	No hay claves de pago disponibles para la transacción.
cardNotSupported	La tarjeta digital no admite el pago remoto DSRP.
cardNotActive	La tarjeta digital no está activa.
noDefaultCard	No se ha configurado ninguna tarjeta predeterminada.
clientError	El flujo de pago remoto falló debido a un error del lado del cliente (por ejemplo, un problema de red).
authenticationKeyInvalidated	Se deshabilitó el código de acceso del dispositivo y el almacenamiento seguro se borró.
biometricNotEnrolled	La biometría no está disponible o no está registrada.

Cada error puede incluir un mensaje que explique el fallo. Úselo para la solución de problemas y el diagnóstico de soporte.

NFC Wallet SDK borra automáticamente las credenciales almacenadas cuando authenticationKeyInvalidated ocurre (por ejemplo, después de restablecer el código de acceso o de un cambio de seguridad).

Su aplicación debe guiar al usuario final durante el proceso de re-registro.

Ejemplo completo de implementación

Use esta muestra de código para entender cómo encajan los pasos anteriores.

func generateDSRP(digitalCard: DigitalCard?) async {
    do {
        let remotePaymentSession = RemotePaymentSession()

        let amount = "000000500030"      // 5000.30 en unidades menores, rellenado con ceros a la izquierda hasta 12
        let currencyCode = "978"         // numérico ISO 4217 (EUR)
        let countryCode = "840"          // numérico ISO 3166-1 (ejemplo de US)
        let unpredictableNumber = "12345"

        let input = RemotePaymentSession.RemotePaymentInputData(
            amount: amount,
            currencyCode: currencyCode,
            transactionType: .purchase,
            unpredictableNumber: unpredictableNumber,
            countryCode: countryCode,
            cryptogramType: .de55
        )

        if let digitalCard {
            _ = try await remotePaymentSession.generateRemotePayment(
                withDigitalCardID: digitalCard.digitalCardID,
                remotePaymentInputData: input,
                userPrompt: "Autenticar"
            )
        } else {
            // Use la tarjeta digital predeterminada.
            _ = try await remotePaymentSession.generateRemotePayment(
                withDigitalCardID: nil,
                remotePaymentInputData: input,
                userPrompt: "Autenticar"
            )
        }
    } catch {
        guard let err = error as? RemotePaymentSession.Error else {
            return
        }

        switch err {
        case .deviceEnvironmentUnsafe:
            break
        case .sessionInProgress:
            break
        case .invalidInputData:
            break
        case .authenticationKeyInvalidated:
            break
        case .biometricNotEnrolled:
            break
        default:
            break
        }
    }
}