Expose application expiration date (EMV tag 5F24)

Adds ExpiryDate(year, month) with isExpired(), displayMmYy(),
displayMmYyyy(). Wired into CardData.Success and the sample app's
SuccessContent (red label when expired). GET DATA 5F24 fallback for
cards that omit the tag from AFL records. Bumps library to 1.1.5.

Also adds Compose @Preview composables for every screen state
(idle, scanning, reading, success variants, error, NFC disabled,
NFC not available) and refreshes the physical-card screenshot.

Author: armenasatryan

NFC_CARD_READER_README.md

@@ -135,10 +135,11 @@ Tests cover:
 ## Known Limitations
 
 1. **Some cards don't expose PAN via NFC** - security feature on some issuers
-2. **CVV/expiry not readable** - intentionally excluded for security
-3. **Cardholder name often unavailable** via contactless
-4. **Virtual cards** (Google Pay, Apple Pay) - different protocol
-5. **Chip-only cards** - no contactless antenna
+2. **CVV not readable** - not present in contactless EMV response
+3. **Expiry (`5F24`)** - exposed by most physical cards; many wallets strip it
+4. **Cardholder name often unavailable** via contactless
+5. **Virtual cards** (Google Pay, Apple Pay) - different protocol
+6. **Chip-only cards** - no contactless antenna
 
 ## Security Notes
 

README.md

@@ -45,6 +45,7 @@
 - **Cardholder name** from EMV tag `5F20` (when exposed)
 - **AID + friendly name** via `AidLabels` (Visa Credit/Debit, Mastercard, Amex, …)
 - **Offline PIN tries remaining** via tag `9F17`
+- **Card expiry (`5F24`)** with `isExpired()` helper and `MM/YY` / `MM/YYYY` display
 - **Multi-brand**: Visa, Mastercard, American Express, Discover, UnionPay, JCB, Mir
 - **Payment Source Detection**: physical card vs Google Wallet, Apple Pay, Samsung Pay, Garmin Pay, Fitbit Pay
 - **Form Factor (`9F6E`) + Token Requestor ID (`9F19`) parsing** for wallet identification
@@ -98,11 +99,11 @@ Add the dependency to your app's `build.gradle.kts`:
 
 ```kotlin
 dependencies {
-    implementation("com.github.Arm63:BankCardNFCReader:1.1.4")
+    implementation("com.github.Arm63:BankCardNFCReader:1.1.5")
 }
 ```
 
-> Latest version is shown on the JitPack badge above. Replace `1.1.4` if a newer release is published.
+> Latest version is shown on the JitPack badge above. Replace `1.1.5` if a newer release is published.
 
 ## Quick Start (View)
 
