Common Data Format 3

Overview
XML Data Format

26 April 2017
 Notices
Following are policies pertaining to proprietary rights, trademarks, translations,
and details about the availability of additional information online.
Proprietary Rights

The information contained in this document is proprietary and confidential to

MasterCard International Incorporated, one or more of its affiliated entities
(collectively “MasterCard”), or both.

This material may not be duplicated, published, or disclosed, in whole or in

part, without the prior written permission of MasterCard.
Trademarks

Trademark notices and symbols used in this document reflect the registration
status of MasterCard trademarks in the United States. Please consult with the
Customer Operations Services team or the MasterCard Law Department for the
registration status of particular product, program, or service names outside
the United States.

All third-party product and service names are trademarks or registered

trademarks of their respective owners.
Translation
A translation of any MasterCard manual, bulletin, release, or other MasterCard
document into a language other than English is intended solely as a
convenience to MasterCard customers. MasterCard provides any translated
document to its customers “AS IS” and makes no representations or warranties
of any kind with respect to the translated document, including, but not limited
to, its accuracy or reliability. In no event shall MasterCard be liable for any
damages resulting from reliance on any translated document. The English
version of any MasterCard document will take precedence over any translated
version in any legal proceeding.
Information Available Online

MasterCard provides details about the standards used for this

document—including times expressed, language use, and contact
information—on the Publications Support page available on MasterCard
Connect®. Go to Publications Support for centralized information.

©2014 MasterCard. Proprietary. All rights reserved.

Common Data Format 3 Overview—XML Data Format 5 November 2014

Common Data Format 3 Overview—XML Data Format i

Contents
Chapter 1 Introduction to the Common Data Format ................................................................................... 1
Common Data Format 3 Layout .................................................................................................................... 1
Common Data Format 3 Layout Documents ................................................................................................. 1
Chapter 2 Common Data Format Overview ................................................................................................... 3
Common Data Format 3 Overview................................................................................................................ 3
Understanding the XML Schema Specifications ............................................................................................ 3
Special Character Handling ....................................................................................................................... 7
Sending Common Data Format 3 Files to the Global Data Repository ......................................................... 7
Common Schema Error Messages............................................................................................................. 7
Receiving Common Data Format 3 Files from Smart Data .............................................................................. 8
Unique MasterCard Transaction Identifier in Outbound Files.................................................................. 10
Updating Financial Transactions .............................................................................................................. 10
Initial Setup ................................................................................................................................................. 10
General Inbound Common Data Format 3 Formatting Rules ...................................................................... 11
Transmission File Layout.......................................................................................................................... 11
Relationships Between Records in a Transmission File ............................................................................ 11
Record Types................................................................................................................................................ 11
Transmission Records .............................................................................................................................. 12
Organization Records .............................................................................................................................. 12
Specific Record Types .............................................................................................................................. 13
Financial and Transaction Records .......................................................................................................... 13
Dun and Bradstreet Supplier Records ..................................................................................................... 15
Appendix A Frequently Asked Questions.................................................................................................... 16
Appendix B Glossary ................................................................................................................................... 20

Common Data Format 3 Overview—XML Data Format ii

Common Data Format 3 Overview—XML Data Format iii
 Introduction to the Common Data Format

Chapter 1 Introduction to the Common Data Format

This section introduces the common data format 3 layout and the layout documents.

Common Data Format 3 Layout

The common data format 3 (CDF3) layout is the default layout used both for
files coming into the Global Data Repository and for files being shipped out
of the Global Data Repository. If you are a processor or issuer sending files
TO MasterCard, then you are an INBOUND customer. If you are a corporation
or a third-party host for corporations, receiving files FROM MasterCard, then
you are an OUTBOUND customer.
The Global Data Repository processes data 20 hours per day, 6 days per week.
Typically all inbound files are queued for processing immediately. Outbound
Files are queued for processing based upon the File Delivery schedule.
File processing expectations set forth herein may change as products and
programs change. MasterCard reserves the right to change file processing time
frames at any time and provide issuers with any new standards.

Common Data Format 3 Layout Documents

The following documents describe the CDF 3 Layout: the XSD file, the html file,
the inbound sample CDF 3 file, and the outbound samples.

If you send or receive files from MasterCard you must review the following
documents describing the CDF 3 Layout:
NOTE
Thoroughly review all documents to gain an understanding of the CDF 3 XML file.

