Personalizar PPSE

Descripción general

Según se define en EMV Book B, el PPSE (Proximity Payment System Environment) es el punto de entrada para los pagos sin contacto. Cada tarjeta digital tiene su propio PPSE, definido en el perfil del token. Contiene la lista de identificadores de aplicación (AID) compatibles, con las etiquetas de aplicación y prioridades correspondientes.

NFC Wallet SDK proporciona API de gestión de PPSE. Permite que tu aplicación de billetera digital:

• Obtén el PPSE (PPSE predeterminado definido en el perfil de la tarjeta digital).
• Obtén el PPSE auxiliar (PPSE definido en el perfil auxiliar de la tarjeta digital para tarjetas de doble marca).
• Personaliza un nuevo PPSE (PPSE personalizado).
• Obtén o restablece el PPSE personalizado.

NFC Wallet SDK utiliza el PPSE personalizado cuando está definido para una transacción sin contacto.

Usar API de gestión de PPSE para aplicar tu política en un programa de billetera digital de doble marca.

SDK de NFC Wallet utiliza solo el PPSE o el PPSE personalizado. No utiliza el PPSE auxiliar.

Integración del SDK

El API de gestión de PPSE incluye el PPSEFCITemplate clase y estas DigitalCard operaciones:

• DigitalCard.ppse: Obtiene el PPSE predeterminado definido en el perfil del token.
• DigitalCard.auxiliaryPPSE: Obtiene el PPSE definido en el perfil auxiliar de la tarjeta digital (tarjetas de doble marca).
• DigitalCard.customPPSE: Obtiene el PPSE personalizado. Devuelve nil si no está definido.
• DigitalCard.setCustomPPSE: Establece un PPSE personalizado. Pasa nil para borrarlo.

El SDK valida automáticamente la plantilla PPSE cuando llamas a DigitalCard.setCustomPPSE.

Consulta Reglas de validación.

Creación de PPSE personalizado

Crea un PPSE personalizado con PPSEFCITemplate de una de estas maneras:

• Usa una plantilla de PPSE existente.
• Usa bytes de PPSE sin procesar.
• Constrúyelo desde cero.

Método 1: Crear PPSE a partir de una plantilla existente

Usa este enfoque cuando quieras partir del PPSE de la tarjeta digital y hacer modificaciones específicas.

Cuándo usarlo:

• Quieres personalizar campos específicos del PPSE existente, como la prioridad o las etiquetas.
• Quieres conservar la estructura predeterminada del PPSE mientras realizas cambios selectivos.
• Necesitas una plantilla base para la personalización.

var fci = try await card.ppse

let visaAID = Data([0xA0, 0x00, 0x00, 0x00, 0x03, 0x10, 0x10])
let visaKernel = Data([0x03])

guard let index = fci.proprietaryTemplate.issuerDiscretionaryData.directoryEntryList.firstIndex(where: { 
    $0.applicationIdentifier == visaAID && $0.kernelIdentifier == visaKernel 
}) else {    
    return
}

let customDiscretionaryData = Data([0xDF, 0x01, 0x02, 0x11, 0x22])

// Establece una etiqueta adicional bajo la entrada del directorio
try fci.proprietaryTemplate.issuerDiscretionaryData.directoryEntryList[index].setAdditionalTag(
    value: customDiscretionaryData, 
    forKey: Data([0x73])
)
    
let transitNetworkIdentifier = Data([0x00, 0x00, 0x1A, 0x9F])
fci.proprietaryTemplate.issuerDiscretionaryData.directoryEntryList[index].asrpd = transitNetworkIdentifier

try await card.setCustomPPSE(fci)

Método 2: Crear PPSE a partir de bytes en bruto

Usa este enfoque cuando ya tengas disponibles los datos completos de la respuesta PPSE en formato BER-TLV.

Cuándo usarlo:

• Ya tienes los datos completos de la respuesta PPSE como bytes en bruto.

