AMEX HTTPS Comms Guide-April 2018

INTERNET DIRECT
HTTPS COMMUNICATION GUIDE
GLOBAL NETWORK BUSINESS

Digital Products and Capabilities
April 2018
Document Version 3.6

Copyright © 2006-2018 American Express Travel Related Services Company, Inc. All rights re-
served. This document contains sensitive, confidential and trade secret information; and no part of
it shall be disclosed to third parties or reproduced in any form or by any electronic or mechanical
means, including without limitation information storage and retrieval systems, without the express
prior written consent of American Express Travel Related Services Company, Inc.
American Express Proprietary & Confidential Internet Direct HTTPS Communication Guide
Table of Contents
1.0 Introduction ....................................................................................................................... 1

2.0 Internet Direct Services Offered ...................................................................................... 3
2.1 Overview ............................................................................................................................. 3
2.2 High-Level Design .............................................................................................................. 3
2.3 Supported File Formats ....................................................................................................... 4
2.4 Usage Requirements ........................................................................................................... 5
3.0 Connectivity Details .......................................................................................................... 6
4.0 Request Message ............................................................................................................... 8
4.1 Request Message Header Value Descriptions .................................................................. 12
5.0 Response Message: Browser and Terminal................................................................... 19
5.1 Standard HTTPS Response Messages from Server .......................................................... 19
5.2 Common Network Socket Exceptions .............................................................................. 20
6.1 ISO 8583 Message (PIP) Format — Example .................................................................. 21
6.1.1 TLS Handshake on New TCP Connection........................................................................ 22
6.1.2 Send HTTPS POST Request ............................................................................................. 23
7.0 How to use the American Express Test System (ATS) via Internet Direct ............... 25
8.0 Steps to Create a Test Client Using Java Technology .................................................. 26
9.0 Steps to Create a Test Client Using .Net Technology (C#) ........................................... 28
9.1 Example of C# Client........................................................................................................ 29
10.0 Steps to Create a Test Client Using C++ ....................................................................... 30
10.1 Example of C++ Client — Connect Method .................................................................... 30
10.2 Example of C++ Client — Send Method .......................................................................... 31
11.0 Rejection, Errors and Failures....................................................................................... 32
12.0 Country and Region Codes ............................................................................................ 34
13.0 Routing Codes ................................................................................................................. 35
14.0 Revision Log .................................................................................................................... 37
April 2018 i
This document contains sensitive, confidential and trade secret information, and must not be disclosed to third parties
without the express prior written consent of American Express Travel Related Services Company, Inc.
This page is intentionally left blank.
April 2018 ii
1.0 Introduction
The Internet Direct HTTPS Communication Guide is written for programmers working on the behalf
of our Partners (including Merchants/Service Establishments, Authorized Processors, Third Party
Developers, Issuers and Terminal and Software Vendors) to develop interfaces to American Express.
This document covers only the communication connections used to transmit data. Specific file formats
and field definitions are explained in other American Express marketing and technical documents
(for example, one format for an Authorization Request message is defined in the American Express
Global Credit Authorization Guide).
Disclaimer: To the maximum extent permitted by law, American Express does not make and hereby
disclaims any and all representations, warranties, and liabilities, whether express or implied, or
arising by law or from a course of dealing or usage of trade, including implied warranties of
merchantability or fitness for a particular purpose or any warranty of title or non-infringement. You
must comply with laws and regulations applicable to the subject matter of this document. These laws
and regulations can differ from country to country, and you are solely responsible for being aware and
adhering to them in all countries where you implement this document.
April 2018 1
April 2018 2
2.0 Internet Direct Services Offered
2.1 Overview
This document is provided for clients who wish to send various request messages to American Express
through the Internet by accessing specific American Express URLs, which are included in this guide.
This document contains technical details necessary for authorized Partners to communicate with
American Express systems via the American Express Internet Direct Gateway.
This manual includes a high-level explanation of the URL options offered, how to invoke the URLs
and Partner system requirements. Details on these functions and American Express global
specifications are available on the following Web site:
http://www.americanexpress.com/merchantspecs
2.2 High-Level Design
The American Express Internet Direct Gateway allows Partners to transmit real-time Authorizations,
Submissions and approved region specific messages via the Internet. HTTPS is used to provide secure
access to the Gateway URLs.
Partners utilize the American Express Internet Direct Gateway solution by accessing the appropriate
URL. The actual request message data is embedded in a hidden parameter in the transmission to
American Express; and an HTTPS POST is used to transmit this data to the American Express
Internet Direct Gateway. No user ID or password is needed.
American Express uses TLS server authentication and transmits a TLS certificate in the handshake
message returned to the terminal/system. The Partner system must accept this certificate in addition to
certificate renewals as needed.
Internet Direct compatible applications should follow best-practices associated with the automatic
acceptance of certificates from trusted sources; if this requirement is not met it is likely that required
certificate renewals will prevent the processing of transactions.
American Express systems process the request and generate a response that is embedded in a hidden
parameter in the American Express-generated response.
Further details on this process are included in the sections that follow.
April 2018 3
2.3 Supported File Formats
At this writing, the following file formats are supported:
 Global Credit Authorization Guide (ISO)
 Global Credit Authorization Guide (XML)
 GICC/GICC Light Protocol for POS Authorizations - EMEA Region
 Standard 70 Authorization Specification - EMEA Region
 Global Electronic Data Capture Specification (GEDC)
 Global Financial Settlement Guide (XML Format)
 PRICE - Specification for Spain
 Global Hostlink Data Capture (GHDC) - LAC, Canada, Americas
April 2018 4
2.4 Usage Requirements
 Whenever possible, a host should be used to connect to American Express instead of using a
direct terminal connection.
 Terminals must be able to accept automatic updates for certificates, IP addresses, URL and
routing indicator changes
 Terminals must be able to support automatic failover between the Internet Direct URLs
 Uptime and connectivity are the responsibility of the Partner and their Internet Service Provider
(ISP)
 It is highly recommended that a Partner have a secondary Internet Service Provider (ISP) to
fulfill any redundancy requirements external to American Express.
 A Partner should have ability to utilize multiple routing indicators to route to different
locations.
 Connections must be made via the URL
 Technical requirements change frequently; please download this guide after each April and
October release to review what’s new and to be prepared for any upcoming changes.
These requirements have been established to minimize the likelihood of a service disruption or outage
for a Partner. Implementations that do not follow these guidelines may be subject to unplanned outages
and downtime and may require manual intervention or coding changes with little advance notice at
Partner expense. Partners that cannot support these usage requirements should speak to their American
Express Technical Representative regarding alternate connectivity.
April 2018 5
3.0 Connectivity Details
 Transaction must be sent to the Internet Direct Gateway web server. The URL will be provided by
the American Express Technical Representative.
 It is highly recommended that a vendor has a secondary Internet Service Provider (ISP) to
fulfillany redundancy requirements external to American Express.
 Detailed specifications for the HTTPS/1.1 protocol can be found in RFCs (7230-7237) on the
World Wide Web Consortium web site: http://www.w3.org/Protocols/
 A transaction is transmitted in the request headers for the POST method. See examples of Internet
Direct Gateway transactions using the POST methods, beginning on page 23.
April 2018 6
April 2018 7
4.0 Request Message
 Make an HTTPS Connection to the provided URL and PORT.
 The following request message header values must be provided to insure proper processing by the
American Express Internet Direct Gateway:
– origin (Vendor Name/Developing Entity or Vendor and Port for Online PIN and GHDC)
– country (Country Code; see page 34)
– region (Region Code; see page 34)
– message (Authorization Message Type being sent; see page 15)
– MerchNbr (Merchant Number of merchant sending the Authorization Request Message)
– RtInd (Routing Indicator where Authorization Message is to be routed; see page 17)
Note: For details on populating these Header Values, see Request Message Header Value Descrip-
tions on page 10.
 Set the request authorization message as a byte-stream in the hidden parameter:

AuthorizationRequestParam
 Terminal will open up URL Connection.
 Perform a HTTPS POST to send the request message to the American Express Internet Direct
Gateway URL.
 The Request Message (i.e., ISO Message or Auth XML value) should not be in the Header Values.
Instead, merchants/vendors must transport Request Message data as the Request POST parameter
AuthorizationRequestParam key value in the body of the Request Message (via browser and ter-
minal). This parameter value is the actual payload message.
 Internet Direct requires the transaction message contained within AuthorizationRequestParam to

be encoded in ascii hex format. This refers to binary data that is converted into ascii format and
the ascii values are shown in hexadecimal.
 An example of ascii hex encoding would be taking the string “qacafe” and mapping it to the ascii
hex value of 71 61 63 61 66 65. If you were to enter the ascii hex data into the
AuthorizationRequestParam parameter, you would enter the data without any spaces. For
example: “716163616665”, but without the quotes.
Request Body Details for Browser and Terminal

AuthorizationRequestParam=<Dynamic-Authorization-Request>
See details for request-message Browser and Terminal Headers on the following pages.
April 2018 8
4.0 Request Message (Continued)
Overview of a standard HTTPS/1.1 message format as defined in RFCs (7230-7237).
Sample HTTPS message diagram:
Note:
 HTTPS ‘Content-length’ is the length of the entire message body, including the length of the
hidden parameter ‘AuthorizationRequestParam=’.
 Each and every header parameter should be separated by one CR[carriage Return]/LF[Line
Feed].
 At the end of the Header parameters there should be two CR/LF before message body starts.
The extra CR/LF indicates the end of HTTPS header sections.
 American Express Internet Direct application will not be able to process any messages in
Internet Direct application unless it follows HTTPS specification of message format as
depicted above.
April 2018 9
4.0 Request Message (Continued)
Browser Header Details — Request

POST POST /IPPayments/inter/CardAuthorization.do HTTPS/1.1
Accept image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, application/vnd.ms-
excel, application/vnd.ms-powerpoint, application/msword, application/x-
shockwave-flash, */*
Referrer <Referrer page>
Accept-Language en-us
Content-Type plain/text
User-Agent Google Chrome: v 1, Mozilla Firefox: v 1, Internet Explorer: Windows XP v
7 and 8, Windows Server 2003: v 7 and 8, Windows Vista: v 7, 8 and 9,
Windows 7: v 8, 9, 10, 11, Server 2008: v 7, 8 and 9, Server 2008 R2: v 8,
9, 10 and 11, Windows 8: v 10, Server 2012: v 10, Windows 8.1 v 11,
Server 2012 R2 v 11
Host <URL:Provided to Merchant/Vendor by American Express Technical

Representative>
Content-Length <Dynamic length of the message>
Cache-Control no-cache
Connection Keep-Alive
origin <Vendor Name>
Merchants writing their own software should use <Merchant Name>
Merchants using online PIN and GHDC should use <ProcessorName-PortNumber>

OR <ProcessorName-MerchantName-PortNumber> This will be provided by
American Express Technical Representative during the certification process
country See Country and Region Code information on page 34.

region See Country and Region Code information on page 34.
message See Message Types on page 12.
MerchNbr SE Number / Merchant Number
RtInd Routing Indicator provided by American Express
Terminal Header Details — Request

POST POST /IPPayments/inter/CardAuthorization.do HTTPS/1.1
Accept-Language en-us
Content-type plain/text
User-Agent Terminal;<Vendor Name>;<Terminal Type>
Host <URL:Provided to Merchant/Vendor by American Express Technical
Representative>
Content-Length <Dynamic length of the message>
Cache-Control no-cache
Connection Keep-Alive
origin <Vendor Name>
country See Country and Region Code information on page 34.
April 2018 10
region See Country and Region Code information on page 34.

message See Message Types on page 12.
MerchNbr SE Number / Merchant Number
RtInd Routing Indicator provided by American Express
Note: Parameter names in first column of tables above are case-sensitive.
April 2018 11
4.1 Request Message Header Value Descriptions
Header Value origin
Header Type: Alphanumeric
Constant: None
Header Requirement: Mandatory
Description: This header value contains an alphanumeric value which refers

to the name of the entity responsible for the development of the
payment solution.
Examples: Origin: Vendor/Developing Entity
Origin*: ProcessorName-PortNumber OR
ProcessorName-MerchantName-PortNumber
*Format required for Online PIN and GHDC / will be provided by American Express Technical
Representative during the certification process
April 2018 12
Header Value country
Header Type: Numeric
Constant: None
Description: This header value contains a three-digit, numeric Country code

that corresponds to the country in which the request message
originates.
For valid codes, see Country and Region Codes on page 34.
Example: Country: 840
Note: Country Code “840” = USA
April 2018 13
4.1 Request Message Header Value Descriptions (Continued)
Header Value region
Header Type: Alphanumeric and special characters
Constant: None
Description: This header value contains a Region code that corresponds to the
American Express region in which the request message originates.
For valid codes, see Country and Region Codes on page 34.
Example: Region: JAPA
April 2018 14
Header Value message
Header Type: Alphanumeric
Constant: None
Description: This header value contains a Message Type code that indicates
the type of data transported in this Request Message. Valid entries
include the following:
Message Type Description

APACS APACS 30 Authorization Specification (EMEA Region)
APACS40 APACS 40 Authorization Specification (EMEA Region)
AS2805 AS2805 Specification for JAPA
DUAG Dial-Up Authorization Guide (US Region)
EDC JAPA Specification for Electronic Data Capture Terminal Device
(JAPA Region)
GFSG XML BAR Batch Admin Request
XML Global Financial Settlement Guide
GFSG XML DCR Data Capture Request
XML Global Financial Settlement Guide
GICC GICC Protocol for POS Authorizations (EMEA Region)
ISO GCAG ISO 8583 v1 – Global Credit Authorization Guide
ISO GLOBAL EDC Global Specification for Electronic Data Capture Terminal
Device (US & LAC Regions)
ISO PIP ISO 8583 v0 – Plural Interface Processing Terminal Inter-
face Specification (US & LAC Regions)
PRICE Specification for Spain
XML GCAG XML Global Credit Authorization Guide (359 only)
GHDC Global Host-Link Data Capture (LAC, Canada, US)
Example: Message: ISO GCAG
April 2018 15
Header Value MerchNbr
Constant: None
Description: This header value contains the American Express-assigned

Merchant Number (a.k.a., Merchant ID or SE/Service Establish-
ment Number) that identifies the specific Merchant/Acquirer
transmitting the request message.
Example: MerchNbr: 123456789
Note: For those messages that don’t contain a valid Merchant

Number, like 1804 ‘ping’ messages, please use the following
value to populate MerchNbr
MerchNbr: 1804000001
April 2018 16
Header Value RtInd
Constant: None
Description: This header value contains a Routing Indicator code that directs
the message to the appropriate American Express system for
processing.
Example: RtInd: 000
Note: The Routing Indicator will be provided by your American

Express Technical Representative during the certification
process.
April 2018 17
April 2018 18
5.0 Response Message: Browser and Terminal
 Perform HTTPS POST operation on connection to retrieve response message from American
Express Internet Direct Gateway URL.
 Then, extract Authorization Response message from stream content received from server.
Header Details – Response Message

(Status-Line) HTTPS/1.1 200 OK (In the case of success)
Connection close
Content-Language en-us
Content-Type plain/text
Date <Date Tue, 18 Jul 2006 00:19:48 GMT>
Server IBM_HTTPS_Server
Actual Response Message String <Actual response message is in string format.>
5.1 Standard HTTPS Response Messages from Server
Status Code Description

200 OK — The request was fulfilled successfully.
204 No Response — Server has received the request, but there is no information to send back; and the client should stay
in the same document view. This is mainly to allow input for scripts without changing the document at the same time.
This scenario occurs when the IP Gateway is waiting for an internal response from some dependant service.
400 Bad Request — The request had bad syntax or was inherently impossible to be satisfied. There may be a few errors
in PATH or errors in making connection to the appropriate servers.
404 Not Found — The server did not find anything matching the URI given.
500 Internal Error — The server encountered an unexpected condition, which prevented it from fulfilling the request.
501 Not Implemented — The server does not support the facility required.
502 Service Temporarily Overloaded — The server cannot process the request due to a high load (whether HTTPS
servicing or other requests). The implication is that this is a temporary condition, which may be alleviated at other
times.
April 2018 19
5.2 Common Network Socket Exceptions
Problem Cause
SocketException 1. Operation timed out. Host unavailable.
2. Could not connect. Could be due to invalid address.
UnknownHostException: User set incorrect URL. • Virgule “/” missing before actual path.
<host name> • Incorrect URL.
April 2018 20
6.0 Communication Details
This section contains diagrams and examples that illustrate TLS processing, basic cryptography
concepts of the TLS operation, and the HTTPS POST request and response flow, with header details.
TLS is a sophisticated encryption scheme that does not require the exchange of a secret key between the
client and server before the transaction is initiated. Instead, TLS public/private keys provide flexible
encryption that is setup when the secure transaction is transmitted.
Note: While the diagram on page 20 shows a typical example of an HTTPS POST browser request,
actual requests may vary depending on the origin of the authorization request (i.e., from a merchant’s
browser, or a terminal).
6.1 ISO 8583 Message (PIP) Format — Example
The following is an example of the ISO 8583 Message, Plural Interface Processing (PIP) Format from
a terminal. User application “/IPPayments/inter/CardAuthorization.do” will post
transaction data to the Internet Direct Gateway URL.
For details, see American Express Plural Interface Processing (PIP) Terminal Interface Specification
(POS020055).
Client American Express

SYN
Secure connection is needed for this session. Browser 
establishes TCP connection on HTTPS TCP port 443.
 ACK
April 2018 21
6.1.1 TLS Handshake on New TCP Connection
 Client sends ClientHello message

proposing TLS options.
 Server responds with ServerHello
message selecting the TLS options.
 Server sends Certificate message,
which contains the server's
certificate.
 Server concludes its part of the
negotiation with ServerHelloDone
message.
 Client sends session key
information (encrypted with
server's public key) in
ClientKeyExchange message.
 Client sends ChangeCipherSpec
message to activate the
negotiated options for all future
messages it will send.
 Client sends Finished message to
let the server check the newly
activated options.
April 2018 22
6.1.2 Send HTTPS POST Request

HTTPS POST
Client sends HTTPS POST containing merchant data, on 
newly established TCP connection. See HTTPS POST
example, below.
POST /IPPayments/inter/CardAuthorization.do HTTPS/1.1
Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg,
application/vnd.ms-excel, application/vnd.ms-powerpoint,
application/msword, application/x-shockwave-flash, */*
Referrer: <space - The jsp or the page if application is referring to.>
Accept-Language: en-us
Content-Type: plain/text
User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; .NET CLR
1.1.4322; .NET CLR 2.0.50727)
Host: qwww318.americanexpress.com
Content-Length: <Dynamic length of the message>
Cache-Control: no-cache
Connection: Keep-Alive
origin: <Vendor Name>
country: 840
region: USA
message: ISO PIP
MerchNbr: 1234567890
RtInd: 000
Merchant needs to send the parameter below in the body of the message.
----------------------------------------------------------
AuthorizationRequestParam=<Authorization Request>
----------------------------------------------------------
HTTPS 100 Continue