@@ -142,6 +143,8 @@ class MainActivity : AppCompatActivity() {
                     val owner = result.maskedOwnerName()    // "A**** A****" or null
                     val aid = result.aidDisplayName         // "Visa Credit/Debit" or null
                     val pinTries = result.pinTriesRemaining // 3 or null
+                    val expiry = result.expiryDate?.displayMmYy() // "12/27" or null
+                    val expired = result.expiryDate?.isExpired() == true
 
                     if (isWallet) showWalletCard(cardNumber, source.displayName)
                     else showPhysicalCard(cardNumber, cardType.displayName)
@@ -191,6 +194,10 @@ fun CardReaderScreen() {
                 result.maskedOwnerName()?.let { Text(it, fontSize = 14.sp) }
                 result.aidDisplayName?.let { Text(it, fontSize = 12.sp, color = Color.Gray) }
                 result.pinTriesRemaining?.let { Text("PIN tries left: $it", fontSize = 12.sp) }
+                result.expiryDate?.let {
+                    val color = if (it.isExpired()) Color.Red else Color.Unspecified
+                    Text("Expires: ${it.displayMmYy()}", fontSize = 12.sp, color = color)
+                }
                 if (result.isTokenizedWallet) Text("Tokenized (DPAN)", fontSize = 12.sp, color = Color.Gray)
             }
             is CardData.Error -> Text("❌ ${result.message}", color = Color.Red)
@@ -216,6 +223,7 @@ fun CardReaderScreen() {
 | `aid` | `String?` | `"A0000000031010"` | Selected AID (tag `4F`), uppercase hex. |
 | `aidDisplayName` | `String?` | `"Visa Credit/Debit"` | Friendly label resolved by `AidLabels`. `null` if unknown. |
 | `pinTriesRemaining` | `Int?` | `3` | Offline PIN Try Counter (tag **`9F17`**). `null` if not exposed. |
+| `expiryDate` | `ExpiryDate?` | `ExpiryDate(2027, 12)` | Application Expiration Date (tag **`5F24`**). `null` if card omits it. |
 | `isTokenizedWallet` | `Boolean` | `true` | `paymentSource.isDigitalWallet`. |
 | `isPhysicalCard` | `Boolean` | `false` | `paymentSource.isPhysicalCard`. |
 
@@ -225,6 +233,16 @@ fun CardReaderScreen() {
 |---|---|---|
 | `maskedOwnerName()` | `String?` | Privacy-safe display form of `cardholderName`, e.g. `"A**** A****"`. Splits on whitespace and `/`, keeps first letter of each token. Returns `null` when name is missing or blank. |
 
+### `ExpiryDate`
+
+```kotlin
+data class ExpiryDate(val year: Int, val month: Int) {
+    fun displayMmYy(): String        // "12/27"
+    fun displayMmYyyy(): String      // "12/2027"
+    fun isExpired(now: Calendar = Calendar.getInstance()): Boolean
+}
+```
+
 ### `PaymentSource` enum
 
 ```kotlin
@@ -466,14 +484,19 @@ No. NFC card emulation between two real devices is required for wallet testing.
 ## Roadmap
 
 - [ ] Track 2 equivalent data parsing (`57`)
-- [ ] Application Expiration Date (`5F24`) exposure
 - [ ] Application Currency Code (`9F42`)
 - [ ] Maven Central publishing in addition to JitPack
 - [ ] CI release workflow with GitHub Actions
 
 ## Changelog
 
-### v1.1.4 (Current)
+### v1.1.5 (Current)
+- Expose **Application Expiration Date** (EMV tag `5F24`) as `expiryDate: ExpiryDate?` on `CardData.Success`
+- `ExpiryDate.isExpired()`, `displayMmYy()`, `displayMmYyyy()` helpers
+- GET DATA `5F24` fallback when AFL records omit the tag
+- Sample app shows expiry on detected card (red when expired)
+
+### v1.1.4
 - Read **cardholder name** from EMV tag `5F20` and expose `cardholderName` + `maskedOwnerName()` on `CardData.Success`
 - Show **remaining offline PIN tries** (`9F17`) via `pinTriesRemaining`
 - Expose selected **AID** (`4F`) and friendly name via `aid` + `aidDisplayName` (backed by `AidLabels`)
@@ -532,4 +555,4 @@ MIT License - Copyright (c) 2025 Armen Asatryan
 
 ---
 
-**Keywords**: android nfc credit card reader library, read PAN from contactless card kotlin, EMV nfc android library, google wallet detection android, apple pay detection android, samsung pay nfc detection, dpan vs pan android, kotlin coroutines nfc reader, emv tag 5f20 cardholder name, emv tag 9f17 pin try counter, emv tag 9f6e form factor indicator, emv tag 9f19 token requestor id, visa mastercard nfc kotlin, jitpack android library
+**Keywords**: android nfc credit card reader library, read PAN from contactless card kotlin, EMV nfc android library, google wallet detection android, apple pay detection android, samsung pay nfc detection, dpan vs pan android, kotlin coroutines nfc reader, emv tag 5f20 cardholder name, emv tag 9f17 pin try counter, emv tag 5f24 expiry, emv tag 9f6e form factor indicator, emv tag 9f19 token requestor id, visa mastercard nfc kotlin, jitpack android library

android-bank-card-reader/build.gradle.kts

@@ -52,7 +52,7 @@ afterEvaluate {
 
                 groupId = "com.github.Arm63"
                 artifactId = "BankCardNFCReader"
-                version = "1.1.4"
+                version = "1.1.5"
 
                 pom {
                     name.set("Bank Card NFC Reader")

android-bank-card-reader/src/main/java/com/emvreader/nfc/CardData.kt

@@ -1,5 +1,31 @@
 package com.emvreader.nfc
 
+import java.util.Calendar
+
+/**
+ * Card application expiration date from EMV tag `5F24`.
+ *
+ * @property year Four-digit Gregorian year (e.g. 2027).
+ * @property month Month, 1..12.
+ */
+data class ExpiryDate(val year: Int, val month: Int) {
+    /** Display as `MM/YY` (e.g. `12/27`). */
+    fun displayMmYy(): String = "%02d/%02d".format(month, year % 100)
+
+    /** Display as `MM/YYYY` (e.g. `12/2027`). */
+    fun displayMmYyyy(): String = "%02d/%04d".format(month, year)
+
+    /**
+     * True if [now] is after the expiry month. EMV cards expire at end of the printed month,
+     * so a card with expiry `12/2025` is valid through 2025-12-31.
+     */
+    fun isExpired(now: Calendar = Calendar.getInstance()): Boolean {
+        val nowYear = now.get(Calendar.YEAR)
+        val nowMonth = now.get(Calendar.MONTH) + 1
+        return nowYear > year || (nowYear == year && nowMonth > month)
+    }
+}
+
 /**
  * Human-readable labels for common RID + AID prefixes (hex, uppercase).
  */
@@ -42,6 +68,7 @@ sealed class CardData {
      * @property cardholderName Cardholder name from EMV tag 5F20 when present. Often **null** on contactless for privacy.
      * @property aid Selected payment application identifier (tag `4F`), uppercase hex without spaces.
      * @property pinTriesRemaining Offline PIN tries left (tag `9F17`) when the card exposes it; often **null** on contactless.
+     * @property expiryDate Application expiration date from tag `5F24` (`MM/YY`). **null** when card omits it.
      */
     data class Success(
         val pan: String,
@@ -52,7 +79,8 @@ sealed class CardData {
         val sourceDetectionResult: CardSourceDetector.DetectionResult? = null,
         val cardholderName: String? = null,
         val aid: String? = null,
-        val pinTriesRemaining: Int? = null
+        val pinTriesRemaining: Int? = null,
+        val expiryDate: ExpiryDate? = null
     ) : CardData() {
 
         /**

android-bank-card-reader/src/main/java/com/emvreader/nfc/EmvCardReader.kt

@@ -76,6 +76,13 @@ class EmvCardReader(
         collectedTlvData[TlvParser.TAG_TRACK1]?.value?.let { v ->
             emvLog("[$phase] 56 Track1 len=${v.size} hex=${v.toHex().hexPreview()}")
         }
+        collectedTlvData[TlvParser.TAG_EXPIRY]?.value?.let { v ->
+            val parsed = TlvParser.extractExpiry(collectedTlvData)
+            emvLog(
+                "[$phase] 5F24 raw len=${v.size} hex=${v.toHex().hexPreview()} " +
+                    "parsed=${parsed?.let { "${it.year}-${"%02d".format(it.month)}" } ?: "null"}"
+            )
+        }
     }
 
     private fun logApduResult(label: String, command: ByteArray, response: ByteArray) {
@@ -130,10 +137,14 @@ class EmvCardReader(
                 emvLog("try AID=${aid.toHex()}")
                 val result = tryReadWithAid(isoDep, aid)
                 if (result is CardData.Success) {
+                    val expStr = result.expiryDate?.let {
+                        "${it.displayMmYy()} expired=${it.isExpired()}"
+                    } ?: "null"
                     emvLog(
                         "readCard: success last4=${result.pan.takeLast(4)} " +
                             "aid=${result.aid ?: "null"} " +
                             "pinTries=${result.pinTriesRemaining ?: "null"} " +
+                            "expiry=$expStr " +
                             "cardholderName=${result.cardholderName?.let { "\"$it\"" } ?: "null"}"
                     )
                     return@withContext result
@@ -288,7 +299,8 @@ class EmvCardReader(
 
         mergeCardholderFromGetData(isoDep)
         mergePinTryCounterFromGetData(isoDep)
-        logCollectedTlv("after_GET_DATA_5F20_9F17")
+        mergeExpiryFromGetData(isoDep)
+        logCollectedTlv("after_GET_DATA_5F20_9F17_5F24")
 
         foundPan?.let {
             val name = TlvParser.extractCardholderName(collectedTlvData)
@@ -407,6 +419,34 @@ class EmvCardReader(
         emvLog("GET_DATA 9F17: exhausted or unsupported")
     }
 
+    /** GET DATA for tag 5F24 (expiry); merges into [collectedTlvData] on success. */
+    private fun mergeExpiryFromGetData(isoDep: IsoDep) {
+        if (TlvParser.extractExpiry(collectedTlvData) != null) {
+            emvLog("GET_DATA 5F24: skip (already in TLV map)")
+            return
+        }
+        for (cla in intArrayOf(0x80, 0x00)) {
+            try {
+                val cmd = ApduBuilder.getData(0x5F, 0x24, cla)
+                val resp = isoDep.transceive(cmd)
+                logApduResult("GET_DATA 5F24 CLA=${"%02X".format(cla)}", cmd, resp)
+                if (!resp.isSuccess()) continue
+                val data = resp.getData()
+                if (data.isEmpty()) continue
+                val parsed = TlvParser.parse(data)
+                emvLog("GET_DATA 5F24 parsed tags=${parsed.keys.sorted().joinToString(",")}")
+                collectedTlvData.putAll(parsed)
+                if (TlvParser.extractExpiry(collectedTlvData) != null) {
+                    emvLog("GET_DATA 5F24: expiry=${TlvParser.extractExpiry(collectedTlvData)}")
+                    return
+                }
+            } catch (e: Exception) {
+                emvLog("GET_DATA 5F24 CLA=${"%02X".format(cla)} exception=${e.message}")
+            }
+        }
+        emvLog("GET_DATA 5F24: exhausted or unsupported")
+    }
+
     private fun tryGpoWithVariants(isoDep: IsoDep, pdol: ByteArray?): ByteArray {
         for ((index, ttq) in EmvConstants.TTQ_VARIANTS.withIndex()) {
             val pdolData = buildPdolData(pdol, ttq)
@@ -531,6 +571,7 @@ class EmvCardReader(
         logCollectedTlv("direct_after_scan")
         mergeCardholderFromGetData(isoDep)
         mergePinTryCounterFromGetData(isoDep)
+        mergeExpiryFromGetData(isoDep)
         logCollectedTlv("direct_after_GET_DATA")
         foundPan?.let {
             emvLog("tryDirectRecordRead success last4=${it.takeLast(4)} name=${TlvParser.extractCardholderName(collectedTlvData)}")
@@ -555,7 +596,8 @@ class EmvCardReader(
             sourceDetectionResult = detectionResult,
             cardholderName = TlvParser.extractCardholderName(collectedTlvData),
             aid = TlvParser.extractAid(collectedTlvData),
-            pinTriesRemaining = TlvParser.extractPinTryCounter(collectedTlvData)
+            pinTriesRemaining = TlvParser.extractPinTryCounter(collectedTlvData),
+            expiryDate = TlvParser.extractExpiry(collectedTlvData)
         )
     }
 }

android-bank-card-reader/src/main/java/com/emvreader/nfc/TlvParser.kt

@@ -36,6 +36,8 @@ object TlvParser {
     const val TAG_DEVICE_TYPE = "9F6D"
     /** PIN Try Counter — offline PIN attempts remaining (often via GET DATA). */
     const val TAG_PIN_TRY_COUNTER = "9F17"
+    /** Application Expiration Date — YYMMDD BCD (3 bytes). */
+    const val TAG_EXPIRY = "5F24"
 
     data class TlvData(val tag: String, val length: Int, val value: ByteArray)
 
@@ -217,6 +219,23 @@ object TlvParser {
         return v[0].toInt() and 0xFF
     }
 
+    /**
+     * Expiry from tag `5F24` (YYMMDD BCD, 3 bytes). Returns null if tag missing,
+     * malformed, or month outside 1..12.
+     *
+     * Two-digit year mapped to 2000–2099 (EMV cards use 4-digit Gregorian year minus century).
+     */
+    fun extractExpiry(tlvMap: Map<String, TlvData>): ExpiryDate? {
+        val v = tlvMap[TAG_EXPIRY]?.value ?: return null
+        if (v.size < 3) return null
+        val digits = decodeBcd(v)
+        if (digits.length < 4) return null
+        val yy = digits.substring(0, 2).toIntOrNull() ?: return null
+        val mm = digits.substring(2, 4).toIntOrNull() ?: return null
+        if (mm !in 1..12) return null
+        return ExpiryDate(year = 2000 + yy, month = mm)
+    }
+
     data class AflEntry(val sfi: Int, val firstRecord: Int, val lastRecord: Int)
 
     private fun List<Byte>.toHex(): String = joinToString("") { "%02X".format(it) }

android-bank-card-reader/src/test/java/com/emvreader/nfc/ExpiryDateTest.kt

@@ -0,0 +1,85 @@
+package com.emvreader.nfc
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import java.util.Calendar
+import java.util.GregorianCalendar
+
+class ExpiryDateTest {
+
+    private fun tlv(hex: String): Map<String, TlvParser.TlvData> = mapOf(
+        TlvParser.TAG_EXPIRY to TlvParser.TlvData(
+            tag = TlvParser.TAG_EXPIRY,
+            length = hex.length / 2,
+            value = hex.chunked(2).map { it.toInt(16).toByte() }.toByteArray()
+        )
+    )
+
+    @Test
+    fun extractExpiry_validBcd_returnsYearAndMonth() {
+        val e = TlvParser.extractExpiry(tlv("271231"))
+        assertEquals(ExpiryDate(2027, 12), e)
+    }
+
+    @Test
+    fun extractExpiry_missing_returnsNull() {
+        assertNull(TlvParser.extractExpiry(emptyMap()))
+    }
+
+    @Test
+    fun extractExpiry_shortValue_returnsNull() {
+        assertNull(TlvParser.extractExpiry(tlv("2712")))
+    }
+
+    @Test
+    fun extractExpiry_invalidMonth_returnsNull() {
+        assertNull(TlvParser.extractExpiry(tlv("271331")))
+    }
+
+    @Test
+    fun displayMmYy_padsZero() {
+        assertEquals("01/27", ExpiryDate(2027, 1).displayMmYy())
+        assertEquals("12/05", ExpiryDate(2005, 12).displayMmYy())
+    }
+
+    @Test
+    fun displayMmYyyy_full() {
+        assertEquals("03/2029", ExpiryDate(2029, 3).displayMmYyyy())
+    }
+
+    @Test
+    fun isExpired_pastMonth_true() {
+        val now = GregorianCalendar(2026, Calendar.MAY, 16)
+        assertTrue(ExpiryDate(2025, 12).isExpired(now))
+        assertTrue(ExpiryDate(2026, 4).isExpired(now))
+    }
+
+    @Test
+    fun isExpired_currentMonth_false() {
+        val now = GregorianCalendar(2026, Calendar.MAY, 16)
+        assertFalse(ExpiryDate(2026, 5).isExpired(now))
+    }
+
+    @Test
+    fun isExpired_futureMonth_false() {
+        val now = GregorianCalendar(2026, Calendar.MAY, 16)
+        assertFalse(ExpiryDate(2026, 6).isExpired(now))
+        assertFalse(ExpiryDate(2030, 1).isExpired(now))
+    }
+
+    @Test
+    fun success_expiryDate_storedOnSuccess() {
+        val s = CardData.Success(
+            pan = "4111111111111111",
+            formattedPan = "4111 1111 1111 1111",
+            maskedPan = "4111 **** **** 1111",
+            cardType = CardType.VISA,
+            expiryDate = ExpiryDate(2028, 6)
+        )
+        assertEquals(ExpiryDate(2028, 6), s.expiryDate)
+        assertEquals("06/28", s.expiryDate?.displayMmYy())
+    }
+}