External Host Interface (EHI) Guide (JSON version)

EHI Guide 5.0.16 (JSON version)

Multiple EHI endpoints functionality has 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.

Added new processing codes for Credit Account Status Inquiry (ASI) and Debit ASI to Transaction Codes.

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

Corrections to JSON tokenisation examples: ACN, TCN and TEN messages should have Txn_Type = J. ACN messages should have an MTID = 0120, while TCN and TEN messages have an MTID = 0620. See GetTransaction Example Messages.

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.

Added Incremental Authorisation examples. See GetTransaction Message Fields.
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 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 examples of tokenisation messages to the GetTransaction Example Messages.

Updated AVS Results page. Removed unused codes, and clarified address and postcode/zip code results for US and non-US addresses.

Added FAQ item for Mastercard STIP. See General FAQs.

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

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.

EHI Guide 5.0.15 (JSON version)

Removed the MTID value of 0100 from the Automatic Authorisation Reversal message on the Transaction Matching and GetTransaction Message Fields pages. 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.

Updates to field descriptions in JSON Data Types and EHI Fields.

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.

EHI Guide 5.0.14 (JSON version)

Added a note to state that EHI feeds in JSON cannot send fields to externally hosted systems where the data values are blank. This differs from EHI data feeds for XML that allow the sending of fields with blank values. See JSON Data Types and EHI Fields.

New terminology introduced around EHI modes: Gateway Processing (mode 1), Cooperative Processing (mode 2), Full Service Processing (mode 3) and Gateway Processing with STIP (mode 4). See EHI Modes.

New Merchant Category Code (MCC) added: 3168 Hainan Airlines (as part of Visa mandate 2024 Q2 VISA Article 2.5 Changes to Merchant Category Codes and Response Code). See Merchant Category Codes.

Added additional processing codes and account types now supported by Visa (as part of Article 2.1 Changes to Support Global Processing Alignment for Issuer). See Processing Codes. For more information, see PRN-179.

Clarified how the transaction status of Cleared (C) and Settled (S) impacts the card balance. See Transaction Status Codes.

Correction to description of the processing code for ASI transactions listed in the FAQs section. Should be 39.

Added examples of Financial Reversals (1240 type E messages). See GetTransaction Example Messages.

Updated the list of values that can be returned in the Visa_ResponseInfo_DE44 field position 5 (CVV/iCVV/dCVV result). See Visa_ResponseInfo_DE44.

Added details to clarify the usage of the Resp_Code_DE39 field. See GetTransaction Message Fields.

Clarified usage of the Auth_Code_DE38 field: an authorisation code is generated for both approved and declined authorisations. See GetTransaction Message Fields.

Added a new page to describe the HTTP header fields in EHI request and response messages. See HTTP Message Format.

Added a note to clarify that the EHI message response should not contain the value "null" in any response fields where EHI is expecting a numeric value, as this may result in EHI declining the transaction. See Response Message Fields.

EHI Guide 5.0.13 (JSON version)

Added details of how to use the Resp_Code_DE39 field when returning a decline response to Thredd. See the appendix Resp_Code_DE39 Values

Added MCC code 5262 to the Merchant Category Codes page. See Merchant Category Codes.

Correction to matching logic table for transactions of type 1240 N. See Transaction Matching.

Added details to clarify that the field PaymentToken_creatorStatus can contain “ “ or be empty when no value has been provided. See Payment Token Fields.

In the section Checking fields used for 3D Secure Authentication, added a note and reference to the PSD2 and SCA Guide.

In the GetTransaction Message Fields section, added information on the interchange fee received in the Interchange_Amount_Fee and Interchange_Amount_Fee_Settlement fields.

EHI Guide 5.0.12 (JSON version)

In the GetTransaction Message Fields section, updated the Request Message Fields headings to clarify whether this applies to authorisation, financial or non-card network messages.

On the GPS_POS_Data field page, fixed the link to the Card Present Indicator section.

Added further information describing the use of transaction processing codes 01,02,11, 12, 21, 26, 28 and 39. See Processing Codes.

Added a new section describing implementation of Dynamic CVV2 functionality. This section is also available as a stand-alone document.

Updated the Trans_link field data type from Number (Long) to String, to align with the RFC 8259 Standard for JSON fields. See JSON Data Types and EHI Fields. See PRN-154.

Guide rebrand to new company name and brand identity.

EHI Guide 5.0.11 (JSON version)

Added a new appendix which provides details of the contents of the Trans_Link Field.

Added a note to explain that in EHI Mode 2, you can override the Thredd decline code of 51 (Insufficient Funds) with another decline code), if you would like to use a more specific decline reason to be passed to cardholder. See EHI Operating Modes. See PRN-144.

Added further details and clarification on the use of JSON data types and the compatibility of EHI fields with the IEEE 754 binary-64 (double precision) format. See JSON Data Types and EHI Fields.

Correction to description of the token field and its possible values. See GetTransaction Message Fields.

