Gateway Web Service API Integration Guide Version 2017-6 (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 1 Introduction 6 2 Artefacts You Need 7 3 How the API works 8 4 Sending transactions to the gateway 10 5 Building Transactions in XML 11 5.1 Credit/Debit Card transactions 11 5.1.1 Sale 12 5.1.2 Pre-Authorisation 13 5.1.3 Post-Authorisation 13 5.1.4 ForceTicket 14 5.1.5 Return 14 5.1.6 Credit 15 5.1.7 Void 16 5.1.8 Recurring Sale (Merchant-triggered) 16 5.1.9 Standing Instructions 17 5.2 MasterPass™ 18 5.3 SEPA Direct Debit – Germany 19 5.3.1 Sale 19 5.3.2 Void 20 5.3.3 Credit 20 5.3.4 Return 21 5.4 PayPal 21 5.4.1 Recurring Payment Transaction 21 5.4.2 Return 22 5.4.3 Void 23 5.4.4 Credit 23 5.5 SOFORT Überweisung 24 5.5.1 Return 24 5.6 Klarna 25 5.6.1 Pre-Authorisation (Reservation) 25 5.6.2 Post-Authorisation (Activation) 27 5.6.3 Return 28 5.6.4 Void 29 5.7 iDEAL 29 5.7.1 Return 29 5.8 Generic Transaction Type for Voids and Returns 30 6 Additional Web Service actions 32 6.1 Initiate Clearing 32 6.2 Inquiry Order 32 6.3 Inquiry Transaction 36 6.4 Get Last Orders 37 6.4.1 Latest orders of a Store 37 6.4.2 Latest orders of a Store within a given date range 37 6.4.3 All orders of a Store after a given Order ID 38 6.4.4 Response 38 6.5 Get Last Transactions 42 6.5.1 Latest transactions of a Store 42 6.5.2 All transactions of a Store after a given Transaction ID 43 6.5.3 Response 43 6.6 Recurring Payments (Scheduler) 45 API Integration Guide v2017-6 2 6.6.1 Install 45 6.6.2 Modify 46 6.6.3 Cancel 46 6.6.4 Test Recurring Payments in test environment 47 6.6.5 Response 47 6.7 External transaction status 48 6.8 Trigger email notifications 48 6.9 Card Information Inquiry 48 6.10 Basket Information and Product Catalogue 49 6.10.1 Basket information in transaction messages 49 6.10.2 Setting up a Product Catalogue 49 6.10.3 Manage Product Stock 51 6.10.4 Sale transactions using product stock 51 7 Data Vault 53 7.1 Token Type Options 53 7.2 Store or update payment information when performing a transaction 56 7.3 Store payment information from an approved transaction 56 7.4 Initiate payment transactions using stored data 57 7.5 Store payment information without performing a transaction at the same time 57 7.6 Avoid duplicate cardholder data for multiple records 59 7.7 Display stored records 59 7.8 Delete existing records 60 8 Dynamic Currency Conversion and Dynamic Pricing (Multi Currency Conversion) 61 8.1 Exchange rate requests for Dynamic Currency Conversion 61 8.2 Exchange rate requests for Dynamic Pricing 62 8.3 Exchange rate reponses 63 8.4 Conversion offering 63 8.5 Declined rate request 64 8.6 Failed rate request 65 8.7 Dynamic Currency Conversion transactions 65 8.7.1 Step 1: Rate request 65 8.7.2 Step 2: Using the conversion rate for the payment transaction 66 9 Payment URL 68 10 Solvency Information from Bürgel 70 11 Mobile top-ups 71 12 3DSecure Authentication 72 13 Purchasing Card 76 14 XML-Tag overview 79 14.1 Overview by transaction type 79 14.2 Description of the XML-Tags 88 14.2.1 CreditCardTxType 88 14.2.2 CreditCardData 88 14.2.3 recurringType 89 14.2.4 Wallet 89 14.2.5 cardFunction 90 14.2.6 CreditCard3DSecure 90 14.2.7 India Mobile / IVR Extension Verification Request 90 14.2.8 India Mobile / IVR Extension Authentication Request 91 14.2.9 3DSecure Authentication / Verification Redirect Response 91 14.2.10 3DSecure Authentication / ACS Response 92 14.2.11 DE_DirectDebitTxType 92 14.2.12 DE_DirectDebitData 92 14.2.13 PayPalTxType 93 14.2.14 Payment 93 API Integration Guide v2017-6 3 14.2.15 TransactionDetails 94 14.2.16 Purchasing Cards 95 14.2.17 Purchasing Cards/ Line Item Data 96 14.2.18 InquiryRateReference 96 14.2.19 Billing 97 14.2.20 Shipping 97 14.2.21 TopUpTxType 98 14.2.22 ClientLocale 98 14.2.23 RequestCardRateForDCC 98 14.2.24 RequestMerchantRateForDynamicPricing 99 14.2.25 CardRateForDCC and MerchantRateForDynamicPricing 99 14.2.26 MCC 6012 Visa and Mastercard Mandate 100 14.2.27 Market Segment Addendum 100 15 Custom Parameters 100 15.1 Additional Parameters for Fraud Detect 100 16 Building a SOAP Request Message 102 17 Reading the SOAP Response Message 103 17.1 SOAP Response Message 103 17.2 SOAP Fault Message 105 17.3 SOAP-ENV:Server 105 17.4 SOAP-ENV:Client 106 18 Analysing the Transaction Result 108 18.1 Transaction Approval 108 18.2 Transaction Failure 110 19 Building an HTTPS POST Request 111 19.1 PHP 112 19.2 ASP 114 20 Establishing a TLS connection 114 20.1 PHP 115 20.1.1 Using the PHP cURL Extension 115 20.1.2 Using the cURL Command Line Tool 115 20.2 ASP 116 21 Sending the HTTPS POST Request and Receiving the Response 118 21.1 PHP 118 21.1.1 Using the PHP cURL Extension 118 21.1.2 Using the cURL Command Line Tool 119 21.2 ASP 119 22 Using a Java Client to connect to the web service 120 22.1 Instance an IPGApiClient 120 22.2 How to construct a transaction and handle the response 121 22.3 How to construct an action 121 22.4 How to connect behind a proxy 121 23 Using a .NET Client to connect to the Web Service 122 24 Appendix 123 24.1 Test Transactions 123 24.2 XML 123 24.3 XML Schemata 123 25 Troubleshooting - Merchant Exceptions 124 26 Troubleshooting - Processing Exceptions 128 27 Troubleshooting - Login error messages when using cURL 132 28 Troubleshooting - Login error messages when using the Java Client 134 29 Troubleshooting - .NET integration issues 135 API Integration Guide v2017-6 4 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-6 5 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-6 6 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-6 7 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-6 8 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-6 9 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-6 10