External Host Interface (EHI) Guide (XML version) for Single Message Systems

This guides describes the Thredd External Host Interface (EHI) and provides technical specifications on how to integrate your systems to EHI, using XML. It also includes information around using EHI for Single Message Systems (SMS). You should read this guide if you are using EHI for payment transaction authorisation and/or subscription to the EHI real-time payment transaction data feed.

This guide is only relevant to customers interested in issuing cards in countries that operate single message system (SMS) networks (e.g., in the US). Please speak to your Account Manager for further details.

Topics covered: ClosedEHI version control, EHI modes, Transaction Flow Scenarios, Transaction Types, Single vs Dual Message Systems, EHI Configuration Options, Integration steps, Processing EHI Transactions, Transaction Matching, GetTransaction Message Fields, GetTransaction WSDL and Example Messages

Current Version

The current version is available in both Online (HTML) and PDF format.

Online (HTML)

PDF

What's Changed?

Version

External Host Interface (EHI) Guide (XML version) including Single Message Systems

Added new C09 and F09 Scheme Transaction Identifier Values. See PRN-310.

Added MCCs 3306, 3884, 3885 and 3886 to Merchant Category Codes. See PRN-311.

Added enhanced validation the Additional_Data_DE48 field, where if Mastercard indicates that systemic controls were not applied then Thredd will automatically decline the transaction. This is shared with the customer using sub-element 71 (SE71) field. See PRN-316.

Added new P73Scheme Transaction Identifier Values to support merchants enrolled in the Global Reach Acquiring Program. See PRN-308.

Revised the description of response codes 91 and 92 to clarify the behaviour for Gateway Processing customers. See Response Status Values.

Added more details for each of the EHI operating modes. See EHI Operating Modes.

Corrected Step 2 of Scenario 1: Maximum preauthorisation example and Scenario 2: Nominal preauthorisation example for AFD Authorisations. See Transaction Flow Scenarios: AFD Authorisations.

Added functionality to support edge cases where a programme has inputs from multiple sources. See EHI Configuration Options.

Added the EHI Version 5.5 WSDL to GetTransaction WSDL.

Added Z5 and 1A response status codes. See Response Status Values and Resp_Code_DE39 Values.

Updated the default Timeout after setting to 800 miliseconds. See EHI Configuration Options.

Added SenderOrganizationName and ReceiverOrganizationName fields to comply with Mastercard Send transaction enhancements on participant data. See SenderData and ReceiverData Fields and PRN-290.

Included new Transaction Identifier code from Mastercard (P72) to identify other speciality merchants. See Scheme Transaction Identifier Values and PRN-294.

Added Transaction Link Identifier fields of NetworkTransactionId2,NetworkRelatedTransactionId, and NetworkLinkValidation to the GetTransaction message fields. Updated the EHI Versions page to include these new fields for 5.5. See GetTransaction Message Fields and EHI Versions Continued and PRN-291.

5.5

Older Versions

Older versions are available in PDF format only.

File Name

What's Changed?

Version

External Host Interface (EHI) Guide (XML version) including Single Message Systems 5.4 (No PDF available)

Updated the description of the P70 Mastercard Scheme Transaction Identifier value, and added the P76 Mastercard Scheme Transaction Identifier value. See Scheme Transaction Identifier Values and PRN-277.

Added R0, R1 and R3 response codes to support VISA subscription management. See Response Status Values and PRN-284.

Removed support for CVV2 result codes C, D, K, and L to align with Visa’s updated Field 44.10 CVV2 response code mandate. See Visa_ResponseInfo_DE44.

EHI version 5.4 now released for general availability. See EHI Versions.

5.4

External Host Interface (EHI) Guide (XML version) including Single Message Systems 5.3 (No PDF available)

Added new MCCs (Merchant Category Codes) as part of Visa and Mastercard updates to comply with ISO standards. See Merchant Category Codes.

Added links to the STIP Balance Update endpoint in the API Hub. See EHI Operating Modes.

Amended amount sign examples to ensure correct credit and debit information appears in the table. See Examples of Amount Signs.

Corrected the match criteria for an Authorisation Advice. See Transaction Matching Criteria.

EHI version 5.3 now released for general availability. See EHI Versions.

