Card Generation Interface

Specification
Version: 12.7
30 June 2023
Publication number: CGIS-12.7-6/30/2023

For the latest technical documentation, see the Documentation Portal.

Thredd 6th Floor, Victoria House, Bloomsbury Square, London, WC1B 4DA
Support Email: [email protected]
Support Phone: +442037409682

© Thredd 2023
Copyright
© Thredd 2023
The material contained in this guide is copyrighted and owned by Thredd Ltd together with any other intellectual property in such
material.
Except for personal and non‐commercial use, no part of this guide may be copied, republished, performed in public, broadcast, uploaded,
transmitted, distributed, modified or dealt with in any manner at all, without the prior written permission of Thredd Ltd., and, then, only in
such a way that the source and intellectual property rights are acknowledged.
To the maximum extent permitted by law, Thredd Ltd shall not be liable to any person or organisation, in any manner whatsoever from the
use, construction or interpretation of, or the reliance upon, all or any of the information or materials contained in this guide.
The information in these materials is subject to change without notice and Thredd Ltd. assumes no responsibility for any errors.

© Thredd 2023 Card Generation Interface Specification 2

About this Document
This document describes the format for the Thredd Card Generation XML Interface.
The interface allows card manufacturers to accept card generation files from Thredd.

What’s Changed?
If you want to find out what's changed since the previous release, see the Document History section.

How to use this Guide

If you want to find out about the file naming convention and different file format options available, see About the Card Generation File.
To view example files, see Example Files.
To view details of the fields in the XML files, see XML Fields.
For details of field differences between file formats, see File Format and File Versions.

Related Documents
Refer to the table below for other documents which should be used in conjunction with this guide.

Document Description

Web Services Guide Describes how to use the Thredd web services API to make agency banking requests.

EHI Guide Provides details of the Thredd External Host Interface (EHI).

Smart Client Guide Describes Smart Client, which is an administration application that can be used to view and manage
cards and transactions in your program.

Tip: For the latest technical documentation, see the Documentation Portal.

Other Relevant Documents

The following ISO standard documents provide additional information on some card fields. These are available at iso.org.

Document Description

ISO 9564-1 Specifies PIN block formats.

Specification

ISO 7813 Specification Specifies Magnetic Stripe Data formats.

ISO 4217 Specification Specifies currency codes (but note that Thredd may differ slightly, in cases where Visa/Mastercard differ
from the ISO specification).

ISO 8583 Specification Specifies PAN and PAN sequence number.

© Thredd 2023 Card Generation Interface Specification 3

1 About the Card Generation File
1.1 File Naming Conventions
The file naming convention is flexible but by default, card interface files have the following naming convention:

1.1.1 On-Premise Customers (P0)

XXXX_PPPP_rrrr_bbbb.xml

1.1.2 Thredd Cloud (P1 and P2)

XXXX_PPPP_rrrr_bbbb_Pn.xml
Where:
l XXXX — is the Institution name as held by Thredd
l PPPP— is the first PRODUCT_REF (product reference) in the file
l Rrrr — is the number of records in the file
l Bbbb — is the unique Thredd batch number
l Pn — is the production environment (2 digits), such as P1 and P2. (Not applicable to customers in our UK data centre production
environment)

1.1.3 Example
CLI_PRODUCT1_124_1571_P1.xml

Note: The production environment variable is relevant to customers in one of our AWS Cloud-based production environments (P1 and P2)
and does not apply to existing customers in our UK data centre production environment (P0). For details of which production environment
applies to your programme, please check with your Thredd implementation manager or account manager.

1.2 File Formats

The Card Generation XML file is available in the following formats:
l 1 — Cut-Down Format. By default, you are provided with this format, which is similar to the file sent to the card bureau but with
sensitive information removed. This file does not contain the following fields:
l <TRACK1>
l <TRACK2>
l <CVV2>
l The CHIP element which includes the fields: <CHIP> <CHIP_TRACK_1> <CHIP_TRACK_2> <CHIP_TRACK_1_MSD_CL>
<CHIP_TRACK_2_MSD_CL> and <PINBLOCK>
l 2 — Full Format. This format is provided on request and only to fully PCI-compliant clients. This file is the same as the one sent to
the card bureau and includes the sensitive information above.
l 3 — Cut Down Format with masked PAN. This format is provided on request and is the same as the Cut-Down Format but includes
the masked PAN in the <PAN> element.

Note: For examples of full and cut-down formats, see Example Files. For more information on the fields included with each file format, see File
Format and File Versions.

© Thredd 2023 Card Generation Interface Specification 4

1.3 Data Format Version Number
This indicates the data version number. Newer data format versions may include new fields. Currently supported data format versions
are: 10, 11 and 12. For more information on the fields included with each data format version, see File Format and File Versions.

© Thredd 2023 Card Generation Interface Specification 5

2 XML Fields
This section provides details of the fields included in the XML file.

Nulls
XMLTAG Type Length Description
Allowed

<CARDGEN> Header tag N/A

<CARDSUM> Summary file opening tag N/A

<DATA_FORMAT_VERSION> Varchar 5 File version No

<FILEDATE> dd-mm- 10 File date No

yyyy

<FILETIME> hh-mm- 10 File time No

ss

<NO_OF_CARRIERS> Integer Number of carriers No

<NO_OF_CARDS> Integer Number of cards No