• The XSD file—The XML schema definition for the CDF file you will either
send to or receive from MasterCard. This file completely describes the
XML file.
• The html file—A more user friendly version of the CDF XSD (schema)
document.
• The change notification document—A listing of the specific changes
implemented in the.given specification
 The inbound sample file (a sample CDF 3 file)—MasterCard recommends
that the sample file be used as a reference in your analysis and development
process.
NOTE
The content of the sample file is for demonstration purposes only and is
not representative of actual data.
• Outbound Samples—Outbound Cycle demonstrates the record types
anticipated after statementing, or the account has cycled. Outbound Mid
Cycle contains the daily portfolio information.
Common Data Format 3 Overview—XML Data Format 1
 Introduction to the Common Data Format

NOTE
Please visit the Global Commercial Product Information Center on MasterCard
Connect to ensure you are using the most current specifications. If you are a
Third Party vendor or a new customer without MasterCard Connect access,
contact [email protected].

Common Data Format 3 Overview—XML Data Format 2

Chapter 2 Common Data Format Overview
This section describes the common data format, sending and receiving Common Data
Format 3 files, initial setup, general inbound Common Data Format 3 formatting rules, and
record types.

Common Data Format 3 Overview

The Common Data Format serves as both a description of corporate card
activity and as the transport medium for that information. The exchange of this
information requires that the relationships between records are maintained
during transmission.
More than 35 record types are defined in the CDF3 specification. Not all of
these record types must be used, but the full complement of records facilitates
a very complete specification of a corporate card user, that user’s organization,
and the transactions against that user’s account. Depending on your needs for
detailed specification of your organization and the transaction types you make
on your corporate cards, you may use only a very few record types or the
entire complement of records available.
There are a limited number of required fields in CDF3. This is not a justification
for sending just those required fields. Any file comprising just the required data
elements will be of almost no use to our mutual customers.

Not every field on every record must be populated, but every field for which
data can be obtained by the issuer/processor must be populated.
The CDF layout provides records to specify organizational entities and to
transmit transactions. Transactions require that the organization be specified
before they can be processed.

Understanding the XML Schema Specifications

The XML Schema Definition for the CDF file describes the requirements for
the CDF3 file.
The example on the next page demonstrates the attributes of the elements.

Common Data Format 3 Overview—XML Data Format 3

 Common Data Format Overview
Understanding the XML Schema Specifications

<xs:element name="BillingType" type="BillingType" minOccurs="1"

maxOccurs="1"></xs:element>
name= The name of the tag in the XML file. In this instance, the name of the tag
is BillingType.
type= The data type restrictions placed on this field. In other words, the acceptable
types and values for this tag. In this instance the data type is BillingType.
minOccurs= The minimum number of times a tag can occur.
maxOccurs= The maximum number of times a tag can occur.

minOccurs and maxOccurs Attributes

Each tag in the XML Schema Document (CDFFileTransmission.xsd) contains
minOccurs and maxOccurs attributes. The minOccurs tells you the minimum
number of tags that must be contained in the file. The maxOccurs tell you the
maximum number of tags that can be contained in the file.

Example 1
<xs:element name="BillingType" type="BillingType" minOccurs="1"
maxOccurs="1"></xs:element>
This notation implies that the tag BillingType is required. There can be one and only
one entry for this tag.

Example 2
<xs:element name="ProcessingCorporateAccount" type="Id19Type" minOccurs="0"
maxOccurs="1"></xs:element>
This notation implies that the tag ProcessingCorporateAccount is not required. There
can be zero to one entry for this tag.

Common Data Format 3 Overview—XML Data Format 4

 Common Data Format Overview
Understanding the XML Schema Specifications

type = Attribute

Each tag in the XML Schema Document (CDFFileTransmission.xsd) contains a

type= attribute. This attribute is used to determine not only the data type and
size, but in some instances, acceptable values.

Example 1
<xs:element name="AccountNumber" type="Id19Type" minOccurs="0"
maxOccurs="1"></xs:element>
The AccountNumber tag has a type of Id19Type. Find the definition of this type in
the CDFFileTransmission.xsd file.
<xs:simpleType name="Id19Type">
<xs:restriction base="xs:token">
<xs:minLength value="1"></xs:minLength>
<xs:maxLength value="19"></xs:maxLength>
</xs:restriction>
</xs:simpleType>
This Id19Type is a simple data type. In this example, the AccountNumber can have a
length between 1 and 19 characters inclusive.
Valid Example: <AccountNumber>549900000000000</AccountNumber>

