Class LifeCycleId

java.lang.Object
org.jpos.iso.LifeCycleId
public final class LifeCycleId extends Object
Encodes and decodes the ISO 8583 Transaction Life Cycle Identification Data (DE-021).

DE-021 is a 19-byte constructed field that correlates related messages across a transaction's full life cycle—authorization, financial presentment, reversal, and chargeback.

Wire layout

 Bytes  Notation     Sub-field
 1       AN1 (ASCII)  Life cycle support indicator
 2–16   AN15 (ASCII)  Life cycle trace identifier
 17–18  N2 (BCD)     Life cycle transaction sequence number
 19–22  N4 (BCD)     Life cycle authentication token

jPOS TxnId integration

When jPOS originates a transaction, the trace identifier is populated from a TxnId via its base-36 TxnId.toRrn() form, right-padded with spaces to 15 characters. On inbound messages, txnId() attempts to reverse this mapping; it returns an empty Optional when the trace identifier does not represent a TxnId (e.g. when received from an external network with its own trace ID scheme).

Usage — outbound (originates authorization)

byte[] de21 = LifeCycleId.builder()
    .supportIndicator(mti)        // derives '1' for 1xx, '2' for 2xx, etc.
    .traceId(txnId)               // uses txnId.toRrn(), padded to 15 chars
    .build()
    .pack();
msg.set(new ISOBinaryField(21, de21));

Usage — outbound (financial presentment echoing prior auth)

LifeCycleId authLC = LifeCycleId.unpack(authMsg.getBytes(21));
byte[] de21 = authLC.toBuilder()
    .sequenceNumber(seq)
    .authToken(tokenFromAuthResponse)
    .build()
    .pack();

Usage — inbound (from external network)

LifeCycleId lc = LifeCycleId.unpack(msg.getBytes(21));
lc.txnId().ifPresent(t -> ctx.put("TXNID", t));
String rawTrace = lc.traceIdentifier();
See Also:

  • Field Details

  • Method Details

    • supportIndicator

      public char supportIndicator()
      Returns the life cycle support indicator character. '1' indicates the identifier was first assigned during an authorization message; '2' during a financial presentment.
      Returns:
      support indicator

    • traceIdentifier

      public String traceIdentifier()
      Returns the raw 15-character life cycle trace identifier.
      Returns:
      trace identifier

    • txnId

      public Optional<TxnId> txnId()
      Attempts to parse the trace identifier as a jPOS TxnId.

      Returns a non-empty Optional when the trimmed trace identifier was produced by TxnId.toRrn(). Returns empty for identifiers generated by other systems.

      Returns:
      optional TxnId

    • sequenceNumber

      public int sequenceNumber()
      Returns the life cycle transaction sequence number. Zero when not assigned.
      Returns:
      sequence number

    • authToken

      public int authToken()
      Returns the life cycle authentication token assigned by the card issuer. Zero when not yet assigned or when omitted by mutual agreement.
      Returns:
      authentication token

    • pack

      public byte[] pack()
      Serializes this life cycle identifier to the DE-021 wire format.
      Returns:
      19-byte wire representation

    • unpack

      public static LifeCycleId unpack(byte[] data) throws ISOException
      Deserializes DE-021 bytes into a LifeCycleId.
      Parameters:
      data - 19-byte DE-021 field content
      Returns:
      parsed life cycle identifier
      Throws:
      ISOException - when the byte array is null, empty, or too short

    • toBuilder

      public LifeCycleId.Builder toBuilder()
      Creates a new LifeCycleId.Builder pre-populated with this instance's values. Useful for constructing a financial presentment that echoes an authorization's life cycle identifier.
      Returns:
      builder initialized from this instance

    • builder

      public static LifeCycleId.Builder builder()
      Returns a new empty builder.
      Returns:
      builder

    • supportIndicatorForMTI

      public static char supportIndicatorForMTI(String mti)
      Derives the life cycle support indicator character from an ISO 8583 MTI. Returns the first digit of the MTI's class component (position 1, 0-indexed).

      Examples: "0100" → '1', "0200" → '2', "0420" → '4'.

      Parameters:
      mti - 3- or 4-character ISO 8583 MTI string
      Returns:
      support indicator character
      Throws:
      IllegalArgumentException - when the MTI is null or too short

    • toString

      public String toString()
      Overrides:
      toString in class Object