The client should continue with its request. This interim
response is used to inform the client that the initial part of the
request has been received and has not yet been rejected by
the server. The client should continue by sending the
remainder of the request or, if the request has already been
completed, ignore this response. The server must send a
final response after the request has been completed.
TCP (ACK)
The web server sends a TCP ACK to acknowledge the two
TCP segments for the HTTPS POST.
HTTPS 200 OK
The web server acknowledges the HTTPS POST. See
HTTPS POST Header example, below.
(Status-Line): HTTPS/1.1 200 OK
Connection: Close
Content-Language: en_US
Content-Type: text/html; charset=ISO-8859-1
Date: <Date Tue, 18 Jul 2006 11:25:07 GMT>
Server: IBM_HTTPS_Server
----------------------------------------------------------
Response is sent to the merchant in the string format.
----------------------------------------------------------
April 2018 23
6.1.2 Send HTTPS POST Request (Continued)

TCP (ACK)
TCP ACK for TCP segment containing “HTTPS 200 OK“

TCP (FIN)
Web server initiates TCP connection release by sending a
close notification alert.
TCP (FIN)
Client initiates TCP connection release.

 TCP (ACK)
TCP (FIN)
Web server initiates TCP connection release.
TCP (ACK) 
April 2018 24
7.0 How to use the American Express Test System (ATS) via Internet
Direct
Overview
The American Express Test System (ATS) is a certification platform available to authorized Partners
to certify American Express transaction features. ATS has been developed to provide an enhanced
customer experience with an intuitive approach to how test transactions are validated and how
certifications are performed. Customers using American Express Authorization SDK or any other
supported transaction can use ATS to test. ATS allows streamlined testing and the ability to view test
transactions by accessing the ATS portal (www.amextestsystem.com).
Your American Express regional representative will work with you enable your ATS access; once
completed, testing with ATS will be available via this link.
Testing Setup
1. Certifying customer chooses to use an ATS compliant specification
2. American Express Certification Analyst agrees upon an ‘Origin’ name with the customer
a. If using Online PIN or GHDC for Internet Direct please follow the guidelines for
‘Origin’ set up (the port provided for testing may be different than the one issued for
production). Please refer to your certification analysts for additional information
regarding the ‘Origin’ that should be used.
3. The customer can then begin testing using the following data:
a. Internet Direct URL for testing/certification:

https://qwww318.americanexpress.com/IPPayments/inter/CardAuthorization.do
b. ATS Routing Indicator: 050
c. Assigned Origin value (if applicable)
d. All other Header values remain the same based on the standard guidelines
‘Go-Live’ Production
1. Once the American Express Analyst has indicated that all ATS testing and certification
is complete, the application is ready to ‘Go-Live’ into production. The following data
values must change to ensure successful transactions in the production environment:
a. The production URL is provided during successful certification
b. Production Routing Indicator provided by the American Express Certification

Analyst
c. Assigned Origin value (remains the same from test)
d. All other Header values remain the same based on the standard production guidelines
April 2018 25
8.0 Steps to Create a Test Client Using Java Technology
The following example is Java code for opening a connection and sending an Authorization Request
message using the hidden parameter. Statements in bold text are comments.
If any systems running the Internet Direct payment solution uses JRE 1.6 Update 22 or later
sun.net.http.allowRestrictedHeader must be set to true. This ensures that all required headers are
passed properly as part of the HTTPS message.
//OPEN CONNECTION
… (Client’s code)
URL url = new URL("https://qwww318.americanexpress.com/IPPayments/inter/CardAuthorization.do");
URLConnection conn = url.openConnection();
//SET HEADERS - Values on the connection object
conn.setRequestProperty("POST", "/IPPayments/inter/CardAuthorization.do HTTP/1.1" );