Example 2
<xs:element name="TransactionDate" type="MasterCardDateType" minOccurs="1"
maxOccurs="1"></xs:element>
The TransactionDate tag has a type of MasterCardDateType. Find the definition of
this type in the CDFFileTransmission.xsd file.
<xs:simpleType name="MasterCardDateType">
<xs:restriction base="xs:date"></xs:restriction>
</xs:simpleType>
This MasterCardDateType is a simple data type. In this example, the TransactionDate
can be a valid date in the CCYY-MM-DD format.
Valid Example: <TransactionDate>2003-01-31</TransactionDate>

Common Data Format 3 Overview—XML Data Format 5

 Common Data Format Overview
Understanding the XML Schema Specifications

Example 3
<xs:element name="DebitOrCreditIndicator" type="SignCodeType" minOccurs="1"
maxOccurs="1"></xs:element>
The DebitOrCreditIndicator tag has a type of SignCodeType. Find the definition of
this type in the CDFFileTransmission.xsd file.
<xs:simpleType name="SignCodeType">
<xs:restriction base="xs:token">
<xs:enumeration value="C"></xs:enumeration>
<xs:enumeration value="D"></xs:enumeration>
</xs:restriction>
</xs:simpleType>
This SignCodeType is a simple data type with a restriction (list of acceptable values).
In this example, the DebitOrCreditIndicator tag can only contain either a C or a D.
Any other values will be rejected.
Valid Example: <DebitOrCreditIndicator>D</DebitOrCreditIndicator>

Example 4
<xs:element name="AmountInOriginalCurrency" type="CurrencyAmountType"
minOccurs="1" maxOccurs="1"></xs:element
The AmountInOriginalCurrency tag has a type of CurrencyAmountType. Find the
definition of this type in the CDFFileTransmission.xsd file.
<xs:complexType name="CurrencyAmountType">
<xs:simpleContent>
<xs:extension base="CurrencyType">
<xs:attribute name="CurrencyCode" type="CurrencyCodeType" use="re-
quired"></xs:attribute>
<xs:attribute name="CurrencyExponent" type="CurrencyExponentType"
use="required"></xs:attribute>
<xs:attribute name="CurrencySign" type="SignCodeType" use="required"></xs:at-
tribute>
</xs:extension>
</xs:simpleContent>
</xs:complexType>

This CurrencyAmountType is a complex data type that consists of many tags.

This field consists of a CurrencyCode, CurrencyExponent and CurrencySign.
Each one of these tags has their own type= that you must look up to determine
the appropriate values.

Valid Example: <AmountInOriginalCurrency CurrencySign=”D” CurrencyExponent=”2”

CurrencyCode=”840”>10938</AmountInOriginalCurrency>
The above example represents a debit amount in the 840 currency of 109.38.

Common Data Format 3 Overview—XML Data Format 6

 Common Data Format Overview
Sending Common Data Format 3 Files to the Global Data Repository

NOTE
The CDF v3.0 XML Schema Document (CDFFileTransmission.xsd) states that no
decimals are to be placed in amount fields. The concept of an exponent is used
in the CDF v3.0 document.

Special Character Handling

XML control characters need to be sent as indicated in the table below. For
example, for a merchant named “Steve & Jose Bookstore” enter this in the XML
file as “Steve &amp; Jose Bookstore.”

Character Reference
& &amp;
< &lt;
> &gt;
" &quot;
' &apos;

Sending Common Data Format 3 Files to the Global Data Repository

Every CDF v3.0 file that is sent to MasterCard is validated against the schema
before it is loaded to Global Data Repository. During schema validation
MasterCard will check your input file and ensure all the data conforms to the
file specifications.
The following items will not pass validation:
• Missing required fields
• Incorrect data length
• Incorrect data type
• Incorrect data format (invalid date format)
• Tags that are misspelled or have incorrect character case

Common Schema Error Messages

Common schema error messages include invalid characters or content errors.

The table describes common schema error messages and the reasons for the
messages.

Common Data Format 3 Overview—XML Data Format 7

 Common Data Format Overview
Receiving Common Data Format 3 Files from Smart Data

Message Reason

