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: EHI 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 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

Online (HTML)

PDF

What's Changed?

Version

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

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

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.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

File Name

What's Changed?

Version

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