Understand HCEImage JSON files

The shared envelope

Both document types use the .hceimage.json suffix and four top-level fields. Applications check the contents, not just the filename.

The envelope schema number does not describe the contents of payload. A consumer must check the expected format and kind, then validate the payload under its own schema. The envelope does not authenticate a file or guarantee that its data is safe.

Field types matter: format and kind must be JSON strings, schemaVersion must be an integer number rather than a quoted number, and payload must be a JSON object. Missing, null or incorrectly typed required fields are rejected. Additional envelope fields are ignored, but the application still validates its specific payload.

Card-profile definition

HCE Test Tool imports a native, reusable synthetic card profile. Its envelope uses format: com.hceimage.definition and kind: card-profile. The profile schema is in payload.schemaVersion.

{
  "format": "com.hceimage.definition",
  "schemaVersion": 1,
  "kind": "card-profile",
  "payload": {
    "schemaVersion": 2,
    "id": "example-profile",
    "name": "Example profile"
  }
}

Structure illustration only: this omits required profile fields and cannot be imported as-is.

A complete payload needs at least one application and one APDU rule. Each applications[] entry has an aid, optional label/PAN/DOL and CVM settings, and an optional crypto group. The supported dynamic cryptogram groups identify their algorithm and synthetic test keys; optional three-byte KCV values are checked against the corresponding keys. Empty or partial security-data groups are not silently completed from other profiles.

Each apduRules[] entry gives an ID, a command matcher (request), a fixed or templated response, and an outcome. expectedFlow[] refers to those IDs. testScenarios[] may describe transaction amount conditions, expected CVM, a Test PIN and terminal setup, but those instructions do not execute a transaction. In-app import accepts supported Visa, Mastercard and American Express profiles only and checks the primary AID, brand and cryptogram algorithm together.

1. Prepare a complete UTF-8 native definition of at most 1 MB with synthetic test values only. Start with a downloadable example or use a bundled profile as a structural reference.
2. In HCE Test Tool, open Card profiles → Import and select the file.
3. Review the preview, warnings and Profile ID, then confirm. Invalid structure, unsupported brands or duplicate IDs block import.
4. Select the imported profile in the Emulator and review its Test guidance before starting a controlled NFC test.

Legacy per-card cryptography

Payload schema 2 adds optional applications[].legacyCrypto for Visa MSD and Mastercard MSI. This group is separate from EMV crypto; the two groups cannot coexist in one application. Its algorithm must match the brand and a MAGSTRIPE_CONTACTLESS flow. Schema-1 profiles cannot contain this group.

"legacyCrypto": {
  "algorithm": "VISA_MSD_DCVV",
  "testCardKey": "0123456789ABCDEFFEDCBA9876543210",
  "testCardKeyKcv": "08D7B4"
}

Excerpt for a complete Visa MSD application, not a standalone import. For Mastercard MSI use MASTERCARD_MSI_CVC3. The public demonstration key provides no secrecy.

testCardKey is a mandatory personalized 16-byte, two-key TDES synthetic card key, not an issuer master key. Optional testCardKeyKcv is six hexadecimal digits and must match the first three bytes of TDES encryption of a zero block. Import checks the key, brand, PAN/track consistency and required command inputs; an empty or incomplete group is rejected.

Visa MSD generates three decimal dCVV digits and uses the rightmost four decimal ATC digits. Mastercard MSI generates binary Track 1/2 CVC3 from the track templates read in that transaction, the UDOL unpredictable number and binary ATC; the reader inserts decimal results into its tracks. Terminal and test-host configurations must support the selected flow and matching synthetic keys.

In Test security data, leave the controls unchanged for profile defaults, enable Custom legacy cryptography key for a complete temporary card-key replacement, or use Fixed legacy verification results for deliberate test values. Custom-key and fixed-result modes are mutually exclusive. Fields are masked; summaries expose KCVs, not keys. Older profiles without legacyCrypto keep scripted results.

American Express AEIPS uses its existing crypto MK-AC group for CVN 01 EMV and CVN 02 magstripe. The selected GPO AIP and returned CDOL1 determine the branch; the response IAD reports the same CVN and CVR used in cryptogram generation. Do not add a Visa/MC legacy-key group to an Amex profile. These are synthetic test implementations, not real wallet provisioning or certification.

Downloadable card-profile examples

These complete native profiles include the application data, PAN and Track 2, DOL inputs, APDU rules and synthetic security defaults needed for contactless online test flows. They are adapted from the bundled Visa, Mastercard and American Express profiles rather than minimal label-only scripts.

Import and test on a terminal