Message: Invalid character (Unicode: This error can occur if the files are being
0x0) sent in ASCII rather than UTF-8. Extended
ASCII characters are not recognized in
UTF-8.
Message: Data type error: When checking the error location in the
Type: InvalidDatatypeValueException, file, it is determined that the field is a
Message:Value 'ON' is not in enumeration. country code and customer populated
State/Province in the location instead.

Message: Not enough elements to match Indicates missing mandatory fields.

content model

Message: Not valid for content model Nesting or sequence issue.

Message: Invalid document structure The file may have been sent in EBCDIC
and not ASCII/UTF-8.

Schema failure notices will be sent by e-mail to the issuing processor, with
the error log attached.
MasterCard strongly recommends all issuing processors or enhanced data
sources perform schema validation against their files before sending the files to
MasterCard. This process ensures prompt and efficient resolution of any data
errors and eliminates delays in the corporate customer data being available
in SmartData.

Upon successful schema validation, the MasterCard Global Data Repository

will produce a confirmation report that contains key information to confirm
the successful arrival and processing of the file as well as informing the
Processor of any record(s) that were rejected as invalid, and the reason why
the record(s) failed to load successfully. The issuer can also request a copy of
the confirmation report.

Receiving Common Data Format 3 Files from Smart Data

Consistent with XML coding standards, MasterCard will only export data
element tags to which a valid value has been assigned. If an element tag is not
distributed, then no value was supplied to MasterCard for that element.
Since all processors do not supply data in CDF3 format (MasterCard accepts
legacy formats), outbound CDF3 files may not pass schema validation.
MasterCard makes every effort to standardize stored data, but it is not always
possible based on the data supplied by the processor.

Common Data Format 3 Overview—XML Data Format 8

Common Data Format 3 Overview—XML Data Format 9
 Common Data Format Overview
Initial Setup

Unique MasterCard Transaction Identifier in Outbound Files

MasterCard creates a tag, <MasterCardFinancialTransactionId>, for each

transaction in a file. This field is a unique identifier for the transaction within
the Global Data Repository and can be used to match updates provided in
subsequent files.

Updating Financial Transactions

With the CDF3 format, inbound CDF3 customers can provide updates to
transactions and addendum records that have already been sent to MasterCard.
Enhanced transaction and addendum information received at a later date can
flow through to applications that support updates.
The only requirement for this is that a unique identifier is maintained for a
transaction between the original and each update. To update a specific
transaction, the financial and each addendum record should contain the same
Processor Transaction ID that was received with the transaction originally
and the Financial Transactions Maintenance Code should be “U.” An update
transaction must always contain the transaction and all addendum records
which belong to the transaction. All previous addenda will be dropped so it is
required that each addendum be resent with the transaction.
The following Financial Transaction record fields are not available for update:
• ICA Number
• Issuer Number
• Corporation Number
• Account Number
• Processor Transaction ID
• Transaction Date
• Posting Date
• Amount in Posting Currency
• Amount in Original Currency
• Credit/Debit Indicator

Initial Setup
When a new issuer is implemented in the Global Data Repository, the issuer
information will be provided and manually entered in the system. The CDF3
Issuer Information Type can be used to update issuer information, but not to
create a new issuer. A hierarchy address record can be used to add or change
address information for an issuer.

Common Data Format 3 Overview—XML Data Format 10

 Common Data Format Overview
General Inbound Common Data Format 3 Formatting Rules

NOTE
For every issuer, one hierarchy address record with the “Primary Address Flag”
set to ‘Y’ must be sent in. Other hierarchy addresses should have the “Primary
Address Flag” set to ‘N’.

All companies and accounts must be sent in CFD3 and created in the Global
Data Repository prior to transmission of transactional data.

General Inbound Common Data Format 3 Formatting Rules

Indicators with the option of Yes (Y) or No (N) will default to No, if not
supplied.
All addendum amounts will be in original currency, with the exception of
Portfolio (record 4420) and Authorization Limit (record 4430). The amounts
supplied for these records will be in the currency agreed upon by the Processor
and the Issuer.
Dates and times must follow the formatting supplied. Partial date, dates
formatted incorrectly or zeros, except when specifically allowed, are invalid.
If an amount is supplied, the associated fields of currency, exponent and
debit/credit indicator must also be supplied when these fields are present in
the record layout.
The file has been specified as an XML document. If a data supplier is unable
to supply a non-mandatory data element populated with a valid value, then
there is no need to send a default value, or a blank, a zero, or a null value.
Simply, do not send the XML field tag.