In the GetTransaction Message Fields section, updated the maximum length and maximum values for the following fields: token, TXn_ID, TLogIDOrg, Trans_link and Matching_Txn_ID.

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

Added two new Visa Merchant Category Codes (MCC): 3839 and 5723. See PRN-147.

Added a note to GPS_POS_DATA Cardholder Authentication Methods, to indicate that it is possible for merchants to send two authentication values, which are recording in positions 4 and 5.

EHI Guide 5.0.10 (JSON version)

Added details to clarify how the transaction processing codes 01, 12 and 17 are used. See Processing Codes and the Troubleshooting FAQs. Fixed version numbering issue.

Updated the FAQs with additional information around clearing files.

Updated the description of the following fields to clarify their usage: POS_Data_DE61, POS_Data_DE22 and Merch_Name_DE43. See GetTransaction Message Fields.

Updated the GetTransaction Example Messages.

Added a note to indicate that if the CVV2_Result field is blank, then the merchant did not provide this information. In this case, Thredd will not complete the CVV2 pre-check and will authorise or decline the transaction based on the card usage group settings for your programme. See GetTransaction Message Fields.

Amended the description of Auth_Code_DE38. Thredd will generate this code for an approved authorisation request. See GetTransaction Message Fields.

Added a link to the new EHI Mode Selector Wizard, an interactive tool which can be used to select the right EHI Mode for your business.

New cut-off messages in JSON format now available. See Cut-Off Message Example.

Updated the Copyright Statement.

Updated the headings for the GPS_POS_Capability field, GPS_POS_Data field and the POS_Data_DE61 field

EHI Guide 5.0.9 (JSON version)

Added further matching criteria for the MTIDs TC25, TC26 and TC27 in transaction matching.

Added a note to the transaction matching section for 0400 authorisation reversals about Visa transactions potentially missing an Auth_Code_DE38 value and how to treat this.

Added Glossary definitions for OCT and AFT transactions.

EHI Guide 5.0.8 (JSON version)

AAdded a note and examples of cut-off message, which are currently only available in XML format.

Added a new value of 'L' (delegated authentication) to the GPS_POS_Data field, position 15 (3D secure authentication method). See GPS_POS_Data.

Added status code 59 to the table of status values appearing in the Resp_Code_DE39 field.

Added new sections on Refunds and Financial Reversals to the Transaction Flow Scenarios section.

Updated the examples on the GetTransaction Example Messages page.

Added new column to 3D Secure Authentication Method section of GPS POS Data to differentiate between the differences between Mastercard and Visa. Also clarified content for Mastercard SPA v2.

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

Added a note to the description of data typesAmountUnsigned and AmountSigned to clarify that values can contain up to four decimal places. For customers processing currencies that have more than 2 decimal places, we now round this off to 2 decimal places and add zero padding for the remaining decimal places; see GetTransaction Message Fields > Rounding off of currencies with exponents greater than 2. See PRN-116.

EHI Guide 5.0.7 (JSON version)

For fields of data type AmountSigned, the number of supported decimal places has been updated from 9.2 to 19.4. For example: 72.1230. See GetTransaction Message Fields. Examples in the GetTransaction WSDL and Example Messages also updated for this change. See PRN-114.

Corrections made to POS_DATA_DE22 Authorisation and POS_DATA_DE22 Mastercard appendices.

Corrections made to MTID references on Processing EHI Transactions.

New Merchant Category Codes added.

EHI Guide 5.0.6 (JSON version)

Added a new appendix to describe Special Characters that may be used in fields of Data Type ANS.

Removed the field FxProviderBookedRate.

Processing Code (Proc_Code) = 39 is now used to identify an Account Verification The card’s magnetic stripe, which stores data on a band of magnetic material on the card. The magnetic stripe is read by swiping a magnetic reading terminal. transaction. See Processing Codes. See PRN-102.

Added a new tag for Visa Base 1 e-commerce data to the Misc_TLV_Data Field.

Standardised the field values used in the EHI field PaymentToken_PanSource so that they align with existing values already used in the EHI field GPS_POS_Data position 3 (Card Data Input Method). See PRN-104.

EHI Guide 5.0.5 (JSON version)

GPS_POS_Data position 18, ExemptFromSCA value 8 changed to "Not a transaction under PSD2 rules".

EHI Guide 5.0.4 (JSON version)

New fields added for Currency Cloud FX service: FxProviderCardholderRate and FxProviderBookedRate.

New Visa examples provided for AuthenticationMerchantHash. See Matching Merchant Name.

New data type of double added to Data Types page.

Udates to Misc_TLV_Data Field description to include new Sender and Receiver data tags.

Updates to descriptions in SenderData and ReceiverData Fields.

Note: Changed guide version number from 5.1 to 5.0.4 to reflect actual current version of EHI (5.0).

Additional information provided on Responding to Authorisation Declines and Responding to Partial Approvals.

Changes to the description of the DECIMAL data type. See Data Types.

Updates to the WSDL for the EHI XML version. See GetTransaction WSDL.

Minor change to description in MTID field 1240.