Test contactless terminal flows with synthetic card profiles

Before starting

• Use an Android device with NFC host card emulation support and NFC enabled.
• Use only an authorized external contactless reader or payment terminal configured for testing.
• Keep the test host and terminal configuration available when interpreting authorization or kernel-specific behavior.

Run a test

1. Choose the payment brand and a card profile that matches the scenario you want to exercise.
2. Review the profile summary and open its test guidance for profile-specific expectations.
3. If the authorized test host requires different test credentials, configure supported values under Test security data. Profile defaults remain unchanged when no override is applied.
4. Start emulation and present the Android device to the reader or terminal.
5. Keep the device in position until the application reports a completed, failed or interrupted outcome.

Inspect the exchange

The live timeline records commands and responses as the terminal communicates with the selected profile. Open an entry to inspect the raw APDU together with contextual command headers, status words, BER-TLV data, DOL values and recognized payment-scheme tags. Command/response timings and session duration help locate delays; they do not measure the terminal's complete payment processing time.

The result view compares the observed exchange with the expected profile flow. A failed or interrupted result is diagnostic context, not by itself proof of a terminal defect: reader configuration, terminal kernels and processing outside the emulator can affect the outcome.

Use history and reports

Completed, failed and interrupted attempts are kept locally. History filters help isolate an outcome, while session details preserve validation checks, the APDU timeline and optional test notes. Delete a single record or clear history when it is no longer needed. Diagnostic reports can be saved or shared in Markdown, HTML or PDF when an integration result needs to be reviewed outside the application.

Choose Full evidence for captured values or Redacted to retain structural diagnostics while omitting card-derived values and notes. Redacted is not a guarantee of anonymity: review the retained diagnostic context before sharing either form. Single-record deletion offers Undo. Settings controls history retention, appearance, Logcat detail, result vibration and emulation timeout. High-detail logs and Full evidence reports can contain synthetic card data; review them before sharing.

Keep results while moving between screens

Switching tabs, backgrounding the app or rotating the screen stops NFC emulation without restarting it automatically. The live result stays available while the app process remains alive. Start replaces it; selecting a different brand or profile clears it. Saved History is independent of this temporary workspace. Applied security overrides survive tabs and rotation, but an unfinished editor draft is discarded when its screen is recreated.

Handle test security data carefully

Only explicitly authorized test values belong in Test security data. Values entered in the Emulator are masked by default, validated before use and retained in memory only. Apply validates and activates the draft; Cancel discards unapplied edits. Reset asks for confirmation, then immediately removes that profile’s overrides and draft, restoring its own defaults or synthetic engine defaults when none are supplied. It never changes the saved profile.

Temporary overrides clear from the next-run selection after the next emulation with that profile starts unless you choose Keep until the app is closed. The active session still uses its captured values; its result and history retain the source used for that session. The Emulator security card describes the next run when no session is active. Overrides are not written to card profiles, history, reports, logs, clipboard output or backups; generated test APDU responses can appear in history and reports. Separately, synthetic defaults included in an imported profile persist with that profile file. Never enter production issuer keys.

Import a card profile

Choose Card profiles → Import to open a native .hceimage.json definition. Review the preview before saving it. The file identifies itself as com.hceimage.definition / card-profile; the app validates its profile schema, unique Profile ID, supported brand, AIDs, APDU behavior and supplied test security data. Built-in profiles cannot be replaced or deleted.

Payload schema version identifies payload.schemaVersion in profile detail and import preview. Current definitions use payload schema 2 inside envelope schema 1; schema-1 payloads remain readable. Schema 2 adds optional Visa MSD/Mastercard MSI per-card test keys. The legacy-security reference explains key roles, KCV checks and temporary overrides.

Imported and Created profiles appear alongside Built-in profiles and can be isolated with the Profile source filter. Swipe a user-owned card or use Delete in its detail; both routes provide Undo. Deleting a profile does not delete its existing session history; repeating a saved session requires an available profile with the same Profile ID. Profile-default synthetic test security data persists with that private profile. Values you apply later in the Emulator are temporary overrides and do not change the profile file. Keep original import files for re-import after reinstalling or changing devices.

Copy and manage your profiles

Profile source uses the same labels on cards, in filters and in detail: Built-in, Imported and Created. These library labels describe how the app obtained a profile; they are separate from the optional provenance metadata inside its JSON.

1. Open an existing profile in Card profiles and choose Copy.
2. Enter a name and a unique Profile ID, review the preview and choose Create. Cancel leaves the original unchanged.
3. Select the new Created profile in the Emulator when you want to test it.

Functional data and profile security defaults remain intact. The copy replaces provenance with "source": { "format": "CUSTOM" } and does not copy temporary Emulator overrides. Copy edits identity metadata only; it does not edit PAN, AID, tracks or certificates. Built-in profiles are protected; Imported and Created profiles can be deleted with Undo. Native profile export and an editor for emulation values are not currently available.