private let knownPPSEFCIHex =
    Data([
        0x6F, 0x6E, 0x84, 0x0E, 0x32, 0x50, 0x41, 0x59, 0x2E, 0x53, 0x59, 0x53, 0x2E, 0x44, 0x44, 0x46,
        0x30, 0x31, 0xA5, 0x5C, 0xBF, 0x0C, 0x59, 0x61, 0x2B, 0x4F, 0x07, 0xA0, 0x00, 0x00, 0x00, 0x98,
        0x08, 0x40, 0x50, 0x0B, 0x56, 0x69, 0x73, 0x61, 0x20, 0x43, 0x72, 0x65, 0x64, 0x69, 0x74, 0x87,
        0x01, 0x01, 0xBF, 0x63, 0x04, 0xDF, 0x20, 0x01, 0x00, 0x9F, 0x0A, 0x04, 0x00, 0x01, 0x01, 0x02,
        0x9F, 0x2A, 0x01, 0x03, 0x61, 0x2A, 0x4F, 0x07, 0xA0, 0x00, 0x00, 0x00, 0x03, 0x10, 0x10, 0x50,
        0x0A, 0x56, 0x69, 0x73, 0x61, 0x20, 0x44, 0x65, 0x62, 0x69, 0x74, 0x87, 0x01, 0x02, 0xBF, 0x63,
        0x04, 0xDF, 0x20, 0x01, 0x00, 0x9F, 0x0A, 0x04, 0x00, 0x01, 0x01, 0x01, 0x9F, 0x2A, 0x01, 0x03
    ])

let template = try DigitalCard.PPSEFCITemplate(data: knownPPSEFCIHex)

try await card.setCustomPPSE(template)

Método 3: Crear PPSE desde cero

Usa este enfoque cuando necesites construir una estructura PPSE mediante programación definiendo cada componente individualmente.

Cuándo usarlo:

• Estás creando datos PPSE sin datos de bytes existentes.
• Necesitas definir entradas de directorio, AID, etiquetas y otros componentes del PPSE mediante programación.
• Quieres una construcción segura de tipos con validación en tiempo de compilación.
• Prefieres objetos estructurados en lugar de bytes en bruto.

DigitalCard expone la respuesta PPSE como PPSEFCITemplate. También puedes construir tu propio PPSEFCITemplate. El siguiente ejemplo muestra cómo.

let dfName = Data([
    0x32, 0x50, 0x41, 0x59, 0x2E, 0x53, 0x59, 0x53, 0x2E, 0x44, 0x44, 0x46, 0x30, 0x31
])

let entry = try DigitalCard.DirectoryEntry(
    applicationIdentifier: Data([0xA0, 0x00, 0x00, 0x00, 0x98, 0x08, 0x40]),
    label: Data([0x56, 0x69, 0x73, 0x61, 0x20, 0x43, 0x72, 0x65, 0x64, 0x69, 0x74]),
    kernelIdentifier: Data([0x03]),
    asrpd: Data([0x00, 0x01, 0x01, 0x02]),
    priority: Data([0x01]),
    additionalTags: [Data([0xBF, 0x63]): Data([0xDF, 0x20, 0x01, 0x00])],
    lockStatus: .unlocked
)

let idd = try DigitalCard.FCIIssuerDiscretionaryData(
    directoryEntryList: entries,
    additionalTags: bf0cAdditionalTags
)

let prop = try DigitalCard.FCIProprietaryTemplate(issuerDiscretionaryData: idd)

let template = try DigitalCard.PPSEFCITemplate(dfName: dfName, proprietaryTemplate: prop)

try await card.setCustomPPSE(template)

Borrar un PPSE personalizado

Pasa nil para eliminar el PPSE personalizado y restaurar la respuesta PPSE predeterminada.

/// 1. Recupera el PPSE personalizado actual (si lo hay)
if let currentPPSE = try? await card.customPPSE {
    print("\(currentPPSE) PPSE está activo.")
}

// 2. Elimina por completo el PPSE actual (vuelve al PPSE configurado de fábrica)
try await card.setCustomPPSE(nil)

Reglas de validación

NFC Wallet SDK valida el PPSE personalizado cuando llamas a DigitalCard.setCustomPPSE. Se asegura de que el PPSE personalizado cumpla los requisitos EMV y la codificación BER-TLV.

Límites de tamaño

• La carga útil BER-TLV serializada debe tener 256 bytes o menos.
• Las claves de etiquetas personalizadas dentro de BF0C o 61 no deben superar los 2 bytes.

Etiquetas requeridas

Tu PPSEFCITemplate debe incluir:

1. DF Name — etiqueta 84
2. Al menos una entrada de directorio — etiqueta 61 dentro de BF0C
3. Un identificador de aplicación en cada entrada de directorio — etiqueta 4F

Si la validación falla, el SDK lanza DigitialCard.Error.invaldPPSE(_:) error

Restricciones de bloqueo de AID

Bloquear un AID con LockStatus.locked solo se admite para tarjetas Visa de una sola marca.

Si estableces LockStatus.locked para una tarjeta no compatible, el SDK lanza DigitialCard.Error.clientError(_:) error