Transmission File Layout

CDF3 files are exchanged as XML between processors, MasterCard, and

customers. The CDF Transmission File element in CDF3 XML consists of
an ordered nesting of records. The order and nesting of these records is
established by the CDF3 schema file (“CDF Transmission File.xsd”).

Relationships Between Records in a Transmission File

The nesting of records in a transmission file determines their relationship.

Records can be thought of as describing the organization or describing
transactions of that organization. This categorization will help in describing
different requirements on the particular elements of a transmission file.

Record Types
The records that comprise the CDF3 Layout specification have been broken into
sections that describe the general purpose of these records.

Common Data Format 3 Overview—XML Data Format 11

 Common Data Format Overview
Record Types

They fall into the following categories:

• Transmission Record Elements—Header and Trailer (1000 and 9999)
• Organizational Record Elements —Hierarchy (3000 through 4xxx)
– IssuerEntity for Issuing Processors
– EnhancedDataEntity for Third Party Global Data providers
• Transaction Record Elements—Financials and Adjustments
• Dun and Bradstreet Supplier Elements—Demographic and socioeconomic
merchant information available based on transactional history. (6xxx)
Please view the sample CDF 3 XML file that was provided for more detailed
information on how the different records relate to each other.

Transmission Records
Each exchange of information in the CDF format must be encapsulated between
two Record Types: the Transmission Header Record and the Transmission
Trailer Record.

Record Type
TransmissionHeader_1000
TransmissionTrailer_9999Type

A transmission file will always contain one Transmission Header and one
Transmission Trailer bounding the organizational, transaction, and/or the
summary records. The Transmission Header record and Transmission Trailer
Record maintain information significant to the exchange of data into Smart Data
and out of it. This information includes the Identification of the source of
the data, version of the data format, period covered by the data as well as
count and summary information used to validate the contents of a received
transmission file.

Organization Records

To successfully represent the significance of corporate card activity, information

over and above any particular transaction is required. CDF provides element
definitions that allow for the initial population of this information and for
the ongoing maintenance of this information. We can call this information
“Maintenance Driven” in that we do not expect it to change each cycle we
process transaction data.

Common Data Format 3 Overview—XML Data Format 12

 Common Data Format Overview
Record Types

CDF imposes minimum requirements for basic organizational information. There

are also additional Record Types to represent more detailed organizational data.
Organizational information describes the issuer, corporation, organizational
points within the corporation, corporate card accounts, fleets, drivers, and
attributes of these entities.

Specific Record Types

• IssuerInformation_3000Type—This record can be used to modify Issuer

information, but cannot be used to create a new issuer. Creation of Issuers
for a client is performed at certification time.
• CorporateInformation_4000Type—The issuer for this corporation must
have been established before the submission of this record. A Corporation
may have zero or more Organizational points defined within it. Accounts
can exist at the corporation level or the Organizational Point level—either is
considered to be an account within the corporate organization.
• OrganizationPointInformation_4100 —This record mirrors a corporate
information record but includes reports-to information.
• AccountInformation_4300Type—An account record is required before
transactions against that account can be processed.
• HierarchyAddress_4410Type—This record is not mandatory within each
file, yet is required to be supported. It is expected that a minimum of one
address should be provided for every level of hierarchy supported.
• Portfolio_4420Type—This information should be sent only once a month,
following statementing or account cycle.
• DailyPortfolio_4450Type—This entity represents the daily status of the
account and may be supplied during an accounts cycle period.
• Custom Hierarchy—This record supplies a location to provide client specific
information that does not have another XML entity or tag defined.

Financial and Transaction Records

Transaction elements represent individual financial transactions against

accounts. Each account against which a transaction occurs must already have
been transmitted to the Global Data Repository. Merchant initiated transactions
(financials) and issuer initiated transactions (adjustments) apply only to
cardholder accounts. All monetary amounts in all addenda records are to be in
posted currency.

There are several types of additional detail depending on the particular

transaction. CDF facilitates the transmission and representation of this
information by supplying several Record Types designed to embody the
significance of a particular account or transaction type. The Financial
Transaction can stand on its own, but also serves as the root for all additional
addendum information.

Common Data Format 3 Overview—XML Data Format 13

 Common Data Format Overview
Record Types

Specific Record Types

