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. Returnsnilif it is not defined.DigitalCard.setCustomPPSE: Sets a custom PPSE. Passnilto 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.
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.
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.
Clear a custom PPSE
Pass nil to remove the custom PPSE and restore the default PPSE response.
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
BF0Cor61must not exceed 2 bytes.
Required tags
Your PPSEFCITemplate must include:
DF Name — Tag
84At least one Directory Entry — Tag
61insideBF0CAn 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
Last updated
Was this helpful?