# VDV Bardcode field mappings
When requesting a VDV barcode, TapConnect generates barcodes according to the VDV_KA_SPEC_1.9.1 specification. The documents describing this specification can be obtained at e-ticket Deutschland (opens new window).
The field list below is mostly based on Technische Anforderung Deutschlandticket V1.7.pdf page 15, chapter 4.3
| Field | TapConnect contents | Description |
|---|---|---|
| berBerechtigung_ID (Struktur "Berechtigung_ID") | ||
| - Berechtigung_ID | vSAM signing key usage counter plus setting Issuing.barcodeVdvEntitlementNumberOffset See FAQ | BerechtigungsId is the entitlement offset + vSAM Signature Key Usage Counter. Please note that the Berechtigung_ID is unique, but not related to the ticketId or the serviceId we know in TapConnect. |
| - Referenz-ORG_ID für KVP | Issuing.barcodeVdvOrgId (vSAM Key OrgId), OrgId of the transport operator | |
| - prodProdukt_ID | 0x270f0bb8 (0x270f=9999 dec), (0x0bb8=3000 dec). First part is the product code, and the second part is the PV OrgId See FAQ. Product codes are 9999 for regular D-Ticket, 9998 for job ticket, 9995 for Student/Schüler ticket) | Technische Anforderung Deutschlandticket V1.7.pdf page 5 for the product numbers, and page 15 for the Org_id of the PV: "...ORG_ID des zentralen PV", and KA HD_BOM-Spec_V190.pdf page 104, table 6-103 for the structure. |
| - berGueltigkeitsbeginn | Barcode validity start (this is also ticket validity start) | date in dateTimeCompact format, see KA HD_BOM-Spec_V190.pdf page 50, table 6-10 |
| - berGueltigkeitsende | Barcode validity end (this can be different from ticket validity end in case of dynamic barcodes) | date in dateTimeCompact format, see KA HD_BOM-Spec_V190.pdf page 50, table 6-10 |
| Berechtigung – Statischer Produktspezifischer Teil | ||
| Tag "Fahrgast" | See Anlage TLV EFS_V190.pdf, page 9, Tag 0xDB – Fahrgast | |
| - efsFahrgastGeschlecht | Hardcoded to 0x00, See FAQ | See Technische Anforderung Deutschlandticket V1.7.pdf page 15, "Gemäß Vorgabe VDV-ETS" |
| - efsFahrgastGeburtsdatum | Filled with date of birth if provided, 1970-01-01 otherwise | See Anlage TLV EFS_V190.pdf, page 9, 2.2 Tag 0xDB – Fahrgast |
| - efsFahrgastName | Filled with Type 1 anonymized traveler name, empty otherwise See FAQ | See KA HD_BOM-Spec_V190.pdf, 6.7.2 Kürzungsregel für Namen und Vornamen |
| Tag "Liste originärer Geltungsbereich" | ||
| - Typ-Definition | Hardcoded: 0x0F | See Technische Anforderung Deutschlandticket V1.7.pdf page 15, "Gemäß Vorgabe VDV-ETS", and Anlage TLV EFS_V190.pdf page 18 Tabelle 2-8, Variant D 0x0F |
| - Organisation_ID (PV) | Hardcoded: 0x1388 (5000 dec) | See Technische Anforderung Deutschlandticket V1.7.pdf page 15, "Gemäß Vorgabe VDV-ETS" |
| - Liste-Flaeche-IDs | Hardcoded: 0x00 0x01 | See Technische Anforderung Deutschlandticket V1.7.pdf page 15, "Gemäß Vorgabe VDV-ETS" |
| logTransaktionsOperator_ID | Issuing.barcodeVdvOrgId (vSAM Key OrgId) | |
| logTerminal_ID (Struktur "Terminal_ ID") | See KA HD_BOM-Spec_V190.pdf, page 112, table 6-127 | |
| - TerminalTyp | Issuing.barcodeVdvTerminalTyp, Usually set to 0x11 (17, Online Ticket Server = barcode auf papier) | See KA HD_BOM-Spec_V190.pdf, page 92, table 6-85 |
| - terminalNummer | Issuing.barcodeVdvTerminalId | Configurable per Tenant |
| - terminalBetreiber | Hardcoded: 39380, XIMEDES_L2_ORGID See FAQ | |
| logTransaktionsZeitpunkt | Validity start or the Date/time of creation of the barcode, whichever is earlier, See FAQ | See KA HD_BOM-Spec_V190.pdf, page 132, table 6-158 |
| TransaktionsOrtID (Struktur "Ort_ID") | See KA HD_BOM-Spec_V190.pdf, page 110, table 6-123 | |
| - OrtTyp | Hardcoded: 0xc9 (201 dec), Massenpersonalisierer | See KA HD_BOM-Spec_V190.pdf, page 84, table 6-69 |
| - OrtNummer | Hardcoded: 0x01 | |
| - OrtDomaene_ID | Hardcoded: 0x99d4 (39380 dec), XIMEDES_L2_ORGID See FAQ | |
| Transaktion Produktspezifischer Teil | ||
| - Tag "Transaktion Produktspezifischer Teil" | Hardcoded 0x8a 0x00, empty TLV, length 0. | See Technische Anforderung Deutschlandticket V1.7.pdf page 15, "Der Transaktion Produktspezifische Teilwird beim TLV EFS nicht benutzt." |
| - berProdLog SAMSeqNummer | vSAM signing key Usage counter | See KA HD_BOM-Spec_V190.pdf, page 140, table 6-162 |
| - Version MKpv | vSAM KV (1 byte key version) | See KA HD_BOM-Spec_V190.pdf, page 130, table 6-152 |
| - SamSequenznummer | vSAM Usage counter (in our case this is the Key Usage Counter, see berProdLog SAMSeqNummer) | See KA HD_BOM-Spec_V190.pdf, page 113, table 6-130 |
| - SAM_ID.samNummer | 3 byte vSAM number provided during the ordering process in the ASM-Tool of VDV (opens new window) | As registered with VDV, see KA SAM-Spec_V190.pdf page 205 and KA NM-SPEC_V190.pdf page 199 table 5-12 |
| - Füllbytes | Padding with 0x00 bytes to make the total ticket at least 111 bytes long | See KA STB-SPEC_V190.pdf, Tabelle 3-1, page 12 |
| Kennung "VDV" | Hardcoded: "VDV" as OctetString | See KA STB-SPEC_V190.pdf, Tabelle 3-1, page 12 |
| Version | Hardcoded: 0x19, 0x00 (version 1.9.0.0 of the KA-STB spec) | See KA STB-SPEC_V190.pdf, Tabelle 3-1, page 12, footnote 11: not configurable |
# FAQ
# Why doesn't the Ticket ID match the data element berechtigungNummer
TapConnect is an existing barcode generation solution which generates its own ticketId and serviceId. The VDV berechtigungsNummer is not useful to the traveler. When a customer has questions about a ticket, normally the serviceId is used in communication with our servicedesk. This serviceid can be found in the responses of TapConnect API when creating or getting info about the Ticket, and is shown in the D-Ticket app on the "back" of the barcode.
The berechtigungNummer is built from the SAMSeqNummer plus a configurable offset, which we configure to be 0 by default. Please let us know if your offset needs to be different.
# Why is the PV Org-Id always 3000
According to the information we received in the document "Technische Anforderung Deutschlandticket v1.7", page 6, the organizationsNummer (OrgID) of the Produktverantwortlicher should be 3000:
Aufgrund eines Beschlusses des VDV-Präsidiums wird ein zentraler, technischer PV eingeführt. Das entsprechende zentrale PVS (ZPVS) wird vorläufig von VDV-ETS betrieben und arbeitet mit der ORG_ID 3000 (Level 3) bzw. 35768 (Level 2). Demzufolge ist als PV-Schlüssel (KID 40) der mit der ORG_ID 3000 (Level 3) bzw. 35768 (Level 2) jeweils in der Regel- und Notfallversion zu verwenden. Diese ORG_ID ist in die Produkt_ID einzutragen.
# Why is the logTransaktionsZeitpunkt not the current/date/time?
According to the VDV specification the logTransaktionsZeitpunkt cannot be after berGueltigeitsbeginn. So when your ticket is valid from the first of the month, the logTransaktionsZeitpunkt will also be the first of the month.
Ticket created at : 10.08.2023 10:46 Uhr for a D-Ticket in August
berGueltigkeitsbeginn : 01.08.2023 00:00
logTransaktionsZeitpunkt : 01.08.2023 00:00
# Why is "fahrgastGeschlecht" always "unspecified"
In TapConnect 523 of October 17th we changed the efsFahrgastGeschlecht to "unspecified" (0x00), as specified in "Technische Anforderung Deutschlandticket v1.7"
# Why is tag „Grundlegende Daten“ (0xDA) not in the barcode?
This is optional information currently not in the Ticket. For D-Ticket this seems less relevant. There are currently no plans to add this optional information to the barcode. (it is also not part of the example in the Technische Anforderung D-Ticket)
# Why are the terminalBetrieber and OrtDomaene_ID the Level 2 Ximedes id
The logTerminal_ID.terminalBetrieber and TransaktionsOrtID.OrtDomaene_ID are the Level 2 Ximedes id (39380), since Ximedes is the "operator" of your vSAM. During implementation we discussed this with VDV, and implemented it as follows:
logTerminalID (structure "Terminal ID")
terminalTyp.code = 16 decimal (mobile phone ticket server) or 17 decimal (online ticket server = barcode on paper)
terminalNummer = number is assigned by the SAM server operator
Organisation_ID.organisationsNummer = ORG_ID of the SAM server operator (Level 2)
logTransaktionsOrtID (structure " Ort_ID")
ortTyp.code = 201
ortNummer = number assigned by the SAM server operator
Organisation_ID.organisationsNummer = ORG_ID of the SAM server operator (Level 2)
In case the KVP wants to have this field filled differently, please contact us.
# Why is the efsFahrgastname encoded
The name of the traveler is stored in an anonymized form in the barcode. According to KA HD_BOM-Spec_V190.pdf, 6.7.2 Kürzungsregel für Namen und Vornamen there are two types of anonymization of names. We chose Type 1 (Maskierter und gekürzter Name). There is also a Type 2, which is currently not supported.
An example of Type 1 anonymization:
Firstname : Eva-Maria Alexandra Tanja Manuela
Lastname : Gräfin von Konstantinopolus
Becomes : E1a*@*K0s
Depending on your barcode scanner, this can be shown on screen as E_a K_________s.