Gateway Web Service API Integration Guide Version 2017-3 (Australia IPG) © 2016 First Data Corporation. All Rights Reserved. All trademarks, service marks and trade names referenced in this material are the property of their respective owners. Contents This table of contents has been amended to exclude sections not applicable to Australia. The original content is still available in this document. 1 Introduction 5 2 Artefacts You Need 6 3 How the API works 7 4 Sending transactions to the gateway 9 5 Building Transactions in XML 10 5.1 Credit/Debit Card transactions 10 5.1.1 Sale 11 5.1.2 Pre-Authorisation 11 5.1.3 Post-Authorisation 12 5.1.5 Return 13 5.1.7 Void 14 5.1.8 Recurring Sale (Merchant-triggered) 15 5.8 Generic Transaction Type for Voids and Returns 28 6 Additional Web Service actions 31 6.1 Initiate Clearing 31 6.2 Inquiry Order 31 6.3 Inquiry Transaction 32 6.4 Get Last Orders 33 6.4.1 Latest orders of a Store 33 6.4.2 Latest orders of a Store within a given date range 33 6.4.3 All orders of a Store after a given Order ID 34 6.4.4 Response 34 6.5 Get Last Transactions 38 6.5.1 Latest transactions of a Store 39 6.5.2 All transactions of a Store after a given Transaction ID 39 6.5.3 Response 39 6.6 Recurring Payments (Scheduler) 41 6.6.1 Install 41 6.6.2 Modify 42 6.6.3 Cancel 43 6.6.4 Test Recurring Payments in test environment 43 6.6.5 Response 44 6.7 External transaction status 44 6.8 Trigger email notifications 44 6.9 Card Information Inquiry 44 6.10 Basket Information and Product Catalogue 45 6.10.1 Basket information in transaction messages 45 6.10.2 Setting up a Product Catalogue 46 6.10.3 Manage Product Stock 47 6.10.4 Sale transactions using product stock 48 7 Data Vault 49 7.1 Token Type Options 49 7.2 Store or update payment information when performing a transaction 52 7.3 Store payment information from an approved transaction 52 7.4 Initiate payment transactions using stored data 53 7.5 Store payment information without performing a transaction at the same time 53 7.6 Avoid duplicate cardholder data for multiple records 55 API Integration Guide v2017-3 2 7.7 Display stored records 55 7.8 Delete existing records 56 8 Dynamic Currency Conversion and Dynamic Pricing (Multi Currency Conversion) 57 8.1 Exchange rate requests for Dynamic Currency Conversion 57 8.2 Exchange rate requests for Dynamic Pricing 58 8.3 Exchange rate reponses 59 8.4 Conversion offering 59 8.5 Declined rate request 60 8.6 Failed rate request 61 8.7 Dynamic Currency Conversion transactions 61 8.7.1 Step 1: Rate request 61 8.7.2 Step 2: Using the conversion rate for the payment transaction 62 9 Payment URL 64 13 XML-Tag overview 72 13.1 Overview by transaction type 72 13.2 Description of the XML-Tags 81 13.2.1 CreditCardTxType 81 13.2.2 CreditCardData 81 13.2.3 recurringType 82 13.2.4 Wallet 82 13.2.5 cardFunction 82 13.2.14 Payment 86 13.2.15 TransactionDetails 86 13.2.16 InquiryRateReference 88 13.2.17 Billing 88 13.2.18 Shipping 89 13.2.19 TopUpTxType 89 13.2.20 ClientLocale 90 13.2.21 RequestCardRateForDCC 90 13.2.22 RequestMerchantRateForDynamicPricing 90 13.2.23 CardRateForDCC and MerchantRateForDynamicPricing 90 14 Custom Parameters 92 15 Building a SOAP Request Message 92 16 Reading the SOAP Response Message 94 16.1 SOAP Response Message 94 16.2 SOAP Fault Message 95 16.3 SOAP-ENV:Server 96 16.4 SOAP-ENV:Client 96 17 Analysing the Transaction Result 99 17.1 Transaction Approval 99 17.2 Transaction Failure 100 18 Building an HTTPS POST Request 102 18.1 PHP 103 18.1.1 Using the cURL PHP Extension 103 18.1.2 Using the cURL Command Line Tool 104 18.2 ASP 104 19 Establishing a TLS connection 105 19.1 PHP 105 19.1.1 Using the PHP cURL Extension 106 19.1.2 Using the cURL Command Line Tool 106 19.2 ASP 106 20 Sending the HTTPS POST Request and Receiving the Response 108 20.1 PHP 109 API Integration Guide v2017-3 3 20.1.1 Using the PHP cURL Extension 109 20.1.2 Using the cURL Command Line Tool 109 20.2 ASP 110 21 Using a Java Client to connect to the web service 110 21.1 Instance an IPGApiClient 110 21.2 How to construct a transaction and handle the response 111 21.3 How to construct an action 112 21.4 How to connect behind a proxy 112 22 Using a .NET Client to connect to the Web Service 112 23 Appendix 113 24 Troubleshooting - Merchant Exceptions 114 25 Troubleshooting - Processing Exceptions 118 26 Troubleshooting - Login error messages when using cURL 122 27 Troubleshooting - Login error messages when using the Java Client 124 Getting Support There are different manuals available for First Data‟s eCommerce solutions. This Integration Guide will be the most helpful for integrating the Web Service API for usage with our distribution channels in Europe, Asia, Australia, Latin America and Africa. Please note, the First Data Gateway solution in Australia is not the same as the Payeezy solution in USA. For information about settings, customisation, reports and how to process transactions manually (by keying in the information) please refer to the User Guide Virtual Terminal & Manager. If you have read the documentation and cannot find the answer to your question, please contact your local support team. Information for merchants with existing Web Service API integration using the Java client to connect to the web service:  The implementation of the IPGApiClient and some signatures of methods of this class have been changed due to a change from appache http client 3.x to appache http client 4.x  Transaction classes and transaction factory have not been changed  If the previous IPGApiClient works in your environment, you can continue to use it. API Integration Guide v2017-3 4 1 Introduction The Web Service API is an Application Programming Interface which allows you to connect your application with the First Data Internet Payment Gateway. In this way, your application is able to submit payment transactions without any user interference. Please note that if you store or process cardholder data within your own application, you must ensure that your system components are compliant with the Data Security Standard of the Payment Card Industry (PCI DSS). Depending on your transaction volume, an assessment by a Qualified Security Assessor may be mandatory to declare your compliance status. From a technical point of view, this API is a Web Service offering one remote operation for performing transactions. The three core advantages of this design can be summarized as follows:  Platform independence: Communicating with the Web Service API means that your application must only be capable of sending and receiving SOAP messages. There are no requirements tied to a specific platform, since the Web Service technology builds on a set of open standards. In short, you are free to choose any technology you want (e.g. J2EE, .NET, PHP, ASP, etc.) for making your application capable of communicating with the Web Service API.  Easy integration: Communicating with a Web Service is simple – your application has to build a SOAP request message encoding your transaction, send it via HTTPS to the Web Service and wait for a SOAP response message which contains your transaction‟s status report. Since SOAP and HTTP are designed to be lightweight protocols, building requests and responses becomes a straightforward task. Furthermore, you rarely have to do this manually, since there are plenty of libraries available in almost every technology. In general, building a SOAP request and handling the response is reduced to a few lines of code.  Security: All communication between your application and the Web Service API is TLS-encrypted. This is established by your application holding a client certificate which identifies it uniquely at the Web Service. In the same way, the First Data Internet Payment Gateway holds a server certificate which your application may check for making sure that it speaks to our Web Service API. Finally, your application has to do a basic authorisation (user name / password) before being allowed to communicate with the Web Service. In this way, the users who are authorised to communicate with the First Data Internet Payment Gateway are identified. These two security mechanisms guarantee that the transaction data sent to First Data both stays private and is identified as transaction data that your application has committed and belongs to no one else. While this represents just a short summary of the Web Service API‟s features, the focus of this guide lies on integrating the First Data Internet Payment Gateway functionality into your application. A detailed description, explaining how this is done step by step, is presented in this guide. API Integration Guide v2017-3 5 2 Artefacts You Need Supporting a high degree of security requires several artefacts you need for communicating securely with the Web Service API. Since these artefacts are referenced throughout the remainder of this guide, the following checklist shall provide an overview enabling you to make sure that you have received the whole set when registering your application for the First Data Internet Payment Gateway:  Store ID: Your store ID (e.g. 10012345678) which is required for the basic authorization.  User ID: The user ID denoting the user who is allowed to access the Web Service API, e.g. 1. Again, this is required for the basic authorization.  Password: The password required for the basic authorization.  Client Certificate p12 File: The client certificate stored in a p12 file having the naming scheme WSstoreID._.userID.p12, e.g. in case of the above store ID / user ID examples, this would be WS101._.007.p12. This file is used for authenticating the client at the Internet Payment Gateway. For connecting with Java you need a ks-File, e.g.: WS10012345678._.1.ks.  Client Certificate Installation Password: The password which is required for installing the p12 client certificate file.  Client Certificate Private Key: The private key of the client certificate stored in a key file having the naming scheme WSstoreID._.userID.key, e.g. in case of the above store ID / user ID examples, this would be WS10012345678._.1.key. Some tools which support you in setting up your application for using the Web Service API require this password when doing the client authentication at the Internet Payment Gateway.  Client Certificate Private Key Password: This password protects the private key of the client certificate. Some tools which support you in setting up your application for using the Web Service API require this password when doing the client authentication at the Internet Payment Gateway. It follows the naming scheme ckp_creationTimestamp. For instance, this might be ckp_1193927132.  Client Certificate PEM File: The client certificate stored in a PEM file having the naming scheme WSstoreID._.userID.pem, e.g. in case of the above store ID / user ID examples, this would be WS10012345678._.1.pem. Some tools which support you in setting up your application for using the Internet Payment Gateway require this file instead of the p12 file described above.  Server Certificate PEM File: The server certificate stored in the PEM file geotrust.pem which is required for authenticating the server running the Web Service API. For connecting with Java you need the truststore.ks-file. If you should be planning to handle multiple Store IDs through your integration, we can issue a special API User and Client Certificate for you that you can use across all your Stores. When you submit transactions from that API user, you do not need to vary the API User Name as the API User is the same for all your Stores. You will need to include the Store ID in each transaction request in that case. API Integration Guide v2017-3 6 3 How the API works The following section describes the API by means of a credit card transaction. The process for other payment types is similar. In most cases, a customer starts the overall communication process by buying goods or services with her credit card in your online store. Following this, your store sends a credit card transaction (mostly in order to capture the customer‟s funds) via the Web Service API. Having received the transaction, the First Data Internet Payment Gateway forwards it to the credit card processor for authorisation. Based on the result, an approval or error is returned to your online store. This means that all communication and processing details are covered by the First Data Internet Payment Gateway and you only have to know how to communicate with this Web Service. The Web Service Standard defines such an interface by using the Web Service Definition Language (WSDL). A WSDL file defining the Web Service API for the First Data Internet Payment Gateway can be found at: https://test.ipg-online.com/ipgapi/services/order.wsdl Note that you will have to supply your client certificate, your credentials, and the server certificate when viewing or requesting the file e.g. in a Web browser. For instance, in case you want to view the WSDL file in Microsoft‟s Internet Explorer running on Microsoft Windows XP, you first have to install your client certificate and the server certificate, and then call the above URL. This is done by executing the following steps: 1. Open the folder in which you have saved your client certificate p12 file. 2. Double-click the client certificate p12 file. 3. Click Next. Check the file name (which should be already set to the path of your client certificate p12 file) and click Next. 4. Provide the client certificate installation password and click Next. 5. Choose the option Automatically select the certificate store based on the type of certificate and click Next. This will place the certificate in your personal certificate store (more precisely in the local Windows user‟s personal certificate store). 6. Check the displayed settings and click Finish. Your client certificate is now installed. 7. Now, you have to install the server certificate. The most straightforward way to do this is to open the folder in which you have saved your server certificate PEM file and rename the file to geotrust.crt. 8. Then, double-click the renamed server certificate file. 9. Click Install Certificate. This starts the same wizard as above. 10. Click Next. Select Place all certificates in the following store and browse for the Trusted Root Certification Authorities folder. Click Next. 11. Check the displayed settings and click Finish (you might have to confirm the installation). The server certificate is now installed in the local computer‟s trusted certificates store. Here, Microsoft Internet Explorer can lookup the server certificate API Integration Guide v2017-3 7 for verifying the First Data Internet Payment Gateway server certificate received when calling the WSDL URL above. 12. Now, open a Microsoft Internet Explorer window and provide the above URL in the address field. 13. After requesting the URL, the server will ask your browser to supply the client certificate to making sure that it is talking to your application correctly. Since you have installed the certificate in the previous steps, it is transferred to the server without prompting you for any input (i.e. you will not notice this process). Then, the First Data Internet Payment Gateway sends its server certificate (identifying it uniquely) to you. This certificate is verified against the trusted one you have installed above. Again, this is done automatically without prompting you for any input. Now, a secure connection is established and all data transferred between your application and the Web Service API is TLS-encrypted. 14. Next, you will be prompted to supply your credentials for authorisation. As user name you have to provide your store ID and user ID encoded in the format WSstoreID._.userID (unless you manage multiple Stores through your integration). For instance, assuming your store ID is 101, your user ID 007, and your password myPW, you have to supply WS101._.007 in the user name field and myPW in the password field. Note that your credentials are encrypted before being passed to the server due to the TLS connection established in the steps above. Then, click OK. 15. The Web Service API WSDL file is displayed. In short, the WSDL file defines the operations offered by the Web Service, their input and return parameters, and how these operations can be invoked. In case of the First Data Internet Payment Gateway Web Service API, it defines only one operation (IPGApiOrder) callable by sending a SOAP HTTP request to the following URL: https://test.ipg-online.com/ipgapi/services This operation takes an XML-encoded transaction as input and returns an XML-encoded response. Note that it is not necessary to understand how the WSDL file is composed for using the First Data Internet Payment Gateway. The following chapters will guide you in setting up your store for building and performing custom credit card transactions. However, in case you are using third-party tools supporting you in setting up your store for accessing the Web Service API, you might have to supply the URL where the WSDL file can be found. In a similar way as described above, you have to tell your Web Service tool, that the communication is TLS-enabled, requiring you to provide your client certificate and accept the server certificate as a trusted one. Furthermore, you have to supply your credentials. How all is done heavily depends on your Web Service tool. Hence, check the tool‟s documentation for details. API Integration Guide v2017-3 8 4 Sending transactions to the gateway The purpose of this chapter is to give you a basic understanding of the steps to be taken when committing transactions to the First Data Internet Payment Gateway. It describes what happens if a customer pays with her credit card in an online store using the Web Service API for committing transactions.  The customer clicks on the Pay button in the online store.  The online store displays a form asking the customer to provide her credit card number and the expiry month and year.  The customer types in these three fields and submits the data to the online store (i. e. purchases the goods).  The online store receives the data and builds an XML document encoding a Sale transaction which includes the data provided by the customer and the total amount to be paid by the customer.  After building the XML Sale transaction, the online store wraps it in a SOAP message which describes the Web Service operation to be called with the transaction XML being passed as a parameter.  Having built the SOAP message, the online store prepares it for being transferred over the Internet by packing its content into an HTTPS POST request. Furthermore, the store sets the HTTP headers, especially its credentials (note that the credentials are the same as the ones you have to provide for viewing the WSDL file).  Now, the store establishes a TLS connection by providing the client and server certificate.  Then, the online store sends the HTTPS request to the Web Service API and waits for an HTTP response.  The Web Service API receives the HTTPS request and parses out the authorization information provided by the store in the HTTP headers.  Having authorized the store to use the First Data Internet Payment Gateway, the SOAP message contained in the HTTP request body is parsed out. This triggers the Web Service operation handling the transaction processing to run.  The Internet Payment Gateway then performs the transaction processing, builds an XML response document, wraps it in a SOAP message, and sends this SOAP message back to the client in the body of an HTTPS response.  Receiving this HTTPS response wakes up the store which reads out the SOAP message and response XML document being part of it.  Depending on the data contained in the XML response document an approval page is sent back to the customer in case of a successful transaction, otherwise an error page is returned.  The approval or error page is displayed. While this example describes the case of a Sale transaction, other transactions basically follow the same process. API Integration Guide v2017-3 9 Summarising the scenario, your application has to perform the following steps in order to commit credit card transactions and analyze the result:  Build an XML document encoding your transactions  Wrap that XML document in a SOAP request message  Build an HTTPS POST request with the information identifying your store provided in the HTTP header and the SOAP request message in the body  Establish a TLS connection between your application and the Web Service API  Send the HTTPS POST request to the First Data Internet Payment Gateway and receive the response  Read the SOAP response message out of the HTTPS response body  Analyse the XML response document contained in the SOAP response message These seven steps are described in the following chapters. They guide you through the process of setting up your application for performing custom credit card transactions. 5 Building Transactions in XML This chapter describes how the different transaction types can be built in XML. As the above example scenario has outlined, a transaction is first encoded in an XML document which is then wrapped as payload in a SOAP message. That means the XML-encoded transaction represents the parameter passed to the Web Service API operation. Note that there exists a variety of Web Service tools supporting you in the generation of client stubs which might free you of the necessity to deal with raw XML. However, a basic understanding of the XML format is crucial in order to build correct transactions regardless of the available tool support. Hence, it is recommended to become familiar with the XML format used by the Web Service API for encoding transactions. 5.1 Credit/Debit Card transactions Regardless of the transaction type, the basic XML document structure of a credit/debit card transaction is as follows: <ipgapi:IPGApiOrderRequest xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1" xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi"> <v1:Transaction> <v1:CreditCardTxType>...</v1:CreditCardTxType> <v1:CreditCardData>...</v1:CreditCardData> <v1:Payment>...</v1:Payment> <v1:TransactionDetails>...</v1:TransactionDetails> <v1:Billing>...</v1:Billing> <v1:Shipping>...</v1:Shipping> </v1:Transaction> </ipgapi:IPGApiOrderRequest> The element CreditCardDataTXType is mandatory for all credit card transactions. The other elements depend on the transaction type. The transaction content is type-specific. API Integration Guide v2017-3 10