<NO_OF_PRODUCTS> Integer Number of different products in the file (Mag No

stripe/chip etc)

<TXREF> varchar 30 Transmission_Reference No

This is an incrementing reference number and may
not be consecutive.

<ORDER_REF> varchar 30 Customer order reference number Yes

<PRODUCT> Defines a product set N/A

<PRODUCT_REF> varchar 50 Identifies the product. No

Note: This is the physical card Design reference as

used by the card printer.

<RECORD> Defines a record within a Product N/A

<REQUEST_TYPE> varchar 15 Indicates whether the card is a “New” or No

“Replacement” card request
For PIN Mailers, can be one of:
PIN_MAILER
NEW_WITH_PINM
REPL_WITH_PINM

<UID> Varchar 20 Unique identifier to identify the record. You can use No
this in error tracking.

<CARRIER> Defines the Carrier section within a Record N/A

<TITLE> Varchar 10 Cardholder title Yes

<FNAME> Varchar 20 Cardholder first name Yes

© Thredd 2023 Card Generation Interface Specification 6

 Nulls
XMLTAG Type Length Description
Allowed

<SNAME> Varchar 30 Cardholder surname Yes

<ADD1> Varchar 50 Cardholder address line 1 Yes

<ADD2> Varchar 50 Cardholder address line 2 Yes

<ADD3> Varchar 50 Cardholder address line 3 Yes

<ADD4> Varchar 50 Cardholder address line 4 Yes

<CITY> Varchar 50 Cardholder address city Yes

<POSTCODE> Varchar 10 Cardholder address postcode Yes

<MOBILE> Varchar 50 Mobile phone number linked to the card Yes

<COUNTRY> Varchar 3 Cardholder address country. Numeric 3-digit ISO Yes

3166-1 Country code (e.g. 052 for Barbados).
(Always 3 digits, use leading zeros if needed.)

<BULK_ADD1> Varchar 50 Alternative delivery address line 1. If present, should Yes

be used in preference to carrier address.

<BULK_ADD2> Varchar 50 Alternative delivery address line Yes

<BULK_ADD3> Varchar 50 Alternative delivery address line 3 Yes

<BULK_CITY> Varchar 50 Alternative delivery address city Yes

<BULK_COUNTY> Varchar 20 Alternative delivery address count Yes

<BULK_POSTCODE> Varchar 10 Alternative delivery address postcode Yes

<BULK_COUNTRY> Varchar 3 Alternative address country. Numeric 3-digit ISO Yes

3166-1 Country code (e.g. 052 for Barbados).
(Always 3 digits, use leading zeros if needed.)

<CARRIER_TYPE> Varchar 30 Defines carrier product. No

Note: This is the Carrier Product Design reference

as used by the card printer.

<CARRIER_LOGO_ID > Varchar 20 Defines an optional carrier logo. Yes

<DELV_METHOD> Char 1 The delivery method for the card: No

0 = Standard mail (default)
1 = Registered mail
2 = Direct delivery (Courier)

<DELV_CODE> Varchar 12 The delivery code for the card: Yes

If specified, all cards with the same delivery code are
to be sent together to the specified BULK delivery
address.
Carriers with the same DELV_CODE will be grouped

© Thredd 2023 Card Generation Interface Specification 7

 Nulls
XMLTAG Type Length Description
Allowed

together in the file.

<FULFIL1> Varchar 50 RFU (Reserved for Future Use) Yes

<FULFIL2> Varchar 50 RFU Yes

<LANG> Char 2 Defines the language of the carrier product, if it is not Yes
already defined by the <CARRIER_TYPE> elements.
Uses ISO 639-1 language code.
Examples:
English is “en”, French is “fr”

<CARD> Card definition opening tag within a Record N/A

<TYPE> varchar 20 Defines the product: No

“Mag”
“Chip&PIN”
“Chip&PIN&Contactless”

<CURRENCY> Char 4 4-digit ISO currency code. For example: “0826”= No

GBP

<TRACK1> Varchar 76 Track 1 data for magnetic stripe, excluding the Start No
Sentinel, End Sentinel and LRC characters.

Note: The ISO standard allows for maximum of 76

(excluding the Start Sentinel, End Sentinel and LRC
characters).

Track Layout

MASTERCARD:
B + PAN + ^ + Name + ^ + Expiry date in “yyMM”
format + Service Code + 00000 + CVV1 + 0000000

VISA:
B + PAN + ^ + Name + ^ + Expiry in "yyMM" format +
Service Code + 00 + CVV1 + 000000

<TRACK2> Varchar 37 Track 2 data for the magnetic stripe, excluding Start No
Sentinel, End Sentinel and LRC characters.

MASTERCARD:
PAN + = + Expiry date in "yyMM" format + Service Code
+ 000000 + Validity in months + CVV1 + PAN Sequence
No

VISA:
PAN + = + Expiry Date in "yyMM" format + Service Code
+ CVV1 + 00000

<TRACK3> Varchar 104 Track 3 data for the magnetic stripe, excluding Start Yes
Sentinel, End Sentinel and LRC characters.

ISO standard allows for a maximum of 104

characters (excluding Start Sentinel, End Sentinel
and LRC).
By default, Thredd will put the Card 9-digit token in

© Thredd 2023 Card Generation Interface Specification 8

 Nulls
XMLTAG Type Length Description
Allowed