conn.setRequestProperty("Accept-Language", "en-us" );
conn.setRequestProperty("Content-Type", "plain/text" );
conn.setRequestProperty("User-Agent", "Application" );
conn.setRequestProperty("Host", "qwww318.americanexpress.com" );
conn.setRequestProperty("Content-Length", "370" );
conn.setRequestProperty("Cache-Control", "no-cache" );
conn.setRequestProperty("Connection", "Keep-Alive" );
conn.setRequestProperty("origin", "" );
conn.setRequestProperty("country", "" );
conn.setRequestProperty("region", "" );
conn.setRequestProperty("message", "" );
conn.setRequestProperty("MerchNbr", "" );
conn.setRequestProperty("RtInd", "" );
conn.setDoInput(true);
conn.setDoOutput(true);
conn.setUseCaches(false);
//Write payload message as post data
String stArgs = "AuthorizationRequestParam = Actual Payload Message";

DataOutputStream out = new
DataOutputStream(conn.getOutputStream());
out.writeBytes(stArgs);
System.out.println(out.toString());
out.flush();
out.close();
… (Client’s code)
April 2018 26
 After the Partner sends the request to the Internet Direct Gateway, American Express returns a
server-side certificate to the merchant terminal/system.
 The terminal/system accepts the certificate.
 The American Express Internet Direct Gateway continues processing the message.
