External Host Interface (EHI) Guide (XML version)

EHI Guide 5.0.16

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

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

EHI Guide 5.0.15

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.

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

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 Example Financial Notifications.

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

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.

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

EHI Guide 5.0.12

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.

Updates to EHI authorisation examples. See WSDL and Examples.

Guide rebrand to new company name and brand identity.

EHI Guide 5.0.11

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.

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

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.

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.

Updated 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

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

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.

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

Updated the EHI Examples section with updated examples, as well as reorganising the layout.

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

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.

Updated examples in the guide to reflect that fields with no data are sent in a closed tag format and not as an open and close tag (e.g., as <Note /> and not as <Note> </Note>).

EHI Guide 5.0.5

Added an example of an Agency Banking transaction.

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

EHI Guide 5.0.4

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.

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.

EHI Guide 5.0.3

New values in GPS_POS_DATA for 3D Secure Authentication: v = Authenticated by Mastercard IDCX (‘Identity Check Express’) service; z = AAV refresh transaction successfully authenticated by ACS. See 3D Secure Authentication Method.

New guide using the EHI REST version is now available. Both versions of the guide have been updated to clarify differences between REST and XML message formats.

For a Visa purchase with Cashback, Thredd now sends the value of Proc_Code 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 field in the GetTransaction Message to use the format provided by GCMS IPM / Visa Base 2, which contains only the data (a multiple of 20 characters). See PRN-72.

In ResponseStatus and Response_Code_DE39 the description of response code 78 has been updated to Card is not active (including created but not yet activated)

Document corrections:

• Corrected the spelling of Responsestatus in Transaction Flow Scenarios and Processing EHI Transactions.

• Additional details provided on transaction matching of Financial Reversals for Visa transactions. See Transaction Matching. New information provided to support matching transactions where the Acquirer data does not match; see Troubleshooting FAQs: Transactions and Matching.

• Information provided on Account Status Inquiry (ASI) transactions and how to identify them.

EHI Guide 5.0.2

New value V = Account Verification added to the Auth_Type field in the GetTransaction message. See PRN-69.

New description of how to respond to Authorisation Reversals. See Processing EHI Transactions.

Updates to Card Status Codes to reflect new card block status codes. See PRN-48.

Note: For additional information about Thredd updates to status and response codes, see the guide Changes to Thredd Card Status and Response Codes.

EHI Guide 5.0.1

Added new EHI fields to authorisation messages, which can be used to compare the 3D Secure authentication amount and currency to the authorised amount and currency:

• AuthenticationCurrency

• AuthenticationAmountUpper

• AuthenticationMerchantNameHash

These fields can be used to comply with the PSD2 Strong Customer Authentication (SCA) Dynamic Linking requirements (see PRN-56). See Checking fields used for 3D Secure Authentication.

Positions 25 and 26 have been added to GPS_POS_Data, which you can use to identify if the authentication amount does not match the authorisation amount.

Updates to recommendations for matching and handling authorisation advises and authorisation reversal requests.

New appendix with Transaction Matching - Authentications and Authorisations.

New optional MerchantAdvice response field added, for use when returning decline responses.

In the ResponseStatus Values section, clarified when to use response codes 70 and 93.

EHI Guide 5.0.0

Updates to reflect new fields added for EHI version 5.0. For details, see EHI Versions. New fields:

• Acquirer_Country

• ClearingFileId

• Network_Fraud_Data

• PaymentToken_PanSource

• ReceiverData

• SenderData

Updates to WSDL and examples. See GetTransaction WSDL and Example Messages.

Addition of new appendices: Network_Fraud_Data Format and SenderData and ReceiverData Fields.

Changes to numbering in Appendices.

Document corrections:

• Updated the GPS_POS_Data, position 16 and 17 descriptions.

• Updated the incorrect spelling of the Proc_Code field in some descriptions which refered to this field.

• Updated the PaymentToken_status field description to point to the correct appendix to use for possible values:  Card Status Codes.

• Changed the following field names to lower-case, to be consistent with how these are used in the GetTransaction WSDL: auth_type, auth_expdate_utc, multi_part_txn, multi_part_txn_final, multi_part_number, multi_part_count.

EHI Guide 4.1.13

Updates to Amount Type Codes for the Additional Amounts field: added values 12, 42, 57 and 58.

EHI Guide 4.1.12

Updates to response code appendices: new appendices for ResponseStatus Response Codes and Response_Code_DE39 Response Codes.

New value of N for Non-Card and updates to description of J value in PaymentToken_deviceType.

EHI Guide 4.1.11

In GPS_POS_Data, changed the descriptions for SCA Assessment Result. Updates to Card Status Codes and Response Codes.

New EHI c value for a mini-card in appendix PaymentToken_deviceType.

New GPS_POS_Data field position 24: Card/Device Type (Form Factor).

EHI Guide 4.1.10

In GPS_POS_Data, added a new value of '3' for position 19, and news values of 8 and 9 for position 18; rewrote the SCA section to improve usability. Added new section for position 23.

EHI Guide 4.1.0.9

Added new tokenisation transaction codes 32, 37 and 28 to Processing Codes.

New tokenisation examples added to GetTransaction WSDL and Example Messages

New page with details of fields per EHI Versions

EHI Guide 4.1.0.8

Major revamp to guide. New format and content rewrite. New Getting Started section and FAQs. Topics and appendices have been reorganised.