Document History

2.1.5

12/06/2025

Added new Transaction XML schema where country and currency codes are removed (see Transaction XML Schema). Removed country and currency codes reference sections.

12/06/2025

Added Mastercard Reason Codes 7680 and 7681. See Message Reason Codes.

30/04/2025

Updated the description of the SchemeSettlementDate element. See Sub-elements and Attributes.

10/04/2025

Added currency code for the Caribbean Guilder currency (XCG) for Curacao and Sint Maartens that replaces Netherlands Antillean guilder (see ISO Currency Codes). Added Curacao and Sint Maartens to the currency list for this new currency.

13/02/2025

Added references to Thredd Portal, our new online portal for managing your cards and transactions.

06/02/2025

For the Transaction XML schema child elements, amended data types and removed child elements that are no longer in use. Amended and removed child elements in various records.

28/01/2025

Updated the description of LocalDateUTC in CardAuthorisation and CardFinancial to indicate that it is the time and date of the matching authorisation. Added LocalDateUTC with examples to Sub-Elements and Attributes.

13/12/2124

Updated FIID Element to indicate that it is not required. See CardChrdBackRepRes

11/12/2024

Updated the maximum length of the location field in the Term element to 128 characters. See Sub-elements and Attributes: Term.

21/11/2024

Added a new attribute called TTI (Transaction Type Identifier) to the Txn element.

Updated minimum length requirement of PAN in <Card> to 14 digits.

Added new ISO currency code: 924.

04/11/2024

Updated the description of the Desc field maximum value to 500 characters. See Sub-elements and Attributes > Desc.

23/07/2024

In the CardChrgBackRepRes element, clarified that FIID, RIID, and ChargebackRefNum are populated only for Mastercard chargebacks.

02/07/2024

Updated the company address.

2.1.4

19/06/2024

Added descriptions of the different types of chargeback records that can be provided in the CardChrgBackRepRes element.

24/05/2026

Changed the ReasonCode field in the CardFinancial element from mandatory to If Applicable.

21/06/2023

Added new values to the CashType attribute. See Sub-elements and Attributes > CashCode.

Added details of Visa Dispute Reason Codes; added Mastercard Reason Codes 1403 and 1404. See Message Reason Codes.

07/06/2023

Updated Operations email address to be occ@thredd.com

27/04/2023

Guide rebrand to new company name and brand identity.

2.1.3

14/03/2023

Added a new attribute called TTI (Transaction Type Identifier) to the Txn element in the CardFinancial record type. See the Txn sub-element.

08/03/2023

Updates to the Transaction XML data schemas to change the data type of PresentmentID from unsigned Int to unsigned Long. Added a new currency code value of 157 (CNH) to the ISOCurrencyCode type in the schema file. See Transaction XML Schema.

28/02/2023

Added Chinese Offshore Renminbi (currency code CNH) to the list of supported currencies. See Currency Codes.

20/02/2023

Updated XML Schema version. Trace auditno attribute changed from required to optional. See PRN-138.

2.1.2

17/02/2023

Updated the description of the Trace element to clarify its usage. See Trace.

Updated the section Matching Transaction XML Records to EHI Records to remove reference to use of Trace element as a unique identifier.

25/01/2023

Update to the description of the XML report file naming convention. See Transaction Data Files.

20/01/2023

Update to description of frequency of XML reports in FAQs section.

01/12/2022

Updated the Copyright Statement.

2.1.1

28/10/2022

The maximum length of the DE94_Txn_Orig_ID field has been updated to 16. See Transaction XML Schema.

27/10/2022

Added a description of the Thredd 16-digit public token.

12/10/2022

Updates to the transaction XML filename format to include details of the applicable Production environment. See Transactional Data Files.

23/09/2022

Update to the table Matching Transaction XML Records to EHI Records.

2.1.0

21/09/2022

New transaction XML schema 1.45: In the CardAuthorisation record, the Apprcode element has been updated to nillable="true"

Removed element: FXConversion

08/09/2022

Added a new Currency Code, SLE, for the new Sierra Leonean leone.

30/08/2022

A new record type called VFC (Visa Fee Collection) has been added to the MasterCardFee element. See PRN-85.

The maximum length of the DE94_Txn_Orig_ID data element has been updated to 16. See PRN-85.

2.0.9

01/09/2022

Updated CardEvent to reflect report handling for CardEvent records that exceed 2GB in size. See PRN-120.

27/07/2022