this element.

<EMBOSS_PAN> Integer 19 Embossed card Primary Account Number (PAN) No

<EMBOSS_NAME> varchar 27 Embossed card name. Actual maximum length will Yes
depend on the card design.

<EMBOSS_START> Varchar 10 Embossed card start date (MM/YY) No

<EMBOSS_EXPIRY> Varchar 10 Embossed card expiry date (MM/YY) No

<EMBOSS_CVC2> varchar 10 Embossed card Verification Code 2 (CVC2) No

<EMBOSS_LINE4> Varchar 27 Embossed card line 4. Actual maximum length will Yes
depend on the card design.

<THERMAL_LINE1> Varchar 70 Example, Company name Yes

<THERMAL_LINE2> Varchar 120 RFU Yes

<IMAGE_ID> Varchar 20 Identifies the image file that will be printed on the Yes
face of the card.

<LOGO_FRONT_ID> Varchar 30 Identifies the logo file that will be printed on the face Yes
of the card.

<LOGO_BACK_ID> Varchar 30 Identifies the image file that will be printed on the Yes
back of the card, if supported.

<QRCODE> Varchar 100 Identifies the QR code that will be printed on the Yes
card, if supported. You can add separate values to
each card using Thredd Web Services.

<PINBLOCK> Hexade 16 Optional. Will only be present if the card is Mag Yes
cimal stripe and the card requester requires online PIN.
Used for PIN mailers.

Format is the same as <PINBLOCK> in the <CHIP>

section; see below.

<CHIP> Defines the chip details within a Record. This N/A

element may not be present, depending on Card
Type.

<TYPE> varchar 10 Possible values: Yes

Maestro
Mastercard
VisaCard
Euro Cirrus
EuroCard
Cirrus Maestro
PLUS Card

<PAN> Integer 16-19 Primary Account Number ISO 8583 bit 2 Yes

<PAN_SEQ> Integer 2 PAN Sequence number. ISO 8583 bit 23. Yes

© Thredd 2023 Card Generation Interface Specification 9

 Nulls
XMLTAG Type Length Description
Allowed

Value from 00 to 99.

<NAME> Varchar 26 Must match name embedded in Track 1 Yes

<START_DATE> Integer 6 YYMMDD Yes

<EXPIRY_DATE> Integer 6 YYMMDD Yes

<SERVICE_CODE> Integer 3 Three decimal digits as defined in ISO 7813. Yes

First digit: Use and Technology:

1 = International
2 = International, Chip
5 = National Use Only
6 = National Use Only, Chip
7 = Private Label
9 = Test Card

Second digit: Authorisation requirements:

0 = Normal
2 = Online Authorisation Required
4 = Online Authorisation required unless special
agreement

Third digit: Service and PIN requirements:

0 = PIN Required
1 = No restrictions
2 = Purchases only
3 = ATM Only, PIN required
4 = Cash only
5 = Purchases only, PIN required
6 = Use PIN if possible
7 = Purchases only, use PIN if possible

<CHIP_TRACK_1> varchar 76 This is the entire chip track 1 for EMV transactions. Yes
It permits the derivation of EMV tag hex 9F1F (track
1 discretionary data as defined in ISO 7813) which is
part of this.

MASTERCARD:
B + PAN + ^ + Name + ^ + Expiry date in “yyMM”
format + Service Code + 00000 + iCVV + 0000000

VISA:
B + PAN + ^ + Name + ^ + Expiry Date in "yyMM"
format + Service Code + 00 + iCVV + 000000

<CHIP_TRACK_2> varchar 38 This is the EMV Track 2 equivalent data, for EMV tag Yes
hex 57. It is for EMV-based (including qVSDC)
transactions (both contact and contactless)

MASTERCARD:
PAN + D + Expiry in "yyMM" format + Service Code +
000000 + Validity in months + iCVV + PAN
Sequence No (If the length of CHIP_TRACK_2 is
odd then will add “F” at the end)

© Thredd 2023 Card Generation Interface Specification 10

 Nulls
XMLTAG Type Length Description
Allowed

VISA:
PAN + D + Expiry Date in "yyMM" format + Service
Code + iCVV + 00000 (If the length of CHIP_
TRACK_2 is odd then will add “F” at the end)

<CHIP_TRACK_1_MSD_CL> Varchar 76 Optional. This element will only be present if the Yes
product type supports Contactless Magnetic Stripe
Transactions.
It is the base Track 1 for Contactless Magnetic Stripe
(which is not EMV) transactions.

MASTERCARD:
For Mastercard, this is for tag hex 56 (PayPass
Magstripe Track 1 Data.) (See Mastercard “PayPass
MagStripe Technical Specifications v3.2 Oct 2006”.)

VISA:
For Visa, if there is a separate data item on the ICC
for the Track 1 exclusively for Magnetic Stripe Data
(not EMV or qVSDC) then use this for it.

Format is same as <CHIP_TRACK_1> except Name is

replaced with space and forward slash i.e. “ /”, and
discretionary data may be different.

<CHIP_TRACK_2_MSD_CL> Varchar 37 Optional. This element will only be present if the Yes
product type supports Contactless Magnetic Stripe
transactions.
It is the base Track 2 for contactless Magnetic Stripe
(which is not EMV) transactions.

