Customize PPSE

Overview

As defined in EMV Book B, the PPSE (Proximity Payment System Environment) is the entry point for contactless payments. Each digital card has its own PPSE, defined in the token profile. It contains the list of supported application identifiers (AIDs), with the corresponding application labels and priorities.

NFC Wallet SDK provides PPSE Management API. It allows your digital wallet application to:

• Get the PPSE (default PPSE defined in the digital card profile).
• Get the auxiliary PPSE (PPSE define in the auxiliary digital card profile for co-badged cards).
• Customize a new PPSE (custom PPSE).
• Get or reset the custom PPSE.

NFC Wallet SDK uses the custom PPSE when it is defined for a contactless transaction.

Use PPSE Management API to apply your policy in a co-badged digital wallet program.

NFC Wallet SDK uses only the PPSE or the custom PPSE. It does not use the auxiliary PPSE.

SDK integration

The PPSE Management API includes the PPSEFCITemplate class and these DigitalCard operations:

• DigitalCard.ppse: Gets the default PPSE defined in the token profile.
• DigitalCard.auxiliaryPPSE: Gets the PPSE defined in the auxiliary digital card profile (co-badged cards).
• DigitalCard.customPPSE: Gets the custom PPSE. Returns nil if it is not defined.
• DigitalCard.setCustomPPSE: Sets a custom PPSE. Pass nil to clear it.

The SDK automatically validates the PPSE template when you call DigitalCard.setCustomPPSE.

See Validation rules.

Building custom PPSE

Build a custom PPSE with PPSEFCITemplate in one of these ways:

• Use an existing PPSE template.
• Use raw PPSE bytes.
• Build it from scratch.

Method 1: Build PPSE from an existing template

Use this approach when you want to start with the digital card PPSE and make targeted modifications.

When to use:

• You want to customize specific fields in the existing PPSE, such as priority or tags.
• You want to preserve the default PPSE structure while making selective changes.
• You need a base template for customization.

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])

// Set additional tag under directory entry
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)

Method 2: Build PPSE from raw bytes

Use this approach when you have the complete PPSE response data already available in BER-TLV format.

When to use:

• You already have the full PPSE response data as raw bytes.

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)

Method 3: Build PPSE from scratch

Use this approach when you need to construct a PPSE structure programmatically by defining each component individually.

When to use:

• You are building PPSE data without existing byte data.
• You need to define directory entries, AIDs, labels, and other PPSE components programmatically.
• You want type-safe construction with compile-time validation.
• You prefer structured objects over raw bytes.

DigitalCard exposes the PPSE response as PPSEFCITemplate. You can also build your own PPSEFCITemplate. The following example shows how.

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)

Clear a custom PPSE

Pass nil to remove the custom PPSE and restore the default PPSE response.

/// 1. Retrieve current custom PPSE (if any)
if let currentPPSE = try? await card.customPPSE {
    print("\(currentPPSE) PPSE is active.")
}

// 2. Remove the current PPSE completely (revert to factory set PPSE)
try await card.setCustomPPSE(nil)

Validation rules

NFC Wallet SDK validates the custom PPSE when you call DigitalCard.setCustomPPSE. It ensures that the custom PPSE follows EMV requirements and BER-TLV encoding.

Size limits

• The serialized BER-TLV payload must be 256 bytes or less.
• Custom tag keys inside BF0C or 61 must not exceed 2 bytes.

Required tags

Your PPSEFCITemplate must include:

1. DF Name — Tag 84
2. At least one Directory Entry — Tag 61 inside BF0C
3. An Application Identifier in each Directory Entry — Tag 4F

If validation fails, the SDK throws DigitialCard.Error.invaldPPSE(_:) error

AID lock restrictions

Locking an AID with LockStatus.locked is supported only for mono-badged Visa cards.

If you set LockStatus.locked for an unsupported card, the SDK throws DigitialCard.Error.clientError(_:) error