In the AgencyAccount element, the sortcode and bankacc attributes have been updated to support alphanumeric characters. See PRN-118.

In the CashCode element, the CashType attribute has been updated to include CHAPS. See PRN-117.

05/07/2022

Updates made to Introduction (QMR section) and Transactional Data Files (Sending of Files section).

2.0.8

09/05/2022

Added a link to the Downloads page on the Documentation Portal, where you can view and download upcoming/future schema versions.

06/04/2022

New WalletTransaction element added to the transaction XML. See PRN-100.

In XSD schema file, changed the type of AuthTxnID from unsignedint to unsignedlong;

Added the two-digit country code SS (South Sudan) to the ISOCountryCode list. See Transaction XML Schema. See PRN-111.

For MasterCardFee, ApprovedAgencyBanking, DeclinedAgencyBanking and DeclinedAgencyBanking, the Desc element can be empty (nillable="true"). See PRN-110.

Correction: the FeeClass type of 0 is a legacy option which will never appear in a transaction XMLrecord and reference to it has been removed from the guide.

Updated the description of FeeAmt in the Card Fee element.

2.0.7

16/03/2022

Processing Code (ProcCode) = 39 is now used to identify an Account Verification A type of authorisation transaction which is intended to confirm that the account is genuine and active. Account Verifications are always for a zero amount, so only appear in Authorisation messages and never in clearing messages. transaction. See the TxnCode field in the CardAuthorisation element. See PRN-102.

Clarified that the fee amount (FeeAmt) in the CardFinancial record is the sum total of any rate fee and fixed fee applied to the transaction.

2.0.6

04/02/2022

Removed reference to the ResponseFinancial element in the XML Schema.

04/01/2022

The ReportedToSAFE event type has been added to the transaction XML Schema file.

13/12/2021

The RecordType element has been updated to include a new Visa Fee Collection (VFC) value, and the <DE94_Txn_Orig_ID> element maximum length has increased from 6 to 13. See PRN-85.

2.0.5

19/10/2021

The CardEvent primary element has been updated to include a new ReportedToSAFE event type; this provides a transactionid attribute to identify a SAFE reporting You can report fraudulent transactions to Mastercard by creating a new fraud event in Mastercom, using their SAFE reporting facility (now referred to as the Mastercard Fraud and Loss Database). transaction, but will be blank for other event types. For examples, see the Event sub-element. See PRN-75. 

FXConversion record updated with <FXRateBilled>

2.0.4

04/11/2021

For a Visa purchase with Cashback, Thredd now sends the value of ProcCode as 09 (instead of 00) and includes the cashback amount in the Additional_Amt_DE54 field. Thredd has standardised the format of the Additional_Amt_DE54 element to use the format provided by GCMS IPM / Visa Base 2, which contains only the data (a multiple of 20 characters). See PRN-72.

15/10/2021

Added a new primary element FXConversion to indicate Foreign Exchange (FX) rate conversion. This contains the sub-elements BookingType and BookingStatus.

2.0.3

20/08/2021

15/09/2021

Added a new field <LocalDateUTC> to CardAuthorisation and CardFinancial records. This field contains the LocalDateUTC data that Thredd receives from Mastercard and Visa. See PRN-59.

Added new appendix Load Source, which provides updated details of possible values for the source of a Load or Unload request.

Removed value 0 from the type attribute in the FeeClass element, as this value is no longer supported.

Updates to Card Status Codes to include new values G1-G9. See PRN-48.

2.0.2

26/07/2021

Updates to include clarification on usage of actioncode and responsecode fields in the Response element.

New <PaymentToken> field added to CardAuthorisation and CardFinancial records to help support Programme Manager Apple-Pay Reporting requirements. See PRN-49.

2.0.1

16/06/2021

Updates to include clarification around transaction reporting times and cycle times. See Transactional Data Files.

Information on XML reports available for issuers. See Introduction.

New details of fields to use for matching transaction XML records to EHI records and matching financials to authorisations. See Transaction Matching

The BillAmt rate and the SettlementAmt rate has been updated to show 9 decimal places. See PRN-44.

2.0

25/04/2021

Major revamp to look and feel and organisation of the guide. Rewrite of content to simplify and make the guide easier to use.

Updates to description of the <Amt> field.

Added new element: FXConv in CardAuthorisation and CardFinancial primary elements. See PRN-37.

Change to the values of the TxId field in the CardFee record. See PRN-41.

1.41

29/12/2020

Added new elements Sender and Receiver in CardAuthorisation.