• PassengerTransportDetailGeneralTicketInformation_5020Type—The first
5020 Passenger Transport Addendum record for the transaction must be
related to the preceding 5000 Financial Transaction.
• PassengerTransportDetailTripLegData_5021Type—The first 5021 Passenger
Transport Detail Trip Leg Addendum record for the transaction must be
immediately preceded by a Passenger Transport Detail Addendum record.
• TemporaryServicesDetailAddendum_5080Type—The CorporateCardLineIt-
emDetail_5010 Corporate Card Line Item Detail Addendum record should be
sent in conjunction with the Temporary Services Detail Addendum record.
• GlobalInvoice_5100Type—The line items of a global Invoice are
represented by Corporate Card Line Items linked to a transaction having the
Invoice number as the Unique Invoice Number.
• TaxAddendum_5300Type—A Tax addendum element can be associated at
varying levels of a transaction, from the transaction, to the summary
addendum, to the Line Item detail. There may be zero, one, or many Tax
records related to a specific bankcard transaction. Each Tax record is linked
to a transaction by the Unique processor Reference Number. If a Detail Line
Addendum is present then the Tax Record will follow that record and have
the next Addendum Sequence Number.
• Custom Financial Data Record—The Custom Financial Addendum Record
carries details about a financial transaction for which the issuers have
defined fields to be carried that are not included in a specific addendum
record. It is generally used when new detail is needed for which a specific
addendum record has not yet been created. The first Custom Financial
Addendum record for the transaction must be preceded by a 5000 Financial
Transaction record. These records are frequently seen in outbound file
deliveries for customers who participate in one of the MasterCard Enhanced
Data Programs.
• FinancialAdjustmentRecord_5900Type—The financial adjustment element
is associated to an account just as a financial transaction, and is to be used
for all Issuer related amounts. While the record is not mandatory in each
file, it is required for the card program, to fully reflect payments and other
non merchant amounts.
• AuthorizationTransactionEntity - AuthorizationTransaction_5910–Rep-
resents a declined transaction, and while not used by most Third Party
expense systems, issuers may use this record for other reporting purposes.
• UnmatchedLodgingSummaryAddendumEntity (8003 and 8031)—The
Unmatched Lodging Summary Addendum Record provides the summary
information about a financial transaction associated with lodging
accommodations. The record format is identical to the 5030 Lodging
Summary Addendum Record. The 8031 format is identical to the 5010
Line Item Summary Record. An Unmatched Lodging Summary Addendum
Record will not be preceded by a corresponding 5000 Financial Transaction
record. These records are only available to a few custom programs, and are
outbound only.

Common Data Format 3 Overview—XML Data Format 14

 Common Data Format Overview
Record Types

• UnmatchedPassengerTransportEntity (8002 and 8021)—The Unmatched

Passenger Transport Entity provides summary and trip leg information about
a financial transaction associated with passenger travel. The record format is
identical to the 5020 Passenger Transport Detail General Ticket Information.
The 8021 format is identical to the 5021 Passenger Transport Detail Trip Leg
Data record. An Unmatched Passenger Transport Entity will not be preceded
by a corresponding 5000 Financial Transaction record. These records are
only available to a few custom programs, and are outbound only.

Dun and Bradstreet Supplier Records

Dun and Bradstreet supplier records represent supplier demographic and

socio-economic information provided by Dun and Bradstreet, most frequently
used by North American customers. This data is available by requesting
enrollment in the Supplier data program. Only data for a merchant that a
customer has frequented will be provided in these records.

Common Data Format 3 Overview—XML Data Format 15

Appendix A Frequently Asked Questions
This appendix provides frequently asked questions and answers about CDF3.

The answers to these frequently asked questions may help you understand
Common Data Format 3 (CDF3).
Why is CDF3 an XML file?
The decision to go with an XML format was based on the following factors:

• The fast-growing, broad acceptance of XML as a standard data format

• The flexibility for adding new data elements to an XML Schema, in a
fast-changing business environment
• The removal of the need for issuers/processors to populate every field in
the layout, whether it is relevant or not. While XML files are inherently
larger than untagged formats, there is a great savings in the development
and certification costs of an XML format file as well as the removal of the
redundancy of providing blank, zero, null and defaulted field values
• The human readability of XML will help expedite transmission trouble
shooting
At first glance, the specifications can appear very intimidating. 3500 plus data
elements is a significantly greater number of elements than is seen in most
file formats in the credit card industry.
The best place to begin is to identify which data elements are applicable to the
system which is sending data to MasterCard. If single data elements or whole
groups of data elements cannot be supplied then they may simply be ignored.
Because the XML tags will not be sent for elements that cannot be supplied,
there is no need for default values in those fields.
What does the data look like?
Where applicable, ISO standards apply to fields in this file. Many acceptable
values for fields are listed in the schema field definitions section of the layout
document.
Is the CDF v3.0 file case sensitive?