1. Download a JSON file to your Android device. In HCE Test Tool, choose Card profiles → Import, select it, review the metadata and confirm. Each example has a separate Profile ID from the bundled catalog. Downloads use envelope schema 1 and payload schema 2.
2. Select the imported example in the Emulator and open its Test guidance. Start with a small purchase below the test terminal's contactless CVM limit; then test above the limit for online PIN. The Visa example's Test PIN is 123412; Mastercard and Amex use 1234. HCE Test Tool does not verify the PIN: the configured test host determines the outcome.
3. Enable the matching brand and AID on an authorized test terminal. Configure its test card/BIN table for the example PAN and, if it verifies cryptograms, configure the host simulator with the demonstration keys and matching derivation settings.
4. Start emulation before presenting the phone. The terminal builds PDOL/CDOL data and chooses its own command flow; inspect the APDU timeline and the terminal result separately.

These profiles support meaningful terminal read flows, but are not certified scheme test cases or a guarantee of compatibility with every kernel. Card/BIN routing, CVM settings, offline-authentication configuration and host processing remain outside the emulator. In particular, an Amex UNKNOWN_CARD rejection can be a payment-application configuration issue even after a completed APDU exchange. A completed HCE session is not proof of payment approval.

What each example demonstrates

Required, optional and conditional fields

The table describes the native profile schema, not just the values in these examples. Optional fields may become necessary for the processing path you choose.

Public test keys and safe editing

"testMasterKeyAc": "0123456789ABCDEFFEDCBA9876543210",
"testMasterKeyAcKcv": "08D7B4"

Excerpt inside the crypto group, not a standalone import file. This intentionally public demonstration key provides no secrecy.

The Mastercard dynamic-number key is 00112233445566778899AABBCCDDEEFF with KCV FB0975. The embedded defaults persist with the imported file; Emulator overrides are separate temporary values. Never substitute production keys or real cardholder data.

• To keep a second edited copy, change payload.id to a new lowercase, hyphenated Profile ID. Changing the filename alone does not avoid duplicate-ID rejection.
• When changing a PAN, update every associated PAN/Track 2 value and keep the check digit valid. Signed test certificates can also bind the PAN: do not independently edit Mastercard's PAN, RSA material or certificates without rebuilding the dependent fixture.
• When changing an AID, label or EMV value, also update related response TLVs and lengths. Changing application metadata does not rewrite APDU responses automatically.
• When changing a key, recompute its supplied KCV and update the test host configuration. Keeping an old KCV deliberately causes import rejection.

EMV analysis trace

EMV Card Analyzer exports a captured diagnostic result for later inspection. Its envelope uses format: com.hceimage.diagnostic and kind: emv-analysis. The trace schema is in payload.schemaVersion; producer.versionName records the creating app release, not the document schema.

{
  "format": "com.hceimage.diagnostic",
  "schemaVersion": 1,
  "kind": "emv-analysis",
  "payload": {
    "schemaVersion": 1,
    "evidence": "Redacted",
    "producer": {
      "applicationId": "com.hceimage.emvcardanalyzer",
      "versionName": "<producer-app-version>"
    }
  }
}

Structure illustration only: an importable trace also needs the result, timing, APDU exchanges and application data.

Export uses payload.schemaVersion. Import also accepts the legacy field payload.payloadVersion. If both fields are supplied, both must be valid and equal; conflicting values are rejected. Use the canonical field for new traces. An older app that only understands the legacy field may need an update before importing a new export.

Each exchanges[] item contains APDU command hex and an optional response, payment-scheme/AID context, optional PDOL/CDOL1 data, a label, optional local errors and optional durationMillis. Each applications[] item records the discovered AID, labels, scheme, processing/read status and optional facts[]. A fact carries its tag, decoded value and sourceApdus indices into the exchange list. The import checks final result state, timestamps, APDU framing and bounded collection sizes before it can be saved.

1. Open a saved analysis in History → Export → Trace, choose Full evidence or Redacted, then save or share deliberately.
2. On another installation, choose History → Import. Inspect the preview before choosing Save to history; Back discards it.

Compatibility boundary

The shared envelope stays at schema 1. Card-profile payload schema 2 and EMV analysis payload schema 1 are independent: upgrading a profile does not upgrade a trace or the envelope. The trace importer accepts legacy payload.payloadVersion as an alias, but HCE card-profile import uses payload.schemaVersion only.

These files cannot be exchanged between the two importers: HCE Test Tool does not import analysis traces, and EMV Card Analyzer does not import card profiles. Renaming a file does not convert it. A profile definition is an input for controlled emulation; an analysis trace is an output from a recorded NFC read. Neither file is a payment credential, approval record or certification result.