1.40

24/12/2020

Added new RecordType element and other data changes in MastercardFee.

1.39

08/12/2020

Added new BSA element in CardFinancial.

1.38

23/10/2020

18/02/2021

Corrected value of ‘Repeat’ in example provided.

Updated list of cardauthmethods and cardauthentity

1.37

22/10/2020

Removed IssuerReferenceNumber, added ChargebackRefNum

1.36.1

29/09/2020

Banking File data not mandatory.

1.36

21/08/2020

Added new IssuerReferenceNumber element in Chargeback.

1.35

19/08/2020

Added new value2 attribute in Financial and Chargeback.

1.34

27/07/2020

Corrected PAN (Primary Account Number) length description.

1.33

24/07/2020

DEV_REPORTING-396 changes added

1.32

15/05/2020

SettlementIndicator available for MC too.

1.31

06/05/2020

Added new element Additional_Amt_DE54

1.30

04/05/2020

Corrected CardFianncial/AuthID description

1.29

09/04/2020

Added new element SettlementIndicator

1.28

09/04/2020

Added recon field in CardFee, productid in MasterCardFee.

1.27

25/03/2020

New 5 fields added in Chargeback section: SettlementCycle, ReconciliationDate, ReconciliationCycle, Usage and Pending_Billing_Amount

1.26

02/03/2020

Some fields in MasterCardFee that shows Chargeback data can be blank. Updated those details in this revision.

1.25

17/12/2019

Updated inputcapability, authcapability, cardholderpresent, cardpresent, cardinputmethod, cardauthmethod and cardauthentity.

1.24

5/11/2019

Updated Function_Code_024 of MastercardFee

1.23

24/10/2019

Updated datatypes for AuthID, AdjustId, ChgbackRepresId, CardFeeId, TxId, FinID and LoadUnloadId, BankingId

1.22

23/11/2018

Documented Agency Banking-related elements and attributes.

Formatting.

1.21

19/10/2018

Clarified Mastercard-only elements CCAAmount and SettlementAmount

1.20

19/09/2018

Added 4.2.59 - AdjustType

1.19

31/05/2018

Added 4.2.58 - SchemeSettlementDate

1.18

16/04/2018

Updated 4.1.4 – CardFeeId description

1.17

06/03/2018

Updated 3.1.2 – Reporting Content.

1.16

27/02/2018

Removed RCC attribute from Classification.

Altered proccode attribute in TxnCode

1.15

26/09/2017

Updated the Account attribute “no” description

Many different elements added to the MasterCard Fee section so that it matches the current file output.

Added Recon, Settlement, PDS0105, and FunctionCode sub elements for the MasterCard Fee change above.

Changed description of CardFee TxId element.

1.14

16/08/2017

Added new Fee Class Code value 1.

Updated permitted values of Fee Class element “type” and “code” attributes for Card Financials.

Corrected the schedule to daily not Mon - Fri

1.11

21/07/2016

Case of XML Element “Account”, attributes “No” and “Type” changed to “no” and “type”, in all recordtypes (“CardAuthorisation”, “CardFinancial” etc..)

Case of XML Element “Response”, attributes “Approved”, “Actioncode”, “Responsecode” and “AdditionalDesc” are changed to: “approved”, “actioncode”, “responsecode” and “additionaldesc” respectively, in the “CardAuthorisation” record only.

Removed ResponseFinancial element description

Documented memberID attribute of FeeClass

Added CCAAmount to CardFinancial

1.10

26/05/2016

Changed Max Length of CardLoadUnload.MerchCode from 15 to 30.

1.09

28/04/2016

Various minor corrections

1.08

19/10/2015

Documented Mastercard.FeeClass element, including new membered sub-element

1.07

01/06/2014

Updated description of CardFee TxId

1.06

01/03/2014

Added new CardFee FeeClass Code value 6000

1.05

05/04/2013

Clarified use of CardEvent Type element

Added VisaCard to Account Element

Clarified requirement of actioncode, responsecode and AdditionalDesc attributes of Response element.

Clarified Load Type attribute

1.04

22/03/2013

Amended data type of Load Type element

1.03

15/03/2013

Updated SettlementDate definition in CardChrgBackRepRes

1.02

14/03/2013

Moved LoadUnloadId in CardFee. Added CardEvent documentation. Changed ProgramID definition.

1.01

13/03/2013

Added CycleNumber, FeeAmt, FeeClass to CardFinancial Element.