Yes, both the open and close tags (fields) must match exactly to the XML
Schema Document (CDFFileTransmission.xsd).

Example
If the schema states the following:
<xs:element name="TotalNumOfAccounts" type="Numeric10Type" minOccurs="0"
maxOccurs="1"></xs:element>
The following would be rejected (reasons in parentheses)
<TotalnumofAccounts>10</TotalnumofAccounts> (lower case “n” in num)
<TotalNumofAccounts>10</TotalNumofAccount> (missing “s” in closing tag)

Common Data Format 3 Overview—XML Data Format 16

 Frequently Asked Questions

ProcessorNumber is an 11 digit number. Our processor number contains

less positions. What exact data should we send?

The ID11Type field is a minimum length of 1 and a maximum length of 11.

If your Processor Number is 1111, you may send 1111 or you may send
00000001111, so long as you meet the minimum and maximum limitations.
May we change the XML version or encoding format in the CDF 3 file?
No, the first two lines of the CDF 3 file must be sent as identified in the Sample
File, as below.

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

<CDFTransmissionFile xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance"

The sequence numbering in the sample file does not look sequential.
Does it need to be?

Sequencing is used for error reporting and each instance should be unique
throughout the file. The sequence number of the hierarchyrecordheader may
be a continuation of the Sequence Number in the Financial Record Header.
Is the data in DebitOrCreditIndicator disregarded in a reversal or
adjustment? Is a Retail Sale and Retail Sales Reversal both debit, or is the
first one debit and the other one is credit?
If the transaction increases the amount the cardholder will owe, it is a debit.
If the transaction decreases the amount the cardholder will owe, it is a credit,
regardless of the transaction type.
May we use the AcquirerReferenceData as the ProcessorTransactionID?
No, it is not recommended. AcquirerReferenceData is assigned by the
Acquirer when the transaction is processed by the Merchant’s bank, and is not
guaranteed to be unique among all Acquirers. It is recommended that the
Processor Transaction ID contain enough data to segregate it from all other
MasterCard Transactions in their system, perhaps by incorporating the ICA,
processing date and a timestamp.
In the TelephonyBillingDetail_5121, the tags CallToCountryCode and
CallFromCountryCode are defined as 3 character ISO Country Codes,
but IPM message PDS 0638s3 and 0644s3 are both 40 position fields.
Also, CallToStateProvince and CallFromStateProvince do not match IPM
mapping. Is there a conversion table or should it be consistent with the
IPM definitions?

No, there is no conversion chart. As these are not mandatory tags, if the data
(or a way to convert it) is not available, do not provide the fields.

Common Data Format 3 Overview—XML Data Format 17

 Frequently Asked Questions

How do I reverse a transaction?

Edit the reversal flag in the 5000 financial to an “R”. Change the debit/credit
indicator to the reverse of the original transaction. Also change the
TransactionAmount debit/credit indicators to the reverse. Resubmit transaction.
How do I handle fields, such as the Account Number, that expanded from
a 16 position numeric field to a 19 position alphanumeric field?

If the field was established in GDR prior to CDFv3, the field was decimal
aligned and zero filled. The field is now defined as alphanumeric, meaning
that it can handle both numeric and alpha characters, so, to match the field in
the database, the first 16 position must be numeric and the remaining three
characters must be spaces.
If the field is new to the database, configure the field any way you wish, but,
consistency is the key ingredient.
Are there default values for any of the tags?
Many fields have default values identified if not provided. If the data is available
in the card management system, it should be provided in CDF3. Default values
cannot be suggested for processor specific fields such as ICA, IssuerNumber,
AccountNumber and CorporationNumber.
Default values are identified in the schema in the following manner.
<element name="StateProvince" type="StateProvinceType" default="–"
What is the FileReferenceNum?

FileReferenceNum is a unique number used to identify the inbound file. One

