HL7 Table HL70017: Transaction Type

HL70017 is the long-standing HL7-defined vocabulary that classifies what kind of financial event a billing message describes. It first appeared in HL7 v2.2 alongside the FT1 Financial Transaction segment and has remained relatively stable through v2.8.1. The table is the principal driver of FT1-6 Transaction Type on every charge, payment, adjustment, or transfer message between a patient-billing system and a downstream accounts-receivable system.

Purpose

HL70017 answers the categorical question "is this money coming in, going out, being moved, or being adjusted". The receiving accounts-receivable system uses the value to choose the correct posting routine: a PY (Payment) credits an open balance, an AJ (Adjustment) modifies a previously posted charge, a RS (Refund) writes a check back to the patient, and a TI / TO pair moves money between accounts without touching cash.

Unlike clinical code tables, HL70017 carries direct ledger consequences. Misposting CR (Credit) as DB (Debit) reverses the sign of every downstream balance calculation, which is why financial integrations almost always validate HL70017 against a per-tenant allowed list before processing.

Where it's used

FT1-6 Transaction Type — the canonical home, populated on every FT1 segment in DFT (Detail Financial Transaction) messages.
BLG-3 Billing Type — referenced in some v2.5+ profiles that carry order-level billing context.

Code list

Code	Display	Comment/Description
AJ	Adjustment	Modifies a previously posted charge or payment without moving cash.
CD	Credit card payment	A payment received via credit card.
CO	Co-pay	Patient co-payment collected at point of service.
CR	Credit	A credit to the patient account (increases patient-favorable balance).
DB	Debit	A debit to the patient account (increases patient-owed balance).
DC	Direct deposit	A payment received via direct bank deposit.
PI	Patient payment	A general patient-originated payment.
PY	Payment	A payment from any source (insurance, patient, third party).
RS	Refund	Money returned to the patient or payer.
ST	Statement	A statement was generated; informational, no ledger movement.
TI	Transfer in	Money moved into this account from another account.
TO	Transfer out	Money moved out of this account to another account.

Code system OID

OID: 2.16.840.1.113883.18.11
Canonical URI: http://terminology.hl7.org/CodeSystem/v2-0017

The OID resolves on the HL7 Terminology server and is the value Vorro emits in CWE.14 when a downstream profile demands OID-bound coded values for FT1-6.

HL7-defined vs user-defined

HL70017 is HL7-defined, but FT1-6 is also one of the most-extended fields in real-world v2 traffic. Vendors routinely add codes for ACH, e-check, HSA/FSA payments, write-offs, bad-debt transfers, and various adjustment reasons (WO, BD, ACH, ECK, HSA, FSA). When extending, place local codes in a parallel user-defined table and never overload the two-letter HL70017 namespace — WO looks superficially like a valid HL70017 code and strict receivers may treat it as a conformance error.

Version differences

v2.2 — Table introduced with the financial chapter. Initial set included CG (Charge — later moved), AJ, CR, DB, PY, ST.
v2.3 — CO (Co-pay), PI (Patient payment), RS (Refund), TI, and TO added as point-of-service collection workflows matured.
v2.3.1 – v2.5 — CD (Credit card payment) and DC (Direct deposit) added to distinguish payment instruments.
v2.6 – v2.8.1 — Set frozen at twelve codes; vendor extensions take over for finer-grained instrument distinctions (ACH, HSA, FSA).
v2.9 — HL70017 itself is unchanged. FHIR alignment work splits the semantics across PaymentNotice, Invoice, and Account resources rather than into a single ValueSet.

Common mistakes

Using CR to mean "credit card" instead of "credit (ledger sign)". CR is a ledger-sign credit; credit-card payments use CD.
Confusing PI (Patient payment) and PY (Payment). PI is specifically patient-originated; PY is a generic payment that may be insurance, third party, or patient. Strict billing systems track these separately.
Sending AJ without populating FT1-22 Adjustment Code or a user-defined adjustment-reason field. A bare AJ with no reason cannot be posted automatically.
Treating ST (Statement) as a ledger-affecting transaction. ST is purely informational — generating a statement does not move money — and posting it as a charge or payment double-counts the underlying transaction.
Using TI/TO without paired matching transactions. Every TO from account A must have a corresponding TI to account B; orphaned transfers break ledger reconciliation.

