> For the complete documentation index, see [llms.txt](https://docs.payments.thalescloud.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payments.thalescloud.io/nfc-wallet-sdk-ios/es/additional-features/customize-ppse.md).

# 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.

{% hint style="info" %}
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**.
{% endhint %}

## 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.

{% hint style="warning" %}
El SDK valida automáticamente la plantilla PPSE cuando llamas a `DigitalCard.setCustomPPSE`.

Consulta [Reglas de validación](#validation-rules).
{% endhint %}

### 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.

```swift
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.

```swift
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.

```swift
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.

```swift
/// 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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.payments.thalescloud.io/nfc-wallet-sdk-ios/es/additional-features/customize-ppse.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.