5.3

External Host Interface (EHI) Guide (XML version) including Single Message Systems 5.2 (No PDF available)

Added support for Tokenization Authentication Framework (TAF) as an entry for the Cardholder Authentication Method. See GPS_POS_Data field.

Amended an incorrect link to the Response _Source_Why and Message_Why page in the Incremental Authorisation FAQ item. See Q. What is an Incremental Authorisation and how do I identify it?

Added new Mastercard Advice Reason code for Mastercard Send or other transaction blocking services. See Positions 1-3 Advice Reason Code.

Updated the description and examples of Financial Notification messages to indicate that the acknowledgement in the response is mandatory and that the response status is optional. See EHI Connections and Messages:Types of EHI Messages and Processing EHI Transactions:Responding to Financial Notifications.

Added a new page in the appendix for Scheme Transaction Identifier values for Visa and Mastercard.

Provided further details of transaction flows for Automated Fuel Dispenser (AFD) transactions. See Transaction Flow Scenarios: AFD Authorisations.

EHI version 5.2 now released for general availability. See EHI Versions.

5.2

External Host Interface (EHI) Guide (XML version) including Single Message Systems 5.1

Added the Remote Terminal value to subfield 10 in GPS_POS_Capability and subfield 49 in POS_Data_DE61. See GPS_POS_Capability Fields and POS_Data_DE61 field.

Added clarification related to how Additional_Data_DE48 field is passed through for scheme transaction risk scores. See GetTransaction Message Fields.

Added a new value of S, Frictionless flow, Smart attempts, to the GPS_POS_Data field, position 15, 3D secure authentication method. See GPS_POS_Data field.

Added a Network Fee section to the FAQs to explain acquirer and issuer transaction-related network fees.

Added a note in the field description for ICC_System_Related_Data_DE55 that the field applies to both Visa and Mastercard (see GetTransaction Message Fields).

EHI version 5.1 now released for general availability. See EHI Versions.

Added new field descriptions for SchemeTransactionIdentifier, TokenUniqueReference, and PaymentTokenPan to GetTransaction Message Fields. See GetTransaction Message Fields.

Updated examples to include the new fields: SchemeTransactionIdentifier, TokenUniqueReference, and PaymentTokenPan. See Example Authorisations for Mastercard Cards and Example Authorisations on Visa Cards.

5.1

External Host Interface (EHI) Guide (XML version) including Single Message Systems 5.0.17

Added Z5 and 1A response status codes. See Response Status Values and Resp_Code_DE39 Values.

Added a new value of S, Frictionless flow, Smart attempts, to the GPS_POS_Data field, position 15, 3D secure authentication method. See GPS_POS_Data field.

Updated the list of Merchant Category Codes (MCCs) to include MCCs 3304 and 3841-3853. See Merchant Category Codes.

Added a note to clarify support for Master Virtual Cards (MVCs) on EHI Cooperative Processing (mode 2) with approve with load. See EHI Operating Modes: Approve with Load.

Removed references to EHI mode 5, which has been decommissioned.

Added additional information to the Transaction Matching section on matching for incremental authorisations and revised the FAQ on incremental authorisations and how to identify them.

Added a note to the description of Additional_data_de48 to clarify the usage of this field. See GetTransaction Message Fields.

Added further details on the use of the MerchantAdvice field and use of Merchant Advice Code 03. See GetTransaction Message Fields: MerchantAdvice. See also the FAQs: What is the MerchantAdvice field and how is it used?

Updated the example for POS_Date_DE13. Provided more details of how traceid_lifecycle is constructed. See GetTransaction Message Fields.

Clarified the description of multi_part_txn_final. See GetTransaction Message Fields.

Added notes to clarify the use of the SubBIN field for 6-digit and 8-digit BINs. See GetTransaction Message Fields.

Updated the FAQs with additional information on incremental authorisations and how to identify them.

Added EHI response codes 12 and 15 to the Response Status Values page. Revised the description of response code 57. Removed card status code 57 from the Card Status Codes page. See PRN-220.

The Matching_Txn_ID field in EHI is now populated with data for the following types of transactions:

Presentments, Authorisation Reversals, Incremental Authorisations and Incremental Authorisation Reversals. See GetTransaction Message Fields. See also PRN-224.