Examples

A patient co-pay collected at the front desk:

FT1|1|||20260625|20260625|CO|99213^Office Visit^CPT||1|||||25.00||||||||||||

An insurance payment posting:

FT1|2|||20260626|20260626|PY|99213^Office Visit^CPT||1|||||120.00|||AETNA^Aetna^MR

A refund issued to the patient:

FT1|3|||20260627|20260627|RS|99213^Office Visit^CPT||1|||||15.00

Same PY transaction projected onto a FHIR PaymentNotice:

{
  "resourceType": "PaymentNotice",
  "status": "active",
  "payment": {
    "reference": "PaymentReconciliation/example"
  },
  "amount": {
    "value": 120.00,
    "currency": "USD"
  },
  "paymentStatus": {
    "coding": [{
      "system": "http://terminology.hl7.org/CodeSystem/v2-0017",
      "code": "PY",
      "display": "Payment"
    }]
  }
}

Mapping failure example — vendor extension collision:

FT1|4|||20260628|20260628|WO|99213^Office Visit^CPT||1|||||50.00

WO (write-off) is not in HL70017. A conformant engine should either reject the message (if the destination profile is strict HL7), or route to the curation queue and either remap to AJ with a write-off adjustment-reason code or pass WO through with CWE.3 set to a local namespace.

FHIR mapping

There is no published one-to-one HL70017-to-FHIR ConceptMap because the twelve codes describe events that span multiple FHIR resources rather than a single coded element. The conventional mapping is:

HL7 v2 (HL70017)	FHIR resource	FHIR field
AJ	Invoice	lineItem with negative or correcting amount
CD, DC, PI, PY	PaymentNotice / PaymentReconciliation	paymentStatus, amount
CO	Invoice	lineItem.priceComponent (co-pay)
CR, DB	Account	balance adjustments
RS	PaymentNotice	with paymentStatus indicating refund
ST	Communication	informational; no ledger impact
TI, TO	Account	relationships between Account resources

Engines that need to preserve the exact v2 code must carry it as a Coding on the corresponding FHIR resource (commonly via an extension) — there is no native HL70017-equivalent code element in FHIR financial resources.

Engine considerations

Sign discipline — CR/DB and TI/TO carry sign semantics. Validate the FT1-7 (Transaction Posting Date) and FT1-12 (Transaction Amount) signs against the transaction type and reject inconsistencies.
Paired transactions — TI and TO must reconcile across accounts. Engines should hold a TO until its paired TI arrives, then commit both atomically.
Idempotency — Financial messages must not be replayed; track FT1-2 Transaction ID and reject duplicates rather than double-posting.
Vendor extension handling — WO, BD, ACH, HSA, and FSA are common local extensions. Configure a per-source remap table; never silently pass unknown codes through to the AR system.

How Vorro handles HL70017

Vorro validates FT1-6 against the twelve HL70017 codes plus a per-tenant extension table on every DFT message. Unknown codes are routed to the financial curation queue rather than the general terminology queue, because financial mismaps have ledger consequences and need a faster review SLA. Each remap is logged with the original payload and the operator who approved it.

Transfer pairs (TI/TO) are reconciled in a holding buffer with a configurable timeout; orphaned transfers raise an alert rather than posting half a transaction. Refunds (RS) are blocked from auto-posting on tenants that require manual refund authorization, and statements (ST) are routed to the document-generation channel rather than the AR-posting channel.

On outbound, Vorro emits HL70017 as IS for v2.5 and earlier profiles and as CWE with CWE.14 populated for v2.7+ destinations that advertise OID-bound coded values.

Sources

← Back to HL7 v2 Guide