suggested way to populate is ICA + ProductCode + CCYYMMDD + HH:MM:SS.
What type of data is to be populated in alternate name line 1 and similar
fields?
Alternate Name Lines and Name Locale Codes are used for customers who wish
to supply the data in two languages.
My vendor does not accept full account numbers, so my files are masked.
How can my vendor identify which account to relate the transaction
back to?

Beginning with CDF Schema Version 10.01.00.00, MasterCard will append the
EmployeeID to all financial and adjustment transactions. Vendors will need to
store the hierarchy records that contain the employee id for future reference.

Common Data Format 3 Overview—XML Data Format 18

 Frequently Asked Questions

How many fraction digits should I provide for the conversion rate in the
CDF3 file?
The Conversion Rate tag is provided in the CDF file to identify the rate used
for conversion from original currency to the other currency. The other currency
can be Posted currency, Billing currency, National currency, etc… Schema
allows a maximum of 9 digits in the exponent of the conversion rate tag.
Mastercard requires at least 7 fraction digits after the decimal to be included in
the conversion rate if conversion between two different currencies is involved.
This requirement is imposed to ensure better data quality and minimum
difference between the amount calculated using the conversion rate and the
amount presented in the CDF file after conversion.

Why does a CDF3 file submitted to the GDR reject due to special
characters when that same data passes through Clearing?
There are differences between what characters the GDR will accept and what
the GCMS system will allow when processing a Clearing file. The GDR and
GCMS are separate systems with different purposes. It is known that the GDR
is more strict than the GCMS when it comes to supporting special characters
and other things that may cause a CDF file to reject such as a line feed or
carriage return in an unexpected place. This is to ensure better quality of the
data which is key to the purpose of the GDR. Entities which submit CDF files
to the GDR were certified and must follow the requirements of the CDF format
regardless of what was submitted through the GCMS Clearing system.
Therefore, it is the responsibility of the issuer/processor to ensure the CDF files
meet the required criteria and specifications.

The issuer/processor can take steps to limit the impact of this situation. They
should refer to CDF schema requirements. They should be careful when
creating the CDF files and possibly add some type of scanning processing to
alert them of problematic characters. They should keep track of the fields and
values that are causing them issues and account for them in process. They
should pay special attention to carriage returns and line feeds.

These are some fields which have the potential to contain problematic
characters: Card Acceptor ID, Card Acceptor Name, Card Acceptor Street
Address, Card Acceptor City, Line Item Description, Customer Code, Unique
Invoice Number.

Common Data Format 3 Overview—XML Data Format 19

 Glossary

Appendix B Glossary
This appendix contains the terms related to the Common Data Format 3 Overview and their
definitions.

The table contains the terms related to the Common Data Format 3 Overview
and their definitions.

Term Definition

Adjustment A financial charge applied to a credit card that did

not occur at a merchant. For example, a yearly
maintenance fee.

Cardholder A Corporate credit card holder

Common Data Format The standard file format that is sent from the
(CDF) processors/customer to the Global Data Repository
and ultimately to downstream applications such as
the Smart Data suite or other applications. This file
contains both hierarchy information as well as financial
transaction information.
Company An entity that contracts with an issuer to receive
corporate cards for its employees. A company is
uniquely identified by its Issuer and Company number.
Company Group A grouping of separate companies to look like a
single company. Often these companies have separate
issuers and are part of a multinational company.

Financial (Transaction) A grouping of separate companies to look like a

single company. Often these companies have separate
issuers and are part of a multinational company.

Global Data Repository (GDR) The Corporate Products data repository. The Global
Data Repository (GDR) receives data from processors
and determines which downstream application to send
the data to.

Hierarchy A term for a company’s organizational chart. This

includes Org Points and Cardholders (credit cards).

Issuer An entity that issues cards to companies that use

corporate cards. An issuer is uniquely identified by the
combination of ICA and Bank Number.
Org Point An organizational point in a company’s hierarchy
(organization chart). For example, Account Payables,
GTO, Corporate Products

Smart Data A product suite where corporate card holders can view
and analyze their spending and the data loaded in the
Global Data Repository (GDR)

Common Data Format 3 Overview—XML Data Format 20

 Glossary

Common Data Format 3 Overview—XML Data Format 21

 Glossary

Term Definition
XML Extensible Markup Language, an industry standard for
data exchange between systems
XML Schema Defines an implementation of XML for representing

Common Data Format 3 Overview—XML Data Format 22