April 2018 27
9.0 Steps to Create a Test Client Using .Net Technology (C#)
 Developed C# client using Visual Studio 2005.
 Below is the list of classes, which come with .Net Framework 2.0. Users may use the following to
develop the client using C#.
HTTPSWebRequest Class —
Provides an HTTPS-specific implementation of the WebRequest class.public class
HTTPSWebRequest : WebRequest, ISerializable — The HTTPSWebRequest class provides

support for the properties and methods defined in WebRequest and for additional properties
and methods that enable the user to interact directly with servers, using HTTPS.
HTTPSWebResponse Class —
This class contains support for HTTPS-specific uses of the properties and methods of the
WebResponse class. The HTTPSWebResponse class is used to build HTTPS stand-alone
client applications, which send HTTPS requests and receive HTTPS responses.
See example in code snippet on next page.
April 2018 28
9.1 Example of C# Client
public virtual string GetResponse(string Uri, string RequestMethod)

{
//RequestMethod will be "POST"
HttpWebRequest webrequest = CreateWebRequest(Uri,RequestMethod);
BuildReqStream(ref webrequest);
HttpWebResponse webresponse;
webresponse = (HttpWebResponse)webrequest.GetResponse();
Encoding enc = System.Text.Encoding.GetEncoding(1252);

StreamReader loResponseStream = new StreamReader(webresponse.GetResponseStream(),enc);
string Response = loResponseStream.ReadToEnd();
loResponseStream.Close();
webresponse.Close();
return Response;
}
public virtual HttpWebRequest CreateWebRequest(string uri,string RequestMethod)

{
HttpWebRequest webrequest = (HttpWebRequest) WebRequest.Create(uri);
webrequest.KeepAlive = false;
webrequest.Method = RequestMethod;
//Header Information should be according to spec. and differs per region
webrequest.Headers.Add("origin", "origin-name");
webrequest.Headers.Add("country", "country-code");
webrequest.Headers.Add("message", "message-type");
webrequest.Headers.Add("region", "region-name");
webrequest.Headers.Add("MerchNbr", "10 digit merchant number"); - Provided by Amex
webrequest.Headers.Add("RtInd", "Routing Indicator");
webrequest.ContentType = "text/xml";
return webrequest;
}//End of secure CreateWebRequest
private void BuildReqStream(ref HttpWebRequest webrequest)

{
string strPost;
strPost = "AuthorizationRequestParam=actual message string";
StreamWriter myWriter = null;
strPost=Request; - This is where the auth message needs to be sent.
webrequest.ContentLength = strPost.Length;
try
{
myWriter = new StreamWriter(webrequest.GetRequestStream());
myWriter.Write(strPost);
}
finally
{
myWriter.Close();
}
}
April 2018 29
10.0 Steps to Create a Test Client Using C++
 Develop a C++ client using Visual Studio 2005.
 See Connect and Send method examples in the code sample on the following pages.
10.1 Example of C++ Client — Connect Method
/////////////////////////////////////////////////////////////////////////////////////////////
//Method: Connect
//Purpose: Connection method takes two parameters the HostAddress and Port
/////////////////////////////////////////////////////////////////////////////////////////////
bool XHttpConnection::Connect(const char *ptHostAddress, unsigned short nHostPort,
const char *ptUser, const char *ptPassword, bool bSecure)
{
DWORD dwFlags = 0;
if (m_pxInternetSession == NULL)
{
if (Initialize() == false)
{
return false;
}
}
try
{
if (bSecure)
{
dwFlags = INTERNET_FLAG_SECURE;
}
m_pxHttpConnection = m_pxInternetSession->GetHttpConnection(ptHostAddress, dwFlags,
nHostPort,ptUser,ptPassword);
}
catch(CInternetException *pIntEx)
{
TCHAR szCause[255];
pIntEx->GetErrorMessage(szCause,255);
//Log
g_Log.PutEntry( (LPSTR)(LPCTSTR)theEdglibApp.GetTaskName(), //log the CInternetException

"XHttpConnection::Connect", HTTP_EXCEPTION,
TRACING_ELMNT_EDGLIB,
EDGLIB_RECORDING_SOURCE_SOCKETS,
"%s", szCause) ;
return false;
}
return true;
April 2018 30
10.2 Example of C++ Client — Send Method
////////////////////////////////////////////////////////////////////////////////////////////
//Method: Send
//Purpose: To transmit data through the System
//Parameters:
// ptMessage - Message to be sent
// ptHeaders - Headers to be added (example Accept:text/*\r\n) -
// SHOULD be all the headers
// ptVerb - POST/GET
// ptObjectName - Who we're sending to ??CardAuthorization.do
// ptHttpVersion
///////////////////////////////////////////////////////////////////////////////////////////
int XHttpConnection::Send(CString* ptMessage, CString *ptHeaders, int iVerb, CString *ptObjectName,
CString ptHttpVersion, DWORD *pStatusCode)
{
try
{
m_pxFile = m_pxHttpConnection->OpenRequest(iVerb, //Verb
(LPCTSTR) ptObjectName, //target object- ?? whatever .do ?? CardAuthorization.do
NULL, //(LPCTSTR) ptHeaders, NOT SURE IF THIS IS THE HEADERS
1, //always use 1 for context, this is only child of session
NULL, //if null, only accept text
(LPCTSTR) ptHttpVersion, //HTTP version, default is HTTP/1.0, Amex wants HTTP/1.1
INTERNET_FLAG_RELOAD | INTERNET_FLAG_SECURE); //cache, HTTPS
m_pxFile->AddRequestHeaders((LPCTSTR) ptHeaders);
DWORD iSize = ptMessage->GetLength();
//The headers are confusing, can load them in OpenRequest, AddRequestHeaders and SendRequest
BOOL bOK = m_pxFile->SendRequest(NULL,0,(LPVOID) ptMessage, iSize);
if (bOK)
{
m_pxFile->QueryInfoStatusCode(*pStatusCode);
}
else
{
*pStatusCode = 0;
}
return (int) iSize;
}
catch(CInternetException *pxIntEx)
{
TCHAR szCause[255];
pxIntEx->GetErrorMessage(szCause,255);
g_Log.PutEntry( (LPSTR)(LPCTSTR)theEdglibApp.GetTaskName(), //log the CInternetException
"XHttpConnection::Send", HTTP_EXCEPTION,
TRACING_ELMNT_EDGLIB,
EDGLIB_RECORDING_SOURCE_SOCKETS,
"%s", szCause) ;
Disconnect();
return -1;
}
}
April 2018 31
11.0 Rejection, Errors and Failures
 Time-Out Failures — Message processing may infrequently exceed the maximum time allotted;
in which case, a “time-out” error message is displayed on the terminal or monitor. In addition,
communication and system-associated failures not related to actual message content are reported
as “time-out” failures, and no further error descriptions are provided.
The American Express Internet Direct Gateway times out after 30 seconds (i.e., after 30
seconds, American Express initiates a connection close and sends the merchant/ vendor a
“null” response, with status code “200”).
 Request Message Rejection and/or Errors — American Express returns response messages that
include status and/or error codes that indicate the reason the financial request was denied/declined
or rejected.
If American Express internal systems are unable to parse the request, or if the message does not
match the required format, a blank string (“”) with no status code is returned as a response.
April 2018 32
April 2018 33
12.0 Country and Region Codes
Refer to the American Express Global Codes & Information Guide for a complete list of Country
codes.
Regional Codes should be added as follows:
LAC: Countries in Latin America (Note: Puerto Rico, Caribbean and Virgin Islands should also
be coded as LAC)
JAPA: Countries in Asia
EMEA: Countries in Europe
CAN: Canada
US: United States
April 2018 34
13.0 Routing Codes
Internal Teams should reach out to the GAN Production Support mailbox for a complete and up to
date list of routing codes. Each message specification and/or PIN transaction may require use of a
unique code; please review before proceeding with certification.
April 2018 35
April 2018 36
14.0 Revision Log
3.6 3/13/18|L. Chmielewski

• Page 8, Added details regarding AuthorizationRequestParam
• Page 34, Added Region codes

• Page 1, Added disclaimer

• Page 4, Updated list of supported message formats
• Page 34-40, Referenced external documentation for Country and Region codes

• Page 4, Added GHDC to list of specifications supported
• Page 4, Noted GCAG XML specification cannot be used or failed over to 206
• Page 5, Revised section to reflect requirements for Internet Direct usage/connectivity
• Page 8, Noted GHDC format for “Origin”
• Page 10, Added GHDC format for “Origin”
• Page 12, Noted GHDC format for “Origin”
• Page 15, Added GHDC to list of specifications
• Page 15, Noted GCAG XML must be used on 359
• Page 25, Noted GHDC routing for testing, added testing URL, updated instructions
3.2 03/08/16|L.Chmielewski
• Page 5, Added recommendations regarding guide usage
• Page 25, Changed ATS routing indicator, added ATS test link
• Page 41, Added notation regarding use of routing indicator
3.1 09/23/15|L. Chmielewski|. Legac

• Page 5, Added recommendation regarding TLS version migration
• Page 6, Added note regarding TLS and SHA version support
• Page 8, Updated the page references
3.0 02/09/15|L. Chmielewski/R. Hancock| See Below

• Page 5, Added Recommendations section
• Page 6, Updated RFC 2616 to RFCs (7230-7237)
• Page 8, Updated origin definition to include Online PIN
• Page 10, Updated origin and user agent definition
• Page 12, Added origin example for Online PIN
• Page 22, Replaced diagram and verbiage
• Page 25, Added Online Pin notation and ATS information
• Changed SSL to TLS
• Updated page numbers and sections as a result of the inclusion of the Recommendations section
April 2018 37
14.0 Revision Log
2.9 10/24/14 |B. Jones| See Below

• Page 4, Added AS2805 Spec for JAPA region and GCAG PwP
• Page 8, Added details on standard HTTP/1.1 message format as defined in RFC 2616 including sample
diagram
• Page 12, Added AS2805 and ISO Global EDC to the Message Type table
• Page 14, Removed Routing Indicator table, added note that Routing Indicator will be provided by
American Express representative
• Removed all references to IP Payments
• Updated page numbers throughout document due to the addition of new pages
2.8 4/19/13 | B. Jones | See Below

• Page 11, Removed GFSG XML IR and GFSG XML IDR references from table
• Page 11, Added details for GFSG XML BAR “Batch Admin Request” and for GFSG XML DCR “Data
Capture Request”
• Page 13, Removed GFSG XML IR and GFSG XML IDR references from table
2.7 10/19/12 | B. Jones | See Below

• Page 21, Added new details to use MTP through Internet Direct
2.6 4/20/12 | B. Jones | M. Miller | See Below

• Page 3, Added verbiage to clarify trusted certificates
• Page 7, Removed merchant reference from Origin definition
• Page 9, Removed merchant reference from Origin definition
• Page 9, Further clarification of the Origin definition.
• Page 11, Removed ISO DLA and ISO POSM
• Page 11, Changed ISO Global EDC to GEDC LAC
• Page 12, Added verbiage for ping messages
• Page 13, Added additional routing indicators for GEDC JAPA
• Page 13, Changed ISO Global EDC to GEDC LAC in the routing indicator table
• Page 21, Added verbiage to clarify usage of Java versions
• Throughout document, removed POS version control numbers and version number
April 2018 38
14.0 Revision Log
2.5 10/21/11 | B. Jones | R. Wong | See Below

• Throughout document, changed text from “Global Web Services” to “Internet Direct”.
• Page 4, deleted the following Supported File Formats:
– Credit Authorization Guide — POS020005
– WS PIP-XML Specification — POS020050
– MULTILINK Mexico and IDC Technical Specification — POS020068
• Page 8:
– Added, “Note: For details on populating these Header Values, see Request Message Header Value Descrip-
tions beginning on page 12.”
– Changed text as indicated, “Instead, merchants/vendors must transport Request Message data is transported
as the Request POST parameter AuthorizationRequestParam key value in the body of the Request Message
(via browser and terminal). This parameter value is the actual payload message.” Also, two-row table was
moved here from previous location when Request Message Header Value Descriptions were added.
• Pages 12-17: Created new subsection, Request Message Header Value Descriptions; and moved Message
Type and Routing Indicator tables from previous location to corresponding Header Value Descriptions.
• Pages 34-Error! Bookmark not defined., Country and Region Codes:
– Deleted, “Note 1: Alpha Country Codes (shown in shaded text) are included for reference only and should
not be used. Only numeric Country Codes and alpha Region Codes are used in the file layouts detailed in
this specification.” Also, deleted Alpha Country Codes from table.
– Changed Region Codes from “APA” to “JAPA”, 46 places.
– Changed Region Code for Japan from “LA/C” to “JAPA”.
– Added “South Sudan - EMEA” as a prohibited country.
• Added new cover and moved Revision Log to end of document.
• Throughout document: Added “Global”, as indicated, “Global Web Services IP Payments Gateway”.
• Page 4: Made the following changes:
– Deleted text, as indicated, “At this writing, the following Authorization File formats are supported”.
– In bullet for POS020055, changed text in title from “Proprietary, Non-XML” to “ISO 8583”.
Also, added the following supported file formats:
– GICC/GICC LITE Protocol for POS Authorizations (EMEA Region)
– APACS 30/APACS 40 Authorization Specification (EMEA Region)
– Global Electronic Data Capture for Terminals
– Global Financial Settlement Guide (XML Format)
– PRICE Specification for Spain
• Page 8: Changed bullet text, as indicated, “Make an HTTPS Connection to the provided Server Name, with
specified PROTOCOL URL and PORT”.
• Page 8: Added indicated text to the following sub-bullets:
– origin (Vendor or Merchant Name)
– country (Country Code; see page 34)
– region (Region Code; see page 34)
– message (Authorization Message Type being sent; see page 15)
– MerchNbr (Merchant Number of merchant sending the Authorization Request Message)
– RtInd (Routing Indicator where Authorization Message is to be routed; see page Error! Bookmark not
defined.)
• Page Error! Bookmark not defined.: Changed text from “Routing Indicator (use in RtInd parameter, on
previous page)” to “Routing Indicator — The following Routing Indicator codes are used in the request-
message Browser and Terminal Header RtInd parameters, which are described on page 10. Also, changed
the following Routing Indicators:
– Deleted 009.
April 2018 39
14.0 Revision Log
– Changed 010, as indicated, “APACS30 Traffic routed to BSH07 UK Stratus (Brighton)— Servicing UK,
Belgium (including Luxembourg), Holland, France, Italy, Finland and Poland
– Changed 011, as indicated, “GICC traffic routed to FRA03 German Stratus (Frankfurt) — Servicing
Germany, Switzerland and Sweden”.
– Added codes 012, 014, 015 and 016.
• Page 15: Changed text from “Message Types (use in message parameter, on previous page)” to “Message
Types — The following Message Type codes are used in the request-message Browser and Terminal Header
message parameters, which are described on page 10. Also, added the following Message Types: ISO
Global EDC, APACS 40, GFSG XML BAR, GFSG XML DCR, GFSG XML IDR, GFSG XML IR and
PRICE.
• Page 19: Changed subsection title, as indicated, “Standard HTTP Response Messages from Server”.
• Page 20: Changed subsection title, as indicated, “5.2 Java Error Response Messages Common Network
Socket Exceptions”. Also, changed “Problem” entries, as indicated:
– java.net.SocketException
– java.net.UnknownHostException:<host name>
– java.io.FileNotFoundException
• Page 21, Section 6.0 – Communication Details: Revised introductory paragraphs to clarify and improve
readability, with no change to technical content.
• Pages 23 and 25 (three occurrences): Changed text, as indicated,
“…qwww215318.americanexpress.com…”
• Pages 34-Error! Bookmark not defined.: Converted part of existing paragraph into Note 1, added “Note
2” for “prohibited countries” and updated Country and Region Codes table.

• Page 4: Changed from “Examples…are shown below” to “See examples…beginning on page 21”.
• Page 21: Changed Note from “…where the merchant/vendor sends the authorization request (Browser or
Terminal)” to “…where the authorization request originates (from either the merchant’s Browser or
Terminal)”.
• Page 31: Added underlined text, “Purpose: To transmit data through the System”.
2.2 02/25/09 | C. Van Blarcum / J. Cheney | R. Wong | See Below

• Page 25: Revised “OPEN CONNECTION” example.

• Page Error! Bookmark not defined.: Added Routing Indicators “007”, “008” and “009”, and Message
Type “EDC JAPA”.

• Page 29: Updated Example of C# Client.
• Page 30: Added “–Connect Method” to subsection title.
• Page 31: Added “–Send Method” to subsection title. Also, changed script text from “ISOMessage Auth” to
CardAuthorization”, two places.

• Page Error! Bookmark not defined.: Added Routing Indicators 010 and 011, and Message Types
APACS and GICC.

• Global: Changed partial URL from “ws/ISO MessageAuth.do” to “CardAuthorization.do”
• Page 8: Added bullet and sub-bullets beginning “The following request message header values must be pro-
vided to insure proper processing…”
April 2018 40
14.0 Revision Log

• Pages 30-31: Added new section 9.0, “Steps to Create a Test Client Using C++”, and renumbered remainder
of document.

• Global: Corrected capitalization on case-sensitive parameter names “country”, “region”, “origin” and
“message”.
• Page 4: Deleted POS010005; added POS020067.
• Page 10, both tables: Changed “Message Type” to “message”, changed font in first column, and added Note
below tables.
• Page 15, Message Type table: Changed from “(use in Message Type parameter…)” to “(… message para-
meter …)”; and added “WS DUAG”.
• Page 22: Changed “Message-Type” to “message”.
• Page 34: Updated Region Codes for JAPA.

• Pages 10-Error! Bookmark not defined.: Changed Origin from <Terminal> and <Software> to <Vendor
Name>, and added more Routing Indicator (RtInd) and Message Type Codes.
• Page 22: Added missing fields to example.

• Page 10-Error! Bookmark not defined.: Added “Origin” and updated Routing Indicator (RtInd) Codes.

• Page 10: Expanded last five items in Browser and Terminal Header Details - Request tables from “LAC
only” to add other countries.
• Page 15: Added Message Types.
• Page 33: Added Country & Region Codes.

• Throughout document: Changed most references from “merchant” to “merchant/vendor”.
• Pages 4-30: Replaced nearly all content in Sections 3 thru 6, and added Sections 7 thru 9.

• Page 4: Added Section 3.0, Attributes for Header & Request Values, and renumbered remaining sections.

Initial release.
April 2018 41
April 2018 42

AMEX HTTPS Comms Guide-April 2018

Uploaded by

Copyright:

Available Formats

You might also like

AMEX HTTPS Comms Guide-April 2018

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

AMEX HTTPS Comms Guide-April 2018

Uploaded by

Copyright:

Available Formats

INTERNET DIRECT

HTTPS COMMUNICATION GUIDE

GLOBAL NETWORK BUSINESS

Document Version 3.6

1.0 Introduction ....................................................................................................................... 1

This page is intentionally left blank.

This page is intentionally left blank.

2.2 High-Level Design

At this writing, the following file formats are supported:

 Global Credit Authorization Guide (ISO)

 Global Credit Authorization Guide (XML)

 GICC/GICC Light Protocol for POS Authorizations - EMEA Region

 Standard 70 Authorization Specification - EMEA Region

 Global Electronic Data Capture Specification (GEDC)

 Global Financial Settlement Guide (XML Format)

 PRICE - Specification for Spain

 Global Hostlink Data Capture (GHDC) - LAC, Canada, Americas

 Connections must be made via the URL

This page is intentionally left blank.

 Make an HTTPS Connection to the provided URL and PORT.

 Set the request authorization message as a byte-stream in the hidden parameter:

 Terminal will open up URL Connection.

 Internet Direct requires the transaction message contained within AuthorizationRequestParam to

Request Body Details for Browser and Terminal

Overview of a standard HTTPS/1.1 message format as defined in RFCs (7230-7237).

Sample HTTPS message diagram:

Browser Header Details — Request

Host <URL:Provided to Merchant/Vendor by American Express Technical

Merchants using online PIN and GHDC should use <ProcessorName-PortNumber>

country See Country and Region Code information on page 34.

Terminal Header Details — Request

region See Country and Region Code information on page 34.

Note: Parameter names in first column of tables above are case-sensitive.

Header Value origin

Header Type: Alphanumeric

Header Requirement: Mandatory

Description: This header value contains an alphanumeric value which refers

Examples: Origin: Vendor/Developing Entity

Header Value country

Header Type: Numeric

Header Requirement: Mandatory

Description: This header value contains a three-digit, numeric Country code

Example: Country: 840

Note: Country Code “840” = USA

Header Value region

Header Type: Alphanumeric and special characters

Header Requirement: Mandatory

Example: Region: JAPA

Header Value message

Header Type: Alphanumeric

Header Requirement: Mandatory

Message Type Description

Example: Message: ISO GCAG

Header Value MerchNbr

Header Type: Numeric

Header Requirement: Mandatory

Description: This header value contains the American Express-assigned

Example: MerchNbr: 123456789

Note: For those messages that don’t contain a valid Merchant