MASTERCARD:
For Mastercard, this is for tag hex 9F6B (PayPass
Magstripe Track 2 Data.) (See Mastercard “PayPass
MagStripe Technical Specifications v3.2 Oct 2006”.)

VISA:
For Visa, if there is a separate data item on the ICC
for the Track 2 exclusively for Magnetic Stripe Data
(not EMV or qVSDC) then use this for it.

Format is same as <CHIP_TRACK_2> but discretionary

data may be different.

<PINBLOCK> Hexade 16 Holds the encrypted PIN to be placed on the chip Yes
cimal card.
Format is ISO 9564-1 Format 0 (same as ANSI X9.8
Format 0), triple DES encrypted with the double-
length Zone PIN Key, expressed as 16 hex digits
(with 2 hex digits representing 1 binary byte.)

This is formed as:

Plaintext PIN field = ‘0’+ PIN length (4-C) + PIN + ‘F’s
padding to 16 hex digits.

Account number field = ‘0000’ + rightmost 12 digits of

the PAN excluding the check digit.

Then XOR the ‘Plaintext PIN field’ and ‘Account

number field’.

© Thredd 2023 Card Generation Interface Specification 11

 Nulls
XMLTAG Type Length Description
Allowed

This is 16 hex digits representing 8 binary bytes.

Then Triple-DES encrypt the resultant 8 binary bytes
with the double length Zone PIN Key.

Example:
PAN = 5299887766554439
PIN = 223344
Zone PIN Key =
3B6870987613107CFB1F4C6EC17F3483

Plaintext PIN field = 06223344FFFFFFFF

Account Number Field = 0000988776655443
Result of XOR = 0622ABC3899AABBC
Encrypting this with the Zone PIN key gives result:
7553DAA289620533

So PINBLOCK is 7553DAA289620533

Additional Fields (In Cut-Down File Version for Program Manager)

XMLTAG Type Length Description Nulls Allowed

<CUST_ACCNO> Varchar 25 Cardholder account Yes