Updated the description of the Settlement_Date field. See GetTransaction Message Fields.

Added digital asset categories, for example Central Bank Digital Currency (CBDC) or tokenized deposits, to the list of POS codes. See Position 4 – Special Condition (existing debt) in Visa_POS_Data_DE60.

Added the following codes for device binding that supports FIDO: 3749 and 3760. See Reason ID for an Authorisation.

Added two new Visa response codes: 5C - Transaction not supported or blocked by issuer and 9G - Blocked by cardholder, contact cardholder. See Response Status Values.

Added Response Code 72 and 46 to the Response Status Values and the Resp_Code_DE39 pages.

5.0.17

External Host Interface (EHI) Guide (XML version) including Single Message Systems 5.0.16

Multiple EHI endpoints functionality as been deprecated. See EHI Configuration Options.

Updated descriptions and examples for How to handle processing errors due to invalid characters. See Troubleshooting FAQs.

Added extra values 100 and 101 for ‘Message_Why’ field in Appendix A.26 (Response_Source_Why + Message_Why). See Response_Source_Why + Message_Why.

Added details of how to set up multiple EHI endpoints (URLs). See EHI Configuration Options.

Updated the description of the 9030 reason code in the Visa_STIP_Reason_Code field.

Added references to Thredd Portal, our new web application for managing your cards and transactions.

Added 3169 RIYADH AIR to Merchant Category Codes.

Added the V1045D0082 tag, 35AN Plan Registration System Identifier, to the Misc_TLV_Data Field.

Added a note to indicate that the functionality to update the balance in Mode 4 (Gateway Processing with STIP) is currently only available via SOAP Web Services. See EHI Operating Modes.

Updated the format of the Acquirer_Reference_Data_031 field to AN(8,23). See GetTransaction Message Fields. See PRN-200.

Added new Reason Codes for authorisation. See Reason_ID.

Updated AVS Results page. Removed unused codes, and clarified address and postcode/zip code results for US and non-US addresses.
Updated the description of response code 61 to remove the previous restriction on Visa usage, as this code is now supported by Visa. See Response Status Values.

Added FAQ item for Mastercard STIP. See General FAQs.

Added details of additional processing codes available on the STAR Network via Mastercard Network Exchange (MNE). See Processing Codes.
The inclusion of the Merch_Country field is typically Optional, but may be mandatory in certain cases, depending on the program or service being processed. See GetTransaction Message Fields.

Added 3437 CITE RENT-A-CAR to Merchant Category Codes.

Added notes to clarify that some credit/refund transactions may be reported as follows:

  • Visa: MTID ‘05pp’, Txn_type 'P' (with processing code 20xxxx).

  • Mastercard: MTID ‘1240’, Txn_type 'P' (with processing code 20xxxx).

See Transaction Matching.

New FAQ added, explaining how fees are applied and reported for declined transactions. See the FAQs.

Clarification that response code 96 may trigger card Scheme Stand-In Processing (STIP) for both Visa and Mastercard, depending on your STIP setup. See Response Codes.

Added sort functionality to the tables in the online guide version. Revised the GetTransaction WSDL example.

Added "U - No data received" to the list of possible AVS Results.

Updated the description of Txn_GPS_Date. See GetTransaction Message Fields.

Updated the company address.

5.0.16

External Host Interface (EHI) Guide (XML version) including Single Message Systems 5.0.15

Correction — an Automatic Authorisation Reversal message should have an MTID value of 0100. See Transaction Matching and GetTransaction Message Fields.

Clarification on use of the 3-digit country code for Romania. See Country Codes.

Added a new value to the GPS_POS_DATA field position 32, to indicate, whether the acquirer requested a 30-day clearing extension (Visa Only). See GPS_POS_Data Field.

Revised description of the usage of the 0101 A Authorisation Repeat message (Visa Only). See Transaction Matching.

Added descriptions of usage of positions 27-31 in the GPS_POS_Data field. See GPS_POS_Data Field.

5.0.15

External Host Interface (EHI) Guide (XML version) including Single Message Systems 5.0.14

Added support for Single Message Systems. See Dual vs. Single Message Systems.

5.0.14