number or reference
number. You can use
this reference to find the
cards linked to a
cardholder. Also
displayed in Smart
Client as Customer
Reference. (Note: This
corresponds to the
CustAccount parameter
set using Web Services.

<PASSCODE> Varchar 6 Code which can be Yes

used to validate the
card when a card
activation request is
received from the
cardholder. (Note: This
corresponds to the
AccCode parameter set
using Web Services.

2.1 XML Markup

Please note that certain characters are reserved for XML markup. When an XML parser encounters a reserved character, it assumes it
has encountered an element, entity or markup statement. The following examples of reserved characters, and what you should replace
this with if you need to include that character as data in the XML file:

© Thredd 2023 Card Generation Interface Specification 12

 Reserved character What you should use

< &lt;

> &gt;

& &amp;

' &apos;

" &quot;

© Thredd 2023 Card Generation Interface Specification 13

3 Example Files
Note: The contents in this file may differ, depending on the card type, data format version number and file format. For more information on the
fields included with each data format version and file type, see File Format and File Versions.

3.1 Full version for Card Manufacturer

Below is an example of a typical card generation XML file sent to the card manufacturer:

<?xml version="1.0" encoding="utf-8"?>

<CARDGEN>
<CARDSUM>
<DATA_FORMAT_VERSION>12</DATA_FORMAT_VERSION>
<FILEDATE>02-01-2023</FILEDATE>
<FILETIME>09-15-55</FILETIME>
<NO_OF_CARRIERS>2</NO_OF_CARRIERS>
<NO_OF_CARDS>2</NO_OF_CARDS>
<NO_OF_PRODUCTS>1</NO_OF_PRODUCTS>
<TXREF>1001</TXREF>
<ORDER_REF>ABC-123</ORDER_REF>
</CARDSUM>
<PRODUCT>
<PRODUCT_REF>DESIGN1</PRODUCT_REF>
<RECORD>
<REQUEST_TYPE>New</REQUEST_TYPE>
<UID>123456789</UID>
<CARRIER>
<TITLE>Mr.</TITLE>
<FNAME>Fred</FNAME>
<SNAME>Jones</SNAME>
<ADD1>Sample Company</ADD1>
<ADD2>1 Sample Street </ADD2>
<ADD3>Sample Borough </ADD3>
<ADD4>Sample Address Line 4</ADD4>
<CITY>Sample City</CITY>
<POSTCODE>E1W2BS</POSTCODE>
<MOBILE>44123456789</MOBILE>
<COUNTRY>UK</COUNTRY>
<BULK_ADD1></BULK_ADD1>
<BULK_ADD2></BULK_ADD2>
<BULK_ADD3></BULK_ADD3>
<BULK_CITY></BULK_CITY>
<BULK_COUNTY></BULK_COUNTY>
<BULK_POSTCODE></BULK_POSTCODE>
<BULK_COUNTRY></BULK_COUNTRY>
<CARRIER_TYPE>CAR_1</CARRIER_TYPE>
<CARRIER_LOGO_ID></CARRIER_LOGO_ID>
<DELV_METHOD>0</DELV_METHOD>
<DELV_CODE></DELV_CODE>
<FULFIL1></FULFIL1>
<FULFIL2></FULFIL2>
<LANG>en</LANG>
</CARRIER>
<CARD>
<TYPE>Mag</TYPE>
<CURRENCY>0826</CURRENCY>
<TRACK1>B1234567812345678^GIFTCARD/CORPORATE^1811122000009830000000</TRACK1>
<TRACK2>1234567812345678=16102210000006064400</TRACK2>
<TRACK3>953171211</TRACK3>
<EMBOSS_PAN>1234 5678 1234 5678</EMBOSS_PAN>
<EMBOSS_NAME>MR A B SAMPLE</EMBOSS_NAME>
<EMBOSS_START>11/11</EMBOSS_START>
<EMBOSS_EXPIRY>10/16</EMBOSS_EXPIRY>
<EMBOSS_CVC2>1234 135</EMBOSS_CVC2>
<EMBOSS_LINE4>A123 REG</EMBOSS_LINE4>
<THERMAL_LINE1>Possible Company Name here</THERMAL_LINE1>
<THERMAL_LINE2></THERMAL_LINE2>

© Thredd 2023 Card Generation Interface Specification 14

 <IMAGE_ID></IMAGE_ID>
<LOGO_FRONT_ID></LOGO_FRONT_ID>
<LOGO_BACK_ID></LOGO_BACK_ID>
<QRCODE>https://www.flex-e-card.com/balance/2909680989632389</QRCODE>
<PINBLOCK>3A56DFF541C12197</PINBLOCK>
</CARD>
</RECORD>
<RECORD>
<REQUEST_TYPE>New</REQUEST_TYPE>
<UID>52738098</UID>
<CARRIER>
<TITLE>Mr.</TITLE>
<FNAME>AN</FNAME>
<SNAME>Other</SNAME>
<ADD1>Tall Pines</ADD1>
<ADD2>1 Sample Road </ADD2>
<ADD3>Sample Borough </ADD3>
<ADD4></ADD4>
<CITY>Sample City</CITY>
<POSTCODE>E1W2BS</POSTCODE>
<MOBILE>447734567679</MOBILE>
<COUNTRY>UK</COUNTRY>
<BULK_ADD1>General Manager</BULK_ADD1>
<BULK_ADD2>The Big Company</BULK_ADD2>
<BULK_ADD3>123 The High Street</BULK_ADD3>
<BULK_CITY>Maintown</BULK_CITY>
<BULK_COUNTY></BULK_COUNTY>
<BULK_POSTCODE>MA1 1MA</BULK_POSTCODE>
<BULK_COUNTRY>UK</BULK_COUNTRY>
<CARRIER_TYPE>CAR_2</CARRIER_TYPE>
<CARRIER_LOGO_ID>Logo1</CARRIER_LOGO_ID>
<DELV_METHOD>2</DELV_METHOD>
<DELV_CODE>BO29</DELV_CODE>
<FULFIL1></FULFIL1>
<FULFIL2></FULFIL2>
<LANG>en</LANG>
</CARRIER>
<CARD>
<TYPE>Chip&PIN</TYPE>
<CURRENCY>0826</CURRENCY>
<TRACK1>B1234567890123456^GIFTCARD/CORPORATE^1811122000009830000000</TRACK1>
<TRACK2>1234567890123456=16102210000006064400</TRACK2>
<TRACK3>123456789</TRACK3>
<EMBOSS_PAN>1234 5678 9012 3456</EMBOSS_PAN>
<EMBOSS_NAME>MR AN OTHER</EMBOSS_NAME>
<EMBOSS_START>11/11</EMBOSS_START>
<EMBOSS_EXPIRY>10/16</EMBOSS_EXPIRY>
<EMBOSS_CVC2>1234 157</EMBOSS_CVC2>
<EMBOSS_LINE4></EMBOSS_LINE4>
<THERMAL_LINE1></THERMAL_LINE1>
<THERMAL_LINE2></THERMAL_LINE2>
<IMAGE_ID>img00124</IMAGE_ID>
<LOGO_FRONT_ID>logo_HSBC</LOGO_FRONT_ID>
<LOGO_BACK_ID></LOGO_BACK_ID>
<QRCODE>https://www.flex-e-card.com/balance/2909680989632389</QRCODE>
<CHIP>
<TYPE>MASTERCARD</TYPE>
<PAN>1234567890123456</PAN>
<PAN_SEQ>01</PAN_SEQ>
<NAME>OTHER/MR AN</NAME>
<START_DATE>111101</START_DATE>
<EXPIRY_DATE>161031</EXPIRY_DATE>
<SERVICE_CODE>221</SERVICE_CODE>
<CHIP_TRACK_1>B1234567812345678^OTHER/MR AN ^1610221000004600000000</CHIP_TRACK_1>
<CHIP_TRACK_2>1234567812345678D16102210000006046000F</CHIP_TRACK_2>
<PINBLOCK>3A56DFF541C12197</PINBLOCK>
<CHIP_TRACK_1_MSD_CL>B1234567812345678^ /^1610221000004600000000</CHIP_TRACK_1_MSD_CL>
<CHIP_TRACK_2_MSD_CL>1234567812345678D161022100000001</CHIP_TRACK_2_MSD_CL>
</CHIP>
</CARD>
</RECORD>

© Thredd 2023 Card Generation Interface Specification 15

 </PRODUCT>
</CARDGEN>

3.2 Cut-down version for Program Manager

Below is an example of a copy of the card generation XML file sent to the program manager. Fields containing sensitive cardholder data
have been removed:

<?xml version="1.0" encoding="utf-8"?>

<CARDGEN>
<CARDSUM>
<DATA_FORMAT_VERSION>12</DATA_FORMAT_VERSION>
<FILEDATE>02-01-2023</FILEDATE>
<FILETIME>09-15-55</FILETIME>
<NO_OF_CARRIERS>2</NO_OF_CARRIERS>
<NO_OF_CARDS>2</NO_OF_CARDS>
<NO_OF_PRODUCTS>1</NO_OF_PRODUCTS>
<TXREF>1001</TXREF>
<ORDER_REF>ABC-123</ORDER_REF>
</CARDSUM>
<PRODUCT>
<PRODUCT_REF>DESIGN1</PRODUCT_REF>
<RECORD>
<REQUEST_TYPE>New</REQUEST_TYPE>
<UID>123456789</UID>
<CUST_ACCNO>
<CARRIER>
<TITLE>Mr.</TITLE>
<FNAME>Fred</FNAME>
<SNAME>Jones</SNAME>
<ADD1>Sample Company</ADD1>
<ADD2>1 Sample Street </ADD2>
<ADD3>Sample Borough </ADD3>
<ADD4>Sample Address Line 4</ADD4>
<CITY>Sample City</CITY>
<POSTCODE>E1W2BS</POSTCODE>
<COUNTRY>UK</COUNTRY>
<BULK_ADD1></BULK_ADD1>
<BULK_ADD2></BULK_ADD2>
<BULK_ADD3></BULK_ADD3>
<BULK_CITY></BULK_CITY>
<BULK_COUNTY></BULK_COUNTY>
<BULK_POSTCODE></BULK_POSTCODE>
<BULK_COUNTRY></BULK_COUNTRY>
<CARRIER_TYPE>CAR_1</CARRIER_TYPE>
<CARRIER_LOGO_ID></CARRIER_LOGO_ID>
<DELV_METHOD>0</DELV_METHOD>
<DELV_CODE></DELV_CODE>
<FULFIL1></FULFIL1>
<FULFIL2></FULFIL2>
<LANG>en</LANG>
</CARRIER>
<CARD>
<TYPE>Mag</TYPE>
<CURRENCY>0826</CURRENCY>
<TRACK3>953171211</TRACK3>
<EMBOSS_PAN>1234 5678 1234 5678</EMBOSS_PAN>
<PASSCODE>123456</PASSCODE>
<EMBOSS_NAME>MR A B SAMPLE</EMBOSS_NAME>
<EMBOSS_START>11/11</EMBOSS_START>
<EMBOSS_EXPIRY>10/16</EMBOSS_EXPIRY>
<EMBOSS_LINE4>A123 REG</EMBOSS_LINE4>
<THERMAL_LINE1>Possible Company Name here</THERMAL_LINE1>
<THERMAL_LINE2></THERMAL_LINE2>
<IMAGE_ID></IMAGE_ID>
<LOGO_FRONT_ID></LOGO_FRONT_ID>
<LOGO_BACK_ID></LOGO_BACK_ID>
<QRCODE>https://www.flex-e-card.com/balance/2909680989632389</QRCODE>
</CARD>

© Thredd 2023 Card Generation Interface Specification 16

 </RECORD>
<RECORD>
<REQUEST_TYPE>New</REQUEST_TYPE>
<UID>52738098</UID>
<CUST_ACCNO>
<CARRIER>
<TITLE>Mr.</TITLE>
<FNAME>AN</FNAME>
<SNAME>Other</SNAME>
<ADD1>Tall Pines</ADD1>
<ADD2>1 Sample Road </ADD2>
<ADD3>Sample Borough </ADD3>
<ADD4></ADD4>
<CITY>Sample City</CITY>
<POSTCODE>E1W2BS</POSTCODE>
<COUNTRY>UK</COUNTRY>
<BULK_ADD1>General Manager</BULK_ADD1>
<BULK_ADD2>The Big Company</BULK_ADD2>
<BULK_ADD3>123 The High Street</BULK_ADD3>
<BULK_CITY>Maintown</BULK_CITY>
<BULK_COUNTY></BULK_COUNTY>
<BULK_POSTCODE>MA1 1MA</BULK_POSTCODE>
<BULK_COUNTRY>UK</BULK_COUNTRY>
<CARRIER_TYPE>CAR_2</CARRIER_TYPE>
<CARRIER_LOGO_ID>Logo1</CARRIER_LOGO_ID>
<DELV_METHOD>2</DELV_METHOD>
<DELV_CODE>BO29</DELV_CODE>
<FULFIL1></FULFIL1>
<FULFIL2></FULFIL2>
<LANG>en</LANG>
</CARRIER>
<CARD>
<TYPE>Chip&PIN</TYPE>
<CURRENCY>0826</CURRENCY>
<TRACK3>123456789</TRACK3>
<EMBOSS_PAN>1234 5678 9012 3456</EMBOSS_PAN>
<PASSCODE>123456</PASSCODE>
<EMBOSS_NAME>MR AN OTHER</EMBOSS_NAME>
<EMBOSS_START>11/11</EMBOSS_START>
<EMBOSS_EXPIRY>10/16</EMBOSS_EXPIRY>
<EMBOSS_LINE4></EMBOSS_LINE4>
<THERMAL_LINE1></THERMAL_LINE1>
<THERMAL_LINE2></THERMAL_LINE2>
<IMAGE_ID>img00124</IMAGE_ID>
<LOGO_FRONT_ID>logo_HSBC</LOGO_FRONT_ID>
<LOGO_BACK_ID></LOGO_BACK_ID>
<QRCODE>https://www.flex-e-card.com/balance/2909680989632389</QRCODE>
</CARD>
</RECORD>
</PRODUCT>
</CARDGEN>

© Thredd 2023 Card Generation Interface Specification 17

4 File Format and File Versions
The table below lists the fields supported in each data format version and file format type of the card generation file.

Included in
Included in Full Null Values
XMLTAG V10 V11 V12 Customer Cut-
File? Allowed?
down File ? **

<CARDGEN> Yes N/A Yes

<CARDSUM> Yes N/A Yes

<DATA_ Yes No Yes

FORMAT_
VERSION>

<FILEDATE> Yes No Yes

<FILETIME> Yes No Yes

<NO_OF_ Yes No Yes

CARRIERS>

<NO_OF_ Yes No Yes

CARDS>

<NO_OF_ Yes No Yes

PRODUCTS>

<TXREF> Yes No Yes

<ORDER_ Yes Yes Yes

REF>

<PRODUCT> Yes N/A Yes

<PRODUCT_ Yes No Yes

REF>

<RECORD> Yes N/A Yes

<REQUEST_ Yes No Yes

TYPE>

<UID> Yes No Yes

<CUST_ No Yes Yes

ACCNO>

<CARRIER> Yes N/A Yes

<TITLE> Yes Yes Yes

<FNAME> Yes Yes Yes

<SNAME> Yes Yes Yes

<ADD1> Yes Yes Yes

© Thredd 2023 Card Generation Interface Specification 18

 Included in
Included in Full Null Values
XMLTAG V10 V11 V12 Customer Cut-
File? Allowed?
down File ? **

<ADD2> Yes Yes Yes

<ADD3> Yes Yes Yes

<ADD4> Yes Yes Yes

<CITY> Yes Yes Yes

<POSTCODE> Yes Yes Yes

<MOBILE> Yes Yes No

<COUNTRY> Yes Yes Yes

<BULK_ADD1> Yes Yes Yes

<BULK_ADD2> Yes Yes Yes

<BULK_ADD3> Yes Yes Yes

<BULK_CITY> Yes Yes Yes

<BULK_ Yes Yes Yes

COUNTY>

<BULK_ Yes Yes Yes

POSTCODE>

<BULK_ Yes Yes Yes

COUNTRY>

<CARRIER_ Yes No Yes

TYPE>

<CARRIER_ Yes Yes Yes

LOGO_ID >

<DELV_ Yes No Yes

METHOD>

<DELV_ Yes Yes Yes

CODE>

<FULFIL1> Yes Yes Yes

<FULFIL2> Yes Yes Yes

<LANG> Yes Yes Yes

<CARD> Yes N/A Yes

<TYPE> Yes No Yes

<CURRENCY> Yes No Yes

© Thredd 2023 Card Generation Interface Specification 19

 Included in
Included in Full Null Values
XMLTAG V10 V11 V12 Customer Cut-
File? Allowed?
down File ? **

<TRACK1> Yes No No

<TRACK2> Yes No No

<TRACK3> Yes Yes Yes

<EMBOSS_ Yes No Yes

PAN>

<PASSCODE> No No Yes

<EMBOSS_ Yes Yes Yes

NAME>

<EMBOSS_ Yes No Yes

START>

<EMBOSS_ Yes No Yes

EXPIRY>

<EMBOSS_ Yes No No
CVC2>

<EMBOSS_ Yes Yes Yes

LINE4>

<THERMAL_ Yes Yes Yes

LINE1>

<THERMAL_ Yes Yes Yes

LINE2>

<IMAGE_ID> Yes Yes Yes

<LOGO_ Yes Yes Yes

FRONT_ID>

<LOGO_ Yes Yes Yes

BACK_ID>

<QRCODE> Yes Yes Yes

<PINBLOCK> Optional Yes No

<CHIP> Conditional * N/A No

<TYPE> Conditional * Yes No

<PAN> Conditional * Yes No

<PAN_SEQ> Conditional * Yes No

<NAME> Conditional * Yes No

<START_ Conditional * Yes No

© Thredd 2023 Card Generation Interface Specification 20

 Included in
Included in Full Null Values
XMLTAG V10 V11 V12 Customer Cut-
File? Allowed?
down File ? **

DATE>

<EXPIRY_ Conditional * Yes No

DATE>

<SERVICE_ Conditional * Yes No

CODE>

<CHIP_ Conditional * Yes No

TRACK_1>

<CHIP_ Conditional * Yes No

TRACK_2>

<CHIP_ Conditional * Yes No

TRACK_1_
MSD_CL>

<CHIP_ Conditional * Yes No

TRACK_2_
MSD_CL>

<PINBLOCK> Conditional * Yes No

* Conditional - depends on the card type whether present. Will not be present for Magstripe only cards.
** Cut-down file - sent on request to the Program Manager, excludes fields containing cardholder sensitive data. This file may contain an
additional <CUST_ACCNO > field.

© Thredd 2023 Card Generation Interface Specification 21

Contact Us
Please contact us if you have queries relating to this document. Our contact details are provided below.

Thredd Ltd.
Support Email: [email protected]
Support Phone: +442037409682

Our Head Office

6th Floor,
Victoria House,
Bloomsbury Square,
London,
WC1B 4DA

Telephone: +44 (0)330 088 8761

Technical Publications
If you want to contact our technical publications team directly, for queries or feedback related to this guide, you can email us at:
[email protected].

© Thredd 2023 Card Generation Interface Specification 22

Document History
Version Date Description Revised by

27/06/2023 Added details of relevant ISO specifications that provide additional WS

12.7 details on some field formats. See About this Document.

31/05/2023 Updated Operations email address to be [email protected] MW

27/04/2023 Guide rebrand to new company name and brand identity. JB

07/01/2023 Added new Example Files of both cut-down and full file formats, and a WS
12.6 new File Format and File Versions section with details of fields included
with each file format and data format version.

21/12/2022 Updated numbering in the Table of Contents MW

01/12/2022 Updated Copyright Statement. MW

12.5 12/10/2022 Added details of the file naming conventions for both cloud and on- WS
premise Thredd solutions. See File Naming Conventions.

28/09/2022 Clarified customer file and data format options; updates to TYPE and AL
CARRIER_TYPE elements.

12.4 12/08/2022 New guide layout and HTML version now available PC

12.3 11/08/2022 The values in the QRCode field can now be updated using Web Services. WS
Field size updated from 50 to 100 characters.

12.2 20/08/2021 PRODUCT_REF field maximum length updated to 50 characters. WS

Thredd office address update
07/09/2021

12.1 24/05/2021 Review and update to language. WS

12.0 13/05/2021 New Guide template and layout. Added section on XML reserved WS
markup characters.

11.01 17/12/2020 Clarification of usage of BULK_ADD fields and DELV_CODE (bulk address IF
and delivery code)
No change to file layout.

11.00 10/03/2020 Added MOBILE to CARRIER section. Only appears for version 11.00 IF
and higher.

10.02 10/03/2020 Updated description of TRACK2 and CHIP_TRACK_2 for VISA. Added IF
00000 to each.

10.01 16/01/2020 Clarified descriptions of all CHIP Track data fields, to aid understanding MD
of the usage of them:
CHIP_TRACK_1, CHIP_TRACK_2, CHIP_TRACK_1_MSD_CL, CHIP_TRACK_2_
MSD_CL
Corrected the description of the PINBLOCK field, and an example is
supplied.
Clarified COUNTRY and BULK_COUNTRY code values.
Clarified SERVICE_CODE values.
Added description for PAN and PAN_SEQ values.

© Thredd 2023 Card Generation Interface Specification 23

 Version Date Description Revised by

Table headings now repeated on each page and prevent rows from
breaking across pages if possible.

10.0 26/03/2019 Added BULK_COUNTY to the CARRIER section IF

9.03 21/03/2016 Corrected max length of TRACK1 and updated description MD

Corrected max length of TRACK2 and updated description
Corrected max length of TRACK3 and updated description
Corrected max length of CHIP_TRACK_1
Corrected max Length of CHIP_TRACK_2
Corrected max length of CHIP NAME
Corrected max length of CHIP_TRACK_1_MSD_CL
Corrected max length of CHIP_TRACK_2_MSD_CL
Updated list of possible CARD TYPEs.
Updated list of possible CHIP TYPEs
No change to file layout.

9.02 4/03/2016 Clarified file naming convention further. IF

No change to file layout.

9.01 18/01/2016 Added documentation about PIN block format, no change to file layout. IF

9 15/12/2015 Corrected File Naming convention

Added new optional tag CHIP_TRACK_1_MSD_CL

8.02 30/04/2015 Changed length and description of BULK_COUNTRY

Increased length of REQUEST_TYPE and added new options for PIN
Mailers

8.01 19/01/2015 Corrections to spec:

Track1 increased to 79

8 9/10/2014 Added PINBLOCK as an optional element in the CARD structure

7 Moved REQUEST_TYPE from <PRODUCT> container to <RECORD>

CHIP_TRACK_1 will be present for Mastercard AND VISA
Detailed contents of Track data
Moved LANG to its correct position

Added new optional tag CHIP_TRACK_2_MSD_CL

6 03/09/2013 Added LANG to CARRIER element IF

Added CARRIER_LOGO_ID to CARRIER element
Added QRCODE to CARD element
Changed all CARRIER elements to allow NULLs
Increased maximum length of Track 1 to show maximum length Thredd
will currently output . N.B. ISO specifications allow for maximum of 79 in
Track 1
Added CHIP_TRACK_1 (only for VISA cards)
Changed COUNTRY from Varchar(20) to char(3) Numeric ISO Country
code
Added CVV1 to sample Track 1 layout

5.01 26/03/2013 Added ORDER_REF to CARDSUM element IF

© Thredd 2023 Card Generation Interface Specification 24

 Version Date Description Revised by

5 08/02/2013 Added new fields to support Bulk Delivery Address IF

4.01 10/09/2012 Replaced <ADD5> with <CITY> in the <CARRIER> element. Clarified IF
Country ISO code.
Added XML closing tags for clarity.

4.0 28/02/2012 Added new fields to support Bulk Delivery, Simplex Line 4, Currency, IF
Thermal Lines 1 & 2, Front & Logo images.
Defined maximum field sizes that were not already defined.

© Thredd 2023 Card Generation Interface Specification 25