Internet Payment Gateway Integration Guide First Data API. Version 1.5 (EMEA)

Transcription

1 Internet Payment Gateway Integratin Guide First Data API Versin 1.5 (EMEA)

2 First Data Internet Payment Gateway INTEGRATION GUIDE FIRST DATA API VERSION 1.5 (EMEA) Cntents 1 Intrductin 4 2 Artefacts Yu Need 5 3 Hw the API wrks 5 4 Sending transactins t the gateway 7 5 Building Transactins in XML Credit Card transactins Sale PreAuth PstAuth FrceTicket Return Credit Vid UK Debit Sale Return Credit Vid German Direct Debit Sale Vid 15 6 Additinal Web Service actins Initiate Clearing Inquiry Order Recurring Payments 18 7 Data Vault 20 8 XML-Tag verview Overview by transactin type Descriptin f the XML-Tags CreditCardTxType CreditCardData CreditCard3DSecure DE_DirectDebitTxType DE_DirectDebitData Payment TransactinDetails Billing Shipping 28 9 Building a SOAP Request Message Reading the SOAP Respnse Message SOAP Respnse Message SOAP Fault Message SOAP-ENV:Server 32 firstdata.cm 2

3 SOAP-ENV:Client Analysing the Transactin Result Transactin Apprval Transactin Failure Building an HTTPS POST Request PHP Using the curl PHP Extensin Using the curl Cmmand Line Tl ASP Establishing an SSL cnnectin PHP Using the PHP curl Extensin Using the curl Cmmand Line Tl ASP Sending the HTTPS POST Request and Receiving the Respnse PHP Using the PHP curl Extensin Using the curl Cmmand Line Tl ASP Using a Java Client t cnnect t the web service Instance an IPGApiClient Hw t cnstruct a transactin and handle the respnse Hw t cnstruct an actin Hw t cnnect behind a prxy 47 Appendix 48 ipgapi.xsd 48 v1.xsd 50 a1.xsd 60 Trubleshting - Merchant Exceptins 64 Trubleshting - Prcessing Exceptins 68 Trubleshting - Lgin errr messages when using curl 72 Trubleshting - Lgin errr messages when using the Java Client 74 Getting Supprt There are different manuals available fr the First Data Internet Payment Gateway. This Integratin Guide First Data API will be the mst helpful fr integratin issues. Fr infrmatin abut settings, custmisatin, reprts and hw t prcess transactins manually (by keying in the infrmatin) please refer t the First Data Virtual Terminal User Guide. If yu have read the dcumentatin and cannt find the answer t yur questin, please cntact yur lcal supprt team. firstdata.cm 3

4 1 Intrductin The First Data API is an Applicatin Prgramming Interface which allws yu t cnnect yur applicatin with the First Data Internet Payment Gateway. In this way, yur applicatin is able t submit credit card transactins withut any user interference. Please nte that if yu stre r prcess cardhlder data within yur wn applicatin, yu must ensure that yur system cmpnents are cmpliant with the Data Security Standard f the Payment Card Industry (PCI DSS). Depending n yur transactin vlume, an assessment by a Qualified Security Assessr may be mandatry t declare yur cmpliance status. Frm a technical pint f view, the First Data API is a Web Service ffering ne remte peratin fr perfrming transactins. The three cre advantages f this design can be summarized as fllws: Platfrm independence: Cmmunicating with the First Data API Web Service means that yur applicatin must nly be capable f sending and receiving SOAP messages. There are n requirements tied t a specific platfrm, since the Web Service technlgy builds n a set f pen standards. In shrt, yu are free t chse any technlgy yu want (e.g. J2EE,.NET, PHP, ASP, etc.) fr making yur applicatin capable f cmmunicating with the First Data API Web Service. Easy integratin: Cmmunicating with a Web Service is simple yur applicatin has t build a SOAP request message encding yur transactin, send it via HTTPS t the Web Service and wait fr a SOAP respnse message which cntains yur transactin s status reprt. Since SOAP and HTTP are designed t be lightweight prtcls, building requests and respnses becmes a straightfrward task. Furthermre, yu rarely have t d this manually, since there are plenty f libraries available in almst every technlgy. In general, building a SOAP request and handling the respnse is reduced t a few lines f cde. Security: All cmmunicatin between yur applicatin and First Data API is SSLencrypted. This is established by yur applicatin hlding a client certificate which identifies it uniquely at the Web Service. In the same way, the First Data API hlds a server certificate which yur applicatin may check fr making sure that it speaks t the API Web Service. Finally, yur applicatin has t d a basic authrizatin (user name / passwrd) befre being allwed t cmmunicate with the Web Service. In this way, the users wh are authrized t cmmunicate with First Data API are identified. These tw security mechanisms guarantee that the transactin data sent t First Data API bth stays private and is identified as transactin data that yur applicatin has cmmitted and belngs t n ne else. While this represents just a shrt summary f First Data API s features, the fcus f this guide lies n integrating the First Data API functinality int yur applicatin. A detailed descriptin, explaining hw this is dne step by step, is presented in this guide. The first chapter describes all the supprted transactin types. firstdata.cm 4

5 2 Artefacts Yu Need Supprting a high degree f security requires several artefacts yu need fr cmmunicating securely with First Data API. Since these artefacts are referenced thrughut the remainder f this guide, the fllwing checklist shall prvide an verview enabling yu t make sure that yu have received the whle set when registering yur applicatin fr the First Data Internet Payment Gateway: Stre ID: Yur stre ID (e.g. 101) which is required fr the basic authrizatin. User ID: The user ID denting the user wh is allwed t access First Data API, e.g Again, this is required fr the basic authrizatin. Passwrd: The passwrd required fr the basic authrizatin. Client Certificate p12 File: The client certificate stred in a p12 file having the naming scheme WSstreID._.userID.p12, e.g. in case f the abve stre ID / user ID examples, this wuld be WS101._.007.p12. This file is used fr authenticating the client at the Internet Payment Gateway. Fr cnnecting with Java yu need a ks-file, e.g.: WS101._.007.ks. Client Certificate Installatin Passwrd: The passwrd which is required fr installing the p12 client certificate file. Client Certificate Private Key: The private key f the client certificate stred in a key file having the naming scheme WSstreID._.userID.key, e.g. in case f the abve stre ID / user ID examples, this wuld be WS101._.007.key. Sme tls which supprt yu in setting up yur applicatin fr using First Data API require this passwrd when ding the client authenticatin at the Internet Payment Gateway. Client Certificate Private Key Passwrd: This passwrd prtects the private key f the client certificate. Sme tls which supprt yu in setting up yur applicatin fr using First Data API require this passwrd when ding the client authenticatin at the Internet Payment Gateway. It fllws the naming scheme ckp_creatintimestamp. Fr instance, this might be ckp_ Client Certificate PEM File: The client certificate stred in a PEM file having the naming scheme WSstreID._.userID.pem, e.g. in case f the abve stre ID / user ID examples, this wuld be WS101._.007.pem. Sme tls which supprt yu in setting up yur applicatin fr using the Internet Payment Gateway require this file instead f the p12 file described abve. Server Certificate PEM File: The server certificate stred in the PEM file getrust.pem which is required fr authenticating the server running First Data API. Fr cnnecting with Java yu need the truststre.ks-file. 3 Hw the API wrks The fllwing sectin describes the API by means f a credit card transactin. The prcess fr ther payment types is similar. firstdata.cm 5

6 In mst cases, a custmer starts the verall cmmunicatin prcess by buying gds r services with her credit card in yur nline stre. Fllwing this, yur stre sends a credit card transactin (mstly in rder t capture the custmer s funds) via First Data API. Having received the transactin, the First Data Internet Payment Gateway frwards it t the credit card prcessr fr authrisatin. Based n the result, an apprval r errr is returned t yur nline stre. This means that all cmmunicatin and prcessing details are cvered by the First Data API interface and yu nly have t knw hw t cmmunicate with this Web Service. The Web Service Standard defines such an interface by using the Web Service Definitin Language (WSDL). In case f First Data API, a WSDL file defining the Web Service can be fund at: Nte that yu will have t supply yur client certificate, yur credentials, and the server certificate when viewing r requesting the file e.g. in a Web brwser. Fr instance, in case yu want t view the WSDL file in Micrsft s Internet Explrer running n Micrsft Windws XP, yu first have t install yur client certificate and the server certificate, and then call the abve URL. This is dne by executing the fllwing steps: 1. Open the flder in which yu have saved yur client certificate p12 file. 2. Duble-click the client certificate p12 file. 3. Click Next. Check the file name (which shuld be already set t the path f yur client certificate p12 file) and click Next. 4. Prvide the client certificate installatin passwrd and click Next. 5. Chse the ptin Autmatically select the certificate stre based n the type f certificate and click Next. This will place the certificate in yur persnal certificate stre (mre precisely in the lcal Windws user s persnal certificate stre). 6. Check the displayed settings and click Finish. Yur client certificate is nw installed. 7. Nw, yu have t install the server certificate. The mst straightfrward way t d this is t pen the flder in which yu have saved yur server certificate PEM file and rename the file t getrust.crt. 8. Then, duble-click the renamed server certificate file. 9. Click Install Certificate. This starts the same wizard as abve. 10. Click Next. Select Place all certificates in the fllwing stre and brwse fr the Trusted Rt Certificatin Authrities flder. Click Next. 11. Check the displayed settings and click Finish (yu might have t cnfirm the installatin). The server certificate is nw installed in the lcal cmputer s trusted certificates stre. Here, Micrsft Internet Explrer can lkup the server certificate fr verifying the First Data API server certificate received when calling the WSDL URL abve. 12. Nw, pen a Micrsft Internet Explrer windw and prvide the abve URL in the address field. 13. After requesting the URL, the server will ask yur brwser t supply the client certificate t making sure that it is talking t yur applicatin crrectly. Since yu have installed the certificate in the previus steps, it is transferred t the server firstdata.cm 6

7 withut prmpting yu fr any input (i.e. yu will nt ntice this prcess). Then, First Data API sends its server certificate (identifying it uniquely) t yu. This certificate is verified against the trusted ne yu have installed abve. Again, this is dne autmatically withut prmpting yu fr any input. Nw, a secure cnnectin is established and all data transferred between yur applicatin and the First Data API Web Service is SSL-encrypted. 14. Next, yu will be prmpted t supply yur credentials fr authrisatin. As user name yu have t prvide yur stre ID and user ID encded in the frmat WSstreID._.userID. Fr instance, assuming yur stre ID is 101, yur user ID 007, and yur passwrd mypw, yu have t supply WS101._.007 in the user name field and mypw in the passwrd field. Nte that yur credentials are encrypted befre being passed t the server due t the SSL cnnectin established in the steps abve. Then, click OK. 15. The First Data API WSDL file is displayed. In shrt, the WSDL file defines the peratins ffered by the Web Service, their input and return parameters, and hw these peratins can be invked. In case f the First Data API Web Service it defines nly ne peratin (IPGApiOrder) callable by sending a SOAP HTTP request t the fllwing URL: This peratin takes an XML-encded transactin as input and returns an XML-encded respnse. Nte that it is nt necessary t understand hw the WSDL file is cmpsed fr using First Data API. The fllwing chapters will guide yu in setting up yur stre fr building and perfrming custm credit card transactins. Hwever, in case yu are using third-party tls supprting yu in setting up yur stre fr accessing First Data API, yu might have t supply the URL where the WSDL file can be fund. In a similar way as described abve, yu have t tell yur Web Service tl, that the cmmunicatin is SSL-enabled, requiring yu t prvide yur client certificate and accept the server certificate as a trusted ne. Furthermre, yu have t supply yur credentials. Hw all is dne heavily depends n yur Web Service tl. Hence, check the tl s dcumentatin fr details. 4 Sending transactins t the gateway The purpse f this chapter is t give yu a basic understanding f the steps t be taken when cmmitting transactins t the First Data Internet Payment Gateway. It describes what happens if a custmer pays with her credit card in an nline stre using First Data API fr cmmitting transactins. The custmer clicks n the Pay buttn in the nline stre. The nline stre displays a frm asking the custmer t prvide her credit card number and the expiry mnth and year. The custmer types in these three fields and submits the data t the nline stre (i.e. purchases the gds). The nline stre receives the data and builds an XML dcument encding a Sale transactin which includes the data prvided by the custmer and the ttal amunt t be paid by the custmer. firstdata.cm 7

8 After building the XML Sale transactin, the nline stre wraps it in a SOAP message which describes the Web Service peratin t be called with the transactin XML being passed as a parameter. Having built the SOAP message, the nline stre prepares it fr being transferred ver the Internet by packing its cntent int an HTTPS POST request. Furthermre, the stre sets the HTTP headers, especially its credentials (nte that the credentials are the same as the nes yu have t prvide fr viewing the WSDL file). Nw, the stre establishes an SSL cnnectin by prviding the client and server certificate. Then, the nline stre sends the HTTPS request t the First Data API Web Service and waits fr an HTTP respnse. First Data API receives the HTTPS request and parses ut the authrizatin infrmatin prvided by the stre in the HTTP headers. Having authrized the stre t use First Data API, the SOAP message cntained in the HTTP request bdy is parsed ut. This triggers the Web Service peratin handling the transactin prcessing t run. First Data API then perfrms the transactin prcessing, builds an XML respnse dcument, wraps it in a SOAP message, and sends this SOAP message back t the client in the bdy f an HTTPS respnse. Receiving this HTTPS respnse wakes up the stre which reads ut the SOAP message and respnse XML dcument being part f it. Depending n the data cntained in the XML respnse dcument an apprval page is sent back t the custmer in case f a successful transactin, therwise an errr page is returned. The apprval r errr page is displayed. While this example describes the case f a Sale transactin, ther transactins basically fllw the same prcess. Summarising the scenari, yur applicatin has t perfrm the fllwing steps in rder t cmmit credit card transactins and analyze the result: Build an XML dcument encding yur transactins Wrap that XML dcument in a SOAP request message Build an HTTPS POST request with the infrmatin identifying yur stre prvided in the HTTP header and the SOAP request message in the bdy Establish an SSL cnnectin between yur applicatin and First Data API Send the HTTPS POST request t the First Data Internet Payment Gateway and receive the respnse Read the SOAP respnse message ut f the HTTPS respnse bdy Analyse the XML respnse dcument cntained in the SOAP respnse message These seven steps are described in the fllwing chapters. They guide yu thrugh the prcess f setting up yur applicatin fr perfrming custm credit card transactins. firstdata.cm 8

9 5 Building Transactins in XML This chapter describes hw the different transactin types can be built in XML. As the abve example scenari has utlined, a transactin is first encded in an XML dcument which is then wrapped as paylad in a SOAP message. That means the XML-encded transactin represents the parameter passed t the First Data API Web Service peratin. Nte that there exists a variety f Web Service tls supprting yu in the generatin f client stubs which might free yu f the necessity t deal with raw XML. Hwever, a basic understanding f the XML frmat is crucial in rder t build crrect transactins regardless f the available tl supprt. Hence, it is recmmended t becme familiar with the XML frmat used by First Data API fr encding transactins. 5.1 Credit Card transactins Regardless f the transactin type, the basic XML dcument structure f a credit card transactin is as fllws: <ipgapi:ipgapiorderrequest xmlns:v1= xmlns:ipgapi=" <v1:transactin> <v1:creditcardtxtype>...</v1:creditcardtxtype> <v1:creditcarddata>...</v1:creditcarddata> <v1:payment>...</v1:payment> <v1:transactindetails>...</v1:transactindetails> <v1:billing>...</v1:billing> <v1:shipping>...</v1:shipping> </v1:transactin> </ipgapi:ipgapiorderrequest> The element CreditCardDataTXType is mandatry fr all credit card transactins. The ther elements depend n the transactin type. The transactin cntent is type-specific Sale The fllwing XML dcument represents an example f a Sale transactin using the minimum set f elements: <ipgapi:ipgapiorderrequest xmlns:v1= xmlns:ipgapi=" <v1:transactin> <v1:creditcardtxtype> <v1:type>sale</v1:type> </v1:creditcardtxtype> <v1:creditcarddata> <v1:cardnumber> </v1:cardnumber> <v1:expmnth>12</v1:expmnth> <v1:expyear>07</v1:expyear> </v1:creditcarddata> <v1:payment> <v1:chargettal>19.95</v1:chargettal> <v1:currency>978</v1:currency> </v1:payment> </v1:transactin> firstdata.cm 9

10 </ipgapi:ipgapiorderrequest> See chapter XML-Tag verview fr a detailed descriptin f all elements used in the abve example as well as further ptinal elements PreAuth The fllwing XML dcument represents an example f a PreAuth transactin using the minimum set f elements: <ipgapi:ipgapiorderrequest xmlns:v1="://ipg-nline.cm/ipgapi/schemas/v1" xmlns:ipgapi=" <v1:transactin> <v1:creditcardtxtype> <v1:type>preauth</v1:type> </v1:creditcardtxtype> <v1:creditcarddata> <v1:cardnumber> </v1:cardnumber> <v1:expmnth>12</v1:expmnth> <v1:expyear>07</v1:expyear> </v1:creditcarddata> <v1:payment> <v1:chargettal>100.00</v1:chargettal> <v1:currency>978</v1:currency> </v1:payment> </v1:transactin> </ipgapi:ipgapiorderrequest> See chapter XML-Tag verview fr a detailed descriptin f all elements used in the abve example as well as further ptinal elements PstAuth The fllwing XML dcument represents an example f a PstAuth transactin using the minimum set f elements: <ipgapi:ipgapiorderrequest xmlns:v1=" xmlns:ipgapi=" <v1:transactin> <v1:creditcardtxtype> <v1:type>pstauth</v1:type> </v1:creditcardtxtype> <v1:payment> <v1:chargettal>59.45</v1:chargettal> <v1:currency>978</v1:currency> </v1:payment> <v1:transactindetails> <v1:orderid> 703d b c6d e8977 </v1:orderid> </v1:transactindetails> </v1:transactin> </ipgapi:ipgapiorderrequest> See chapter XML-Tag verview fr a detailed descriptin f all elements used in the abve example as well as further ptinal elements. firstdata.cm 10

11 5.1.4 FrceTicket The fllwing XML dcument represents an example f a FrceTicket transactin using the minimum set f elements: <ipgapi:ipgapiorderrequest xmlns:v1=" xmlns:ipgapi=" <v1:transactin> <v1:creditcardtxtype> <v1:type>frceticket</v1:type> </v1:creditcardtxtype> <v1:creditcarddata> <v1:cardnumber> </v1:cardnumber> <v1:expmnth>12</v1:expmnth> <v1:expyear>07</v1:expyear> </v1:creditcarddata> <v1:payment> <v1:chargettal>59.45</v1:chargettal> <v1:currency>978</v1:currency> </v1:payment> <v1:transactindetails> <v1:referencenumber>123456</v1:referencenumber> </v1:transactindetails> </v1:transactin> </ipgapi:ipgapiorderrequest> See chapter XML-Tag verview fr a detailed descriptin f all elements used in the abve example as well as further ptinal elements Return The fllwing XML dcument represents an example f a Return transactin using the minimum set f elements: <ipgapi:ipgapiorderrequest xmlns:v1=" xmlns:ipgapi=" <v1:transactin> <v1:creditcardtxtype> <v1:type>return</v1:type> </v1:creditcardtxtype> <v1:payment> <v1:chargettal>19.95</v1:chargettal> <v1:currency>978</v1:currency> </v1:payment> <v1:transactindetails> <v1:orderid> 62e3b5df e e49302b1807 </v1:orderid> </v1:transactindetails> </v1:transactin> </ipgapi:ipgapiorderrequest> See chapter XML-Tag verview fr a detailed descriptin f all elements used in the abve example as well as further ptinal elements. firstdata.cm 11

12 5.1.6 Credit The fllwing XML dcument represents an example f a Credit transactin using the minimum set f elements: <ipgapi:ipgapiorderrequest xmlns:v1=" xmlns:ipgapi=" <v1:transactin> <v1:creditcardtxtype> <v1:type>credit</v1:type> </v1:creditcardtxtype> <v1:creditcarddata> <v1:cardnumber> </v1:cardnumber> <v1:expmnth>12</v1:expmnth> <v1:expyear>07</v1:expyear> </v1:creditcarddata> <v1:payment> <v1:chargettal>50.00</v1:chargettal> <v1:currency>978</v1:currency> </v1:payment> </v1:transactin> </ipgapi:ipgapiorderrequest> See chapter XML-Tag verview fr a detailed descriptin f all elements used in the abve example as well as further ptinal elements Vid The fllwing XML dcument represents an example f a Vid transactin using the minimum set f elements: <ipgapi:ipgapiorderrequest xmlns:v1=" xmlns:ipgapi=" <v1:transactin> <v1:creditcardtxtype> <v1:type>vid</v1:type> </v1:creditcardtxtype> <v1:transactindetails> <v1:orderid> 62e3b5df e e49302b1807 </v1:orderid> <v1:tdate> </v1:tdate> </v1:transactindetails> </v1:transactin> </ipgapi:ipgapiorderrequest> See chapter XML-Tag verview fr a detailed descriptin f all elements used in the abve example as well as further ptinal elements. 5.2 UK Debit Regardless f the transactin type, the basic XML dcument structure f a UK Debit transactin is as fllws: <ipgapi:ipgapiorderrequest firstdata.cm 12

13 xmlns:v1=" xmlns:ipgapi=" <v1:transactin> <v1:uk_debitcardtxtype>...</v1:uk_debitcardtxtype> <v1:uk_debitcarddata>...</v1:uk_debitcarddata> <v1:payment>...</v1:payment> <v1:transactindetails>...</v1:transactindetails> <v1:billing>...</v1:billing> <v1:shipping>...</v1:shipping> </v1:transactin> </ipgapi:ipgapiorderrequest> The element UK_DebitCardTXType is mandatry fr all debit card transactins. The ther elements depend n the transactin type. The transactin cntent is type-specific Sale The fllwing XML dcument represents an example f a Sale transactin using the minimum set f elements: <ipgapi:ipgapiorderrequest xmlns:v1=" xmlns:ipgapi=" <v1:transactin> <v1:uk_debitcardtxtype> <v1:type>sale</v1:type> </v1:uk_debitcardtxtype> <v1:uk_debitcarddata> <v1:cardnumber> </v1:cardnumber> <v1:expmnth>12</v1:expmnth> <v1:expyear>07</v1:expyear> </v1:uk_debitcarddata> <v1:payment> <v1:chargettal>19.95</v1:chargettal> <v1:currency>978</v1:currency> </v1:payment> </v1:transactin> </ipgapi:ipgapiorderrequest> See chapter XML-Tag verview fr a detailed descriptin f all elements used in the abve example as well as further ptinal elements Return The fllwing XML dcument represents an example f a Return transactin using the minimum set f elements: <ipgapi:ipgapiorderrequest xmlns:v1=" xmlns:ipgapi=" <v1:transactin> <v1:uk_debitcardtxtype> <v1:type>return</v1:type> </v1:uk_debitcardtxtype> <v1:payment> <v1:chargettal>19.95</v1:chargettal> <v1:currency>978</v1:currency> </v1:payment> <v1:transactindetails> firstdata.cm 13

14 <v1:orderid> 62e3b5df e e49302b1807 </v1:orderid> </v1:transactindetails> </v1:transactin> </ipgapi:ipgapiorderrequest> See chapter XML-Tag verview fr a detailed descriptin f all elements used in the abve example as well as further ptinal elements Credit The fllwing XML dcument represents an example f a Credit transactin using the minimum set f elements: <ipgapi:ipgapiorderrequest xmlns:v1=" xmlns:ipgapi=" <v1:transactin> <v1:uk_debitcardtxtype> <v1:type>credit</v1:type> </v1:uk_debitcardtxtype> <v1:uk_debitcarddata> <v1:cardnumber> </v1:cardnumber> <v1:expmnth>12</v1:expmnth> <v1:expyear>07</v1:expyear> </v1:uk_debitcarddata> <v1:payment> <v1:chargettal>50.00</v1:chargettal> <v1:currency>978</v1:currency> </v1:payment> </v1:transactin> </ipgapi:ipgapiorderrequest> See chapter XML-Tag verview fr a detailed descriptin f all elements used in the abve example as well as further ptinal elements Vid The fllwing XML dcument represents an example f a Vid transactin using the minimum set f elements: <ipgapi:ipgapiorderrequest xmlns:v1=" xmlns:ipgapi=" <v1:transactin> <v1:uk_debitcardtxtype> <v1:type>vid</v1:type> </v1:uk_debitcardtxtype> <v1:transactindetails> <v1:orderid> 62e3b5df e e49302b1807 </v1:orderid> <v1:tdate> </v1:tdate> </v1:transactindetails> </v1:transactin> </ipgapi:ipgapiorderrequest> firstdata.cm 14

15 See chapter XML-Tag verview fr a detailed descriptin f all elements used in the abve example as well as further ptinal elements. 5.3 German Direct Debit Regardless f the transactin type, the basic XML dcument structure f a German Direct Debit transactin is as fllws: <ipgapi:ipgapiorderrequest xmlns:v1=" xmlns:ipgapi=" <v1:transactin> <v1:de_directdebittxtype>...</v1:de_directdebittxtype> <v1:de_directdebitdata>...</v1:de_directdebitdata> <v1:payment>...</v1:payment> <v1:transactindetails>...</v1:transactindetails> <v1:billing>...</v1:billing> <v1:shipping>...</v1:shipping> </v1:transactin> </ipgapi:ipgapiorderrequest> The element DE_DirectDebitTXType is mandatry fr all debit transactins. The ther elements depend n the transactin type. The transactin cntent is type-specific Sale The fllwing XML dcument represents an example f a Sale transactin using the minimum set f elements: <ipgapi:ipgapiorderrequest xmlns:v1=" xmlns:ipgapi=" <v1:transactin> <v1:de_directdebittxtype> <v1:type>sale</v1:type> </v1:de_directdebittxtype> <v1:de_directdebitdata> <v1:bankcde> </v1:bankcde> <v1:accuntnumber> </v1:accuntnumber> </v1:de_directdebitdata> <v1:payment> <v1:chargettal>19.00</v1:chargettal> <v1:currency>978</v1:currency> </v1:payment> </v1:transactin> </ipgapi:ipgapiorderrequest> See chapter XML-Tag verview fr a detailed descriptin f all elements used in the abve example as well as further ptinal elements Vid The fllwing XML dcument represents an example f a Vid transactin using the minimum set f elements: <ipgapi:ipgapiorderrequest firstdata.cm 15

16 xmlns:v1=" xmlns:ipgapi=" <v1:transactin> <v1:de_directdebittxtype> <v1:type>vid</v1:type> </v1:de_directdebittxtype> <v1:transactindetails> <v1:orderid> 62e3b5df e e49302b1807 </v1:orderid> <v1:tdate> </v1:tdate> </v1:transactindetails> </v1:transactin> </ipgapi:ipgapiorderrequest> See chapter XML-Tag verview fr a detailed descriptin f all elements used in the abve example as well as further ptinal elements. 6 Additinal Web Service actins 6.1 Initiate Clearing Clearing fr German Direct Debit transactins can be initiated via the Web Service similar t a payment transactin: <ipgapi:ipgapiactinrequest xmlns:a1=" xmlns:ipgapi=" <a1:actin> </a1:initiateclearing> </a1:actin> </ipgapi:ipgapiactinrequest> 6.2 Inquiry Order The actin InquiryOrder allws yu t get details abut previusly prcessed transactins f a specific rder. Yu therefre need t submit the crrespnding Order ID: <ns4:ipgapiactinrequest xmlns:ns4=" xmlns:ns2=" xmlns:ns3=" <ns2:actin> <ns2:inquiryorder> <ns2:orderid> b5b7fb da8bd </ns2:orderid> </ns2:inquiryorder> </ns2:actin> </ns4:ipgapiactinrequest> The result cntains infrmatin abut all transactins belnging t the crrespnding Order ID: <ns4:ipgapiactinrespnse firstdata.cm 16

17 firstdata.cm 17 xmlns:ns4=" xmlns:ns2=" xmlns:ns3=" <ns4:successfully>true</ns4:successfully> <ns2:errr /> <ns2:transactinvalues> <ns3:creditcardtxtype> <ns3:type>sale</ns3:type> </ns3:creditcardtxtype> <ns3:creditcarddata> <ns3:cardnumber> </ns3:cardnumber> <ns3:expmnth>12</ns3:expmnth> <ns3:expyear>2008</ns3:expyear> </ns3:creditcarddata> <ns3:payment> <ns3:chargettal>1</ns3:chargettal> <ns3:currency>978</ns3:currency> </ns3:payment> <ns3:transactindetails> <ns3:orderid> b5b7fb da8bd </ns3:orderid> <ns3:tdate> :52:45.0</ns3:TDate> <ns3:transactinorigin>eci</ns3:transactinorigin> </ns3:transactindetails> <ns4:ipgapiorderrespnse> <ns4:orderid> b5b7fb da8bd </ns4:orderid> <ns4:apprvalcde></ns4:apprvalcde> <ns4:tdate> :52:45.0</ns4:TDate> <ns4:terminalid> </ns4:terminalid> </ns4:ipgapiorderrespnse> <ns2:receiptnumber>1865</ns2:receiptnumber> <ns2:respnsecde> Y:: :PPXM: </ns2:respnsecde> <ns2:tracenumber>001884</ns2:tracenumber> <ns2:transactinstate>vided</ns2:transactinstate> </ns2:transactinvalues> <ns2:transactinvalues> <ns3:creditcardtxtype> <ns3:type>credit</ns3:type> </ns3:creditcardtxtype> <ns3:creditcarddata> <ns3:cardnumber> </ns3:cardnumber> <ns3:expmnth>12</ns3:expmnth> <ns3:expyear>2008</ns3:expyear> </ns3:creditcarddata> <ns3:payment> <ns3:chargettal>1</ns3:chargettal> <ns3:currency>978</ns3:currency> </ns3:payment> <ns3:transactindetails> <ns3:orderid> b5b7fb da8bd </ns3:orderid> <ns3:tdate> :52:49.0</ns3:TDate> <ns3:transactinorigin>eci</ns3:transactinorigin> </ns3:transactindetails> <ns4:ipgapiorderrespnse>

18 <ns4:orderid> b5b7fb da8bd </ns4:orderid> <ns4:apprvalcde></ns4:apprvalcde> <ns4:tdate> :52:49.0</ns4:TDate> <ns4:terminalid> </ns4:terminalid> </ns4:ipgapiorderrespnse> <ns2:receiptnumber>1866</ns2:receiptnumber> <ns2:respnsecde> Y:: :PPXM: </ns2:respnsecde> <ns2:tracenumber>001885</ns2:tracenumber> <ns2:transactinstate>captured</ns2:transactinstate> </ns2:transactinvalues> <ns2:transactinvalues> <ns3:creditcardtxtype> <ns3:type>vid</ns3:type> </ns3:creditcardtxtype> <ns3:creditcarddata> <ns3:cardnumber> </ns3:cardnumber> <ns3:expmnth>12</ns3:expmnth> <ns3:expyear>2008</ns3:expyear> </ns3:creditcarddata> <ns3:payment> <ns3:chargettal>1</ns3:chargettal> <ns3:currency>978</ns3:currency> </ns3:payment> <ns3:transactindetails> <ns3:orderid> b5b7fb da8bd </ns3:orderid> <ns3:tdate> :52:52.0</ns3:TDate> <ns3:transactinorigin>eci</ns3:transactinorigin> </ns3:transactindetails> <ns4:ipgapiorderrespnse> <ns4:orderid> b5b7fb da8bd </ns4:orderid> <ns4:apprvalcde></ns4:apprvalcde> <ns4:tdate> :52:52.0</ns4:TDate> <ns4:terminalid> </ns4:terminalid> </ns4:ipgapiorderrespnse> <ns2:receiptnumber>1867</ns2:receiptnumber> <ns2:respnsecde> Y:: :PPX : </ns2:respnsecde> <ns2:tracenumber>001886</ns2:tracenumber> </ns2:transactinvalues> </ns4:ipgapiactinrespnse> 6.3 Recurring Payments The actin RecurringPayment allws yu t install, mdify r cancel peridic credit card payments. Als, it allws yu t schedule a single payment in the future. The fllwing example shws hw t install a peridic payment with nly ne executin (InstallmentCunt) n 31 December 2011: <ns4:ipgapiactinrequest firstdata.cm 18

19 xmlns:ns4=" xmlns:ns2=" xmlns:ns3=" <ns2:actin> <ns2:recurringpayment> <ns2:functin>install</ns2:functin> <ns2:recurringpaymentinfrmatin> <ns2:recurringstartdate> </ns2:recurringstartdate> <ns2:installmentcunt>1</ns2:installmentcunt> <ns2:installmentfrequency> 1 </ns2:installmentfrequency> <ns2:installmentperid> mnth </ns2:installmentperid> </ns2:recurringpaymentinfrmatin> <ns2:creditcarddata> <ns3:cardnumber> </ns3:cardnumber> <ns3:expmnth>12</ns3:expmnth> <ns3:expyear>12</ns3:expyear> <ns3:cardcdevalue>977</ns3:cardcdevalue> </ns2:creditcarddata> <ns3:payment> <ns3:chargettal>1</ns3:chargettal> <ns3:currency>978</ns3:currency> </ns3:payment> </ns2:recurringpayment> </ns2:actin> </ns4:ipgapiactinrequest> If yu set the RecurringStartDate t the actual date, the first payment will immediately be initiated. A start date in the past is nt allwed. Mdificatins f an existing Recurring Payment can be initiated using the Order ID: <ns4:ipgapiactinrequest xmlns:ns4=" xmlns:ns2=" xmlns:ns3=" <ns2:actin> <ns2:recurringpayment> <ns2:functin>mdify</ns2:functin> <ns2:orderid> e368a f-4f56-9ae2-beb4023a6993 </ns2:orderid> <ns2:recurringpaymentinfrmatin> <ns2:installmentcunt>999</ns2:installmentcunt> </ns2:recurringpaymentinfrmatin> </ns2:recurringpayment> </ns2:actin> </ns4:ipgapiactinrequest> Yu nly need t include the elements that need t be changed. If yu change the credit card number, it is als required t include the expiry date. If yu want t change the amunt, yu als need t include the currency. T delete a Recurring Payment, yu als use the Order ID: firstdata.cm 19

20 <ns4:ipgapiactinrequest xmlns:ns4=" xmlns:ns2=" xmlns:ns3=" <ns2:actin> <ns2:recurringpayment> <ns2:functin>cancel</ns2:functin> <ns2:orderid> e368a f-4f56-9ae2-beb4023a6993 </ns2:orderid> </ns2:recurringpayment> </ns2:actin> </ns4:ipgapiactinrequest> The respnse fr a successful instalment, mdificatin r cancellatin cntains the value true fr the parameter <ns4:successfully>: <ns4:ipgapiactinrespnse xmlns:ns4=" xmlns:ns2=" xmlns:ns3=" <ns4:successfully>true</ns4:successfully> <ns4:orderid>e368a f-4f56-9ae2-beb4023a6993</ns4:orderid> </ns4:ipgapiactinrespnse> 7 Data Vault With the Data Vault prduct yu can stre sensitive cardhlder data in an encrypted database in First Data s data centre t use it fr subsequent transactins withut the need t stre this data within yur wn systems. If yu have rdered this prduct, the API slutin ffers yu the fllwing functins: Stre r update payment infrmatin when perfrming a transactin Additinally send the parameter HstedDataID tgether with the transactin data as a unique identificatin fr the payment infrmatin in this transactin. Depending n the payment type, credit card number and expiry date r accunt number and bank cde will be stred under this ID. In cases where the submitted HstedDataID already exists fr yur stre, the stred payment infrmatin will be updated. <ipgapi:ipgapiorderrequest xmlns:v1=" xmlns:ipgapi=" <v1:transactin> <v1:creditcardtxtype> <v1:type>sale</v1:type> </v1:creditcardtxtype> <v1:creditcarddata> <v1:cardnumber> </v1:cardnumber> <v1:expmnth>12</v1:expmnth> <v1:expyear>07</v1:expyear> </v1:creditcarddata> <v1:payment> <v1:hsteddataid>hdid custmer </v1:HstedDataID> <v1:chargettal>19.00</v1:chargettal> firstdata.cm 20

21 <v1:currency>978</v1:currency> </v1:payment> </v1:transactin> </ipgapi:ipgapiorderrequest> The recrd is nly being stred if the authrisatin f the payment transactin is successful and yur Stre has been setup fr this service. Initiate payment transactins using stred data If yu stred cardhlder infrmatin using the Data Vault prduct, yu can perfrm transactins using the HstedDataID withut the need t pass the credit card r bank accunt data again. Please nte that it is nt allwed t stre the card cde (in mst cases n the back f the card) s that fr credit card transactins, the cardhlder still needs t enter this value. Fr the checkut prcess in yur web shp, we recmmend that yu als stre the last fur digits f the credit card number n yur side and display it when it cmes t payment. In that way the cardhlder can see which f his maybe several cards has been registered in yur shp and will be used fr this payment transactin. <ipgapi:ipgapiorderrequest xmlns:v1=" xmlns:ipgapi=" <v1:transactin> <v1:creditcardtxtype> <v1:type>sale</v1:type> </v1:creditcardtxtype> <v1:payment> <v1:hsteddataid>hdid custmer </v1:HstedDataID> <v1:chargettal>19.00</v1:chargettal> <v1:currency>978</v1:currency> </v1:payment> </v1:transactin> </ipgapi:ipgapiorderrequest> Stre payment infrmatin withut perfrming a transactin at the same time Besides the pssibility t stre new recrds when perfrming a payment transactin, yu can stre payment infrmatin using an Actin Request. In that way it is als pssible t uplad multiple recrds at nce. The fllwing example shws the uplad fr a recrd with credit card data as well as ne with accunt number and bank cde. Please nte that als in this case, existing recrds will be updated if the HstedDataID is the same. <ns4:ipgapiactinrequest xmlns:ns4=" xmlns:ns2=" xmlns:ns3=" <ns2:actin> <ns2:strehsteddata> <ns2:datastrageitem> <ns2:creditcarddata> <ns3:cardnumber> </ns3:cardnumber> <ns3:expmnth>12</ns3:expmnth> <ns3:expyear>08</ns3:expyear> </ns2:creditcarddata> firstdata.cm 21

22 <ns2:hsteddataid> d763bba7-1cfa-4d3d-94af-9fbe29ec0e26 </ns2:hsteddataid> </ns2:datastrageitem> <ns2:datastrageitem> <ns2:de_directdebitdata> <ns3:bankcde> </ns3:bankcde> <ns3:accuntnumber> </ns3:accuntnumber> </ns2:de_directdebitdata> <ns2:hsteddataid> 691c7cb3-a752-4d6d-abde-83cad63de258 </ns2:hsteddataid> </ns2:datastrageitem> </ns2:strehsteddata> </ns2:actin> </ns4:ipgapiactinrequest> The result fr a successful strage cntains the value true fr the parameter <ns4:successfully>: <ns4:ipgapiactinrespnse xmlns:ns4=" xmlns:ns2=" xmlns:ns3=" <ns4:successfully>true</ns4:successfully> </ns4:ipgapiactinrespnse> In cases where ne r mre recrds have nt been stred successfully, the crrespnding Hsted Data IDs are marked in the result: <ns4:ipgapiactinrespnse xmlns:ns4=" xmlns:ns2=" xmlns:ns3=" <ns4:successfully>false</ns4:successfully> <ns2:errr Cde="SGSDAS "> <ns2:errrmessage> Culd nt stre the hsted data id: 691c7cb3-a752-4d6d-abde-83cad63de258. Reasn: An internal errr has ccured while prcessing yur request </ns2:errrmessage> </ns2:errr> </ns4:ipgapiactinrespnse> See further pssibilities with the Data Vault prduct in the Integratin Guide fr First Data Cnnect. firstdata.cm 22

23 8 XML-Tag verview 8.1 Overview by transactin type The fllwing shws which XML-tags need t be submitted fr each transactin type as well as which nes can ptinally be used. Please nly use the fields stated belw and als nte the rder. Abbreviatins: m: mandatry : ptinal d: ptinal with default value a und b: maximum ne f the tw values 1: if a is prvided ptinal, mandatry if a and b have nt been prvided 3: mandatry fr 3D Secure transactins s: see details in 3D Secure chapter Path/Name Credit Card Direct Debit all paths relative t ipgapi:ipgapiorderrequest/ v1:transactin Sale FrceTicket PreAuth PstAuth Return Credit Vid Sale Vid v1:creditcardtxtype/ v1:type v1:creditcarddata/ v1:cardnumber v1:creditcarddata/ v1:expmnth v1:creditcarddata/ v1:expyear v1:creditcarddata/ v1:cardcdevalue v1:creditcarddata/ v1:trackdata v1:creditcard3dsecure/ v1:verificatinrespnse v1:creditcard3dsecure/ v1:payerauthenticatinrespnse v1:creditcard3dsecure/ v1:authenticatinvalue v1:creditcard3dsecure/ v1:xid v1:de_directdebittxtype/ v1:type v1:de_directdebitdata/ v1:bankcde v1:de_directdebitdata/ v1:accuntnumber m m m m m m m a a a a a a a a a a a a b b b b s s s s s s s s s s s s m a a m firstdata.cm 23

24 v1:de_directdebitdata/ v1:trackdata v1:payment/ v1:hsteddataid v1:payment/ v1:chargettal v1:payment/ v1:currency v1:transactindetails/ v1:orderid v1:transactindetails/ v1:ip v1:transactindetails/ v1:referencenumber v1:transactindetails/ v1:tdate v1:transactindetails/ v1:transactinorigin v1:transactindetails/ v1:invicenumber v1:billing/ v1:custmerid v1:billing/ v1:name v1:billing/ v1:cmpany v1:billing/ v1:address1 v1:billing/ v1:address2 v1:billing/ v1:city v1:billing/ v1:state v1:billing/ v1:zip v1:billing/ v1:cuntry v1:billing/ v1:phne v1:billing/ v1:fax v1:billing/ v1: v1:shipping/ v1:type v1:shipping/ v1: Name v1:shipping/ v1: Address1 v1:shipping/ v1: Address2 b m m m m m m m m m m m m m m m m m m m m m d d d firstdata.cm 24

25 v1:shipping/ v1: City v1:shipping/ v1: State v1:shipping/ v1: Zip v1:shipping/ v1: Cuntry 8.2 Descriptin f the XML-Tags CreditCardTxType Path/Name v1:creditcardtxtype/ v1:type XML Descriptin Schema type xs:string Stres the transactin type. Pssible values are sale, frceticket, preauth, pstauth, return, credit and vid CreditCardData Path/Name v1:creditcarddata/ v1:cardnumber v1:creditcarddata/ v1:expmnth v1:creditcarddata/ v1:expyear v1:creditcarddata/ v1:cardcdevalue v1:creditcarddata/ v1:trackdata XML Descriptin Schema type xs:string Stres the custmer s credit card number. Make sure that the string cntains nly digits, i.e. passing the number e.g. in the frmat xxxx-xxxx-xxxx-xxxx will result in an errr returned by the First Data API Web Service. xs:string Stres the expiratin mnth f the custmer s credit card. Make sure that the cntent f this element always cntains tw digits, i.e. a card expiring in July will have this element with value 07. xs:string Stres the expiratin year f the custmer s credit card. The same frmatting restrictins as fr the v1:expmnth element apply here. xs:string Stres the three r fur digit card security cde (CSC) smetimes als referred t as card verificatin value (CVV) r cde (CVC) which is typically printed n the back f the credit card. Fr infrmatin abut the benefits f CSC cntact supprt. xs:string Stres the track data f a card when using a card reader instead f keying in card data (can ptinally be used instead f transmitting CardNumber, ExpMnth and ExpYear). This field needs t cntain at firstdata.cm 25

26 least the cncatenated track 1 and 2 data. Track data 3 is ptinal. The track data must include the track and field separatrs as they are stred n the card. Example fr the track data separatr frm track data 1 and 2 withut the data: %?;? CreditCard3DSecure Path/Name v1:creditcard3dsecure/ v1:verificatinrespnse v1:creditcard3dsecure/ v1:payerauthenticatinresp nse v1:creditcard3dsecure/ v1:authenticatinvalue v1:creditcard3dsecure/ v1:xid XML Schema Descriptin type xs:string Stres the VerificatinRespnse (VERes) f yur Merchant Plug-in. xs:string Stres the PayerAuthenticatinRespnse (PARes) f yur Merchant Plug-in. xs:string Stres the AuthenticatinValue (MasterCard: AAV r VISA: CAAV) f yur Merchant Plug-in. xs:string Stres the XID f yur Merchant Plug-in. Please nte that these are values yu receive frm yur wn Merchant Plug-in fr 3D Secure r a slutin f a 3D Secure prvider. The integrated 3D Secure functinality f the Cnnect feature can nt be used fr transactins via the API fr technical reasns DE_DirectDebitTxType Path/Name v1:de_directdebittxtype/ v1:type XML Schema type xs:string Descriptin Stres the transactin type. Pssible values are sale r vid DE_DirectDebitData Path/Name v1:de_directdebitdata/ v1:bankcde v1:de_directdebitdata/ v1:accuntnumber v1:de_directdebitdata/ v1:trackdata XML Schema Descriptin type xs:string Stres the bank cde f the custmer. Please make sure that the value nly cntains numbers and n spaces. xs:string Stres the accunt number f the custmer. Please make sure that the value nly cntains numbers and n spaces. xs:string Stres the track data f a card when using a card reader instead f keying in card data (can ptinally be used instead f transmitting BankCde and AccuntNumber). The field needs t cntain the cncatenated track 2 and 3 data. The track data must include the track and field separatrs as they are stred n the card. firstdata.cm 26

27 8.2.6 Payment Path/Name v1:payment/ v1:hsteddataid v1:payment/ v1:chargettal v1:payment/ v1:currency TransactinDetails Path/Name v1:transactindetails/ v1:orderid v1:transactindetails/ v1:ip v1:transactindetails/ v1:referencenumber v1:transactindetails/ v1:tdate v1:transactindetails/ v1:transactinorigin v1:transactindetails/ v1:invicenumber Billing Path/Name XML Schema Descriptin type xs:string Stres the Hsted Data ID fr the Data Vault prduct xs:duble Stres the transactin amunt. Make sure that the number f psitins after the decimal pint des nt exceed 2, e.g wuld be invalid hwever, 3.12, 3.1, and 3 are crrect. xs:string Stres the currency as a three-digit ISO 4217 value (e. g. 978 fr Eur) XML Schema Descriptin type xs:string Stres the rder ID. This must be unique per Stre ID. If n Order ID is transmitted, the Internet Payment Gateway will generate ne autmatically. xs:string Stres the custmer s IP address which can be used by the First Data API Web Service fr fraud detectin by IP address. Make sure that yu supply the IP in the frmat xxx.xxx.xxx.xxx, e.g wuld be a valid IP. xs:string Stres the six digit reference number yu have received as the result f a successful external authrizatin (e.g. by phne). The First Data API Web Service needs this number fr uniquely mapping a FrceTicket transactin t a previusly perfrmed external authrizatin. xs:string Stres the TDate f the Sale, PstAuth, FrceTicket, Return, r Credit transactin this Vid transactin refers t. A TDate value is returned within the respnse t a successful transactin f ne f these five types. When perfrming a Vid transactin, yu have t pass the TDate in additin t the rder ID fr uniquely identifying the transactin t be vided. The scenari presented belw gives an example. xs:string The surce f the transactin. The pssible values are ECI (if the rder was received via r Internet), MOTO (mail rder / telephne rder) and RETAIL (face t face). xs:string Stres the invice number. XML Schema Descriptin firstdata.cm 27

28 v1:billing/ v1:custmerid v1:billing/ v1:name v1:billing/ v1:cmpany v1:billing/ v1:address1 v1:billing/ v1:address2 v1:billing/ v1:city v1:billing/ v1:state v1:billing/ v1:zip v1:billing/ v1:cuntry v1:billing/ v1:phne v1:billing/ v1:fax v1:billing/ v1: type xs:string Stres yur ID fr yur custmer. xs:string Stres the custmer s name. If prvided, it will appear n yur transactin reprts. xs:string Stres the custmer s cmpany. If prvided, it will appear n yur transactin reprts. xs:string Stres the first line f the custmer s address. If prvided, it will appear n yur transactin reprts. xs:string Stres the secnd line f the custmer s address. If prvided, it will appear n yur transactin reprts. xs:string Stres the custmer s city. If prvided, it will appear n yur transactin reprts. xs:string Stres the custmer s state. If prvided, it will appear n yur transactin reprts. xs:string Stres the custmer s zip cde. If prvided, it will appear n yur transactin reprts. xs:string Stres the custmer s cuntry. If prvided, it will appear n yur transactin reprts. xs:string Stres the custmer s phne number. If prvided, it will appear n yur transactin reprts. xs:string Stres the custmer s fax number. If prvided, it will appear n yur transactin reprts. xs:string Stres the custmer s address. If prvided, it will appear n yur transactin reprts Shipping Path/Name v1:shipping/ v1:type v1:shipping/ v1:name v1:shipping/ v1:address1 v1:shipping/ v1:address2 v1:shipping/ v1:city v1:shipping/ v1:state v1:shipping/ v1:zip v1:shipping/ v1:cuntry XML Schema Descriptin type xs:string Stres the way f delivery. xs:string Stres the name f the recipient. If prvided, it will appear n yur transactin reprts. xs:string Stres the first line f the shipping address. If prvided, it will appear n yur transactin reprts. xs:string Stres the secnd line f the shipping address. If prvided, it will appear n yur transactin reprts. xs:string Stres the recipient s city. If prvided, it will appear n yur transactin reprts. xs:string Stres the recipient s state. If prvided, it will appear n yur transactin reprts. xs:string Stres the recipient s zip cde. If prvided, it will appear n yur transactin reprts. xs:string Stres the recipient s cuntry. If prvided, it firstdata.cm 28

29 will appear n yur transactin reprts. 9 Building a SOAP Request Message After building yur transactin in XML, a SOAP request message describing the Web Service peratin call, yu wish t perfrm, has t be created. That means while the XML-encded transactin yu have established as described in the previus chapter represents the peratin argument, the SOAP request message encdes the actual peratin call. Building such a SOAP request message is a rather straightfrward task. The cmplete SOAP message wrapping the XML-Sale-transactin lks as fllws: <?xml versin="1.0" encding="utf-8"?> <SOAP-ENV:Envelpe xmlns:soap-env=" <SOAP-ENV:Header /> <SOAP-ENV:Bdy> <ipgapi:ipgapiorderrequest xmlns:v1=" xmlns:ipgapi=" <v1:transactin> <v1:creditcardtxtype> <v1:type>sale</v1:type> </v1:creditcardtxtype> <v1:creditcarddata> <v1:cardnumber> </v1:cardnumber> <v1:expmnth>12</v1:expmnth> <v1:expyear>07</v1:expyear> </v1:creditcarddata> <v1:payment> <v1:chargettal>19.00</v1:chargettal> <v1:currency>978</v1:currency> </v1:payment> </v1:transactin> </ipgapi:ipgapiorderrequest> </SOAP-ENV:Bdy> </SOAP-ENV:Envelpe> In shrt, the SOAP request message cntains a SOAP envelpe cnsisting f a header and a bdy. While n specific header entries are required fr calling the Web Service, the SOAP bdy takes the transactin XML dcument as sub element as shwn abve. Nte that there are n further requirements fr transactins f a type ther than Sale. That means the general frmat f the SOAP request message regardless f the actual transactin type is as fllws: <?xml versin="1.0" encding="utf-8"?> <SOAP-ENV:Envelpe xmlns:soap-env=" <SOAP-ENV:Header /> <SOAP-ENV:Bdy> <ipgapi:ipgapiorderrequest xmlns:ipgapi=" xmlns:v1=" firstdata.cm 29

30 <v1:transactin> <!-- transactin cntent --> </v1:transactin> </ipgapi:ipgapiorderrequest> </SOAP-ENV:Bdy> </SOAP-ENV:Envelpe> Finally, yu may have nticed that there are n specific entries describing which Web Service peratin t call. In fact, First Data API autmatically maps the ipgapi:ipgapiorderrequest element t the crrespnding Web Service peratin. 10 Reading the SOAP Respnse Message The SOAP respnse message may be understd as the Web Service peratin result. Hence, prcessing the SOAP request message may have either resulted in a SOAP respnse message in the success case (i.e. the return parameter) r a SOAP fault message in case f a failure (i.e. the thrwn exceptin). Bth SOAP message types are cntained in the bdy f the HTTP respnse message SOAP Respnse Message A SOAP respnse message is received as the result t the credit card prcessr (started by the First Data Internet Payment Gateway) having apprved yur transactin. It always has the fllwing scheme: <?xml versin="1.0" encding="utf-8"?> <SOAP-ENV:Envelpe xmlns:soap-env=" <SOAP-ENV:Header /> <SOAP-ENV:Bdy> <ipgapi:ipgapiorderrespnse xmlns:ipgapi=" <!-- transactin result --> </ipgapi:ipgapiorderrespnse> </SOAP-ENV:Bdy> </SOAP-ENV:Envelpe> If yu have send an Actin, yu get an ipgapi:ipgapiactinrespnse. Again, n headers are defined. The SOAP bdy cntains the actual transactin result cntained in the ipgapi:ipgapiorderrespnse r ipgapi:ipgapiorderrequest element. Its sub elements and their meanings are presented in the next chapter. Hwever, in rder t prvide a quick example, an apprved Sale transactin is wrapped in a SOAP message similar t the fllwing example: <?xml versin="1.0" encding="utf-8"?> <SOAP-ENV:Envelpe xmlns:soap-env=" <SOAP-ENV:Header /> <SOAP-ENV:Bdy> <ipgapi:ipgapiorderrespnse xmlns:ipgapi=" <ipgapi:cmmercialserviceprvider> BNLP </ipgapi:cmmercialserviceprvider> firstdata.cm 30

31 <ipgapi:transactintime> </ipgapi:transactintime> <ipgapi:prcessrreferencenumber> 3105 </ipgapi:prcessrreferencenumber> <ipgapi:prcessrrespnsemessage> Functin perfrmed errr-free </ipgapi:prcessrrespnsemessage> <ipgapi:errrmessage /> <ipgapi:orderid> 62e3b5df e e49302b1807 </ipgapi:orderid> <ipgapi:apprvalcde> Y:440368: :PPXM: </ipgapi:apprvalcde> <ipgapi:avsrespnse>ppx</ipgapi:avsrespnse> <ipgapi:tdate> </ipgapi:tdate> <ipgapi:transactinresult> APPROVED </ipgapi:transactinresult> <ipgapi:terminalid>123456</ipgapi:terminalid> <ipgapi:prcessrrespnsecde> 00 </ipgapi:prcessrrespnsecde> <ipgapi:prcessrapprvalcde> </ipgapi:prcessrapprvalcde> <ipgapi:prcessrreceiptnumber> 4291 </ipgapi:prcessrreceiptnumber> <ipgapi:prcessrtracenumber> </ipgapi:prcessrtracenumber> </ipgapi:ipgapiorderrespnse> </SOAP-ENV:Bdy> </SOAP-ENV:Envelpe> 10.2 SOAP Fault Message In general, a SOAP fault message returned by the First Data API Web Service has the fllwing frmat: <?xml versin="1.0" encding="utf-8"?> <SOAP-ENV:Envelpe xmlns:soap-env=" <SOAP-ENV:Header /> <SOAP-ENV:Bdy> <SOAP-ENV:Fault> <faultcde>soap-env:client</faultcde> <faultstring xml:lang="en-us"> <!-- fault message --> </faultstring> <detail> <!-- fault message --> </detail> </SOAP-ENV:Fault> </SOAP-ENV:Bdy> </SOAP-ENV:Envelpe> firstdata.cm 31

32 Basically, the faultstring element carries the fault type. Accrding t the fault type, the ther elements are set. Nte that nt all f the abve shwn elements have t ccur within the SOAP-ENV:Fault element. Which elements exist fr which fault type is described in the upcming sectins SOAP-ENV:Server In general, this fault type indicates that the Web Service has failed t prcess yur transactin due t an internal system errr. If yu receive this as respnse, please cntact ur supprt team t reslve the prblem. An InternalExceptin always lks like the example belw: <?xml versin="1.0" encding="utf-8"?> <SOAP-ENV:Envelpe xmlns:soap-env=" <SOAP-ENV:Header /> <SOAP-ENV:Bdy> <SOAP-ENV:Fault> <faultcde>soap-env:server</faultcde> <faultstring xml:lang="en-us"> unexpected errr </faultstring> </SOAP-ENV:Fault> </SOAP-ENV:Bdy> </SOAP-ENV:Envelpe> The SOAP fault message elements relative t the SOAP-ENV:Envelpe/SOAP- ENV:Bdy/SOAP-ENV:Fault element are set as fllws: Path/Name XML Schema type Descriptin faultcde xs:string This element is always set t SOAP-ENV:Server, indicating that the fault cause is due t the system underlying the API having failed. faultstring xs:string This element always carries the fllwing fault string: unexpected errr SOAP-ENV:Client MerchantExceptin This fault type ccurs if First Data API can trace back the errr t yur stre having passed incrrect infrmatin. This may have ne f the fllwing reasns: 1. Yur stre is registered as being clsed. In case yu will receive this infrmatin despite yur stre being registered as pen, please cntact supprt. 2. The stre ID / user ID cmbinatin yu have prvided fr HTTPS authrizatin is syntactically incrrect. 3. The XML des nt match the schema. A MerchantExceptin always lks as shwn belw: firstdata.cm 32

33 <?xml versin="1.0" encding="utf-8"?> <SOAP-ENV:Envelpe xmlns:soap-env=" <SOAP-ENV:Header /> <SOAP-ENV:Bdy> <SOAP-ENV:Fault> <faultcde>soap-env:client</faultcde> <faultstring xml:lang="en-us"> MerchantExceptin </faultstring> <detail> <!-- detailed explanatin. --> </detail> </SOAP-ENV:Fault> </SOAP-ENV:Bdy> </SOAP-ENV:Envelpe> The SOAP fault message elements relative t the SOAP-ENV:Envelpe/SOAP- ENV:Bdy/SOAP-ENV:Fault element are set as fllws: Path/Name XML Schema type Descriptin faultcde xs:string This element is always set t SOAP-ENV:Client faultstring detail/reasn xs:string xs:string This element is always set t MerchantExceptin Minimum ne reasn See sectin Merchant Exceptins in the Appendix fr detailed analysis f errrs PrcessingExceptin A fault f this type is raised whenever First Data API has detected an errr while prcessing yur transactin. The difference t the ther fault types is that the transactin passed the check against the xsd. A PrcessingExceptin always lks as shwn belw: <SOAP-ENV:Envelpe xmlns:soap-env=" <SOAP-ENV:Header /> <SOAP-ENV:Bdy> <SOAP-ENV:Fault> <faultcde>soap-env:client</faultcde> <faultstring xml:lang="en-us"> PrcessingExceptin: Prcessing the request resulted in an errr - see SOAP details fr mre infrmatin </faultstring> <detail> <ipgapi:ipgapiorderrespnse xmlns:ipgapi=" <ipgapi:cmmercialserviceprvider> BNLP </ipgapi:cmmercialserviceprvider> <ipgapi:transactintime> </ipgapi:transactintime> firstdata.cm 33

34 <ipgapi:prcessrreferencenumber /> <ipgapi:prcessrrespnsemessage> Card expiry date exceeded </ipgapi:prcessrrespnsemessage> <ipgapi:errrmessage> SGS : Card expiry date exceeded </ipgapi:errrmessage> <ipgapi:orderid> 62e3b5df e e49302b1807 </ipgapi:orderid> <ipgapi:apprvalcde /> <ipgapi:avsrespnse /> <ipgapi:tdate> </ipgapi:tdate> <ipgapi:transactinresult> DECLINED </ipgapi:transactinresult> <ipgapi:terminalid>123456</ipgapi:terminalid> <ipgapi:prcessrrespnsecde/> <ipgapi:prcessrapprvalcde /> <ipgapi:prcessrreceiptnumber /> <ipgapi:prcessrtracenumber /> </ipgapi:ipgapiorderrespnse> </detail> </SOAP-ENV:Fault> </SOAP-ENV:Bdy> </SOAP-ENV:Envelpe> The SOAP fault message elements relative t the SOAP-ENV:Envelpe/SOAP- ENV:Bdy/SOAP-ENV:Fault element are set as described belw. Path/Name XML Schema type Descriptin faultcde xs:string This element is always set t SOAP-ENV:Client, indicating that the fault cause is likely t be fund in invalid transactin data having been passed. faultstring xs:string This element always carries the fllwing fault string: PrcessingExceptin detail/ ipgapi:ipgapiorderrespnse Cmpsite element This element cntains the errr. Since there are numerus causes fr raising such an exceptin, the next chapter will give an verview by explaining the data cntained in this element. See sectin Prcessing Exceptins in the Appendix fr detailed analysis f errrs. 11 Analysing the Transactin Result 11.1 Transactin Apprval The SOAP message wrapping a transactin apprval has been presented in the previus chapter tgether with an example. The transactin status reprt generated by the Internet firstdata.cm 34

35 Payment Gateway is cntained in the ipgapi:ipgapiorderrespnse element and can be understd as the data returned by the Web Service peratin. In the fllwing, its elements relative t the ipgapi:ipgapiorderrespnse super element are described. Nte that always the full set f elements is cntained in the respnse hwever, sme elements might be empty. Path/Name XML Schema type Descriptin ipgapi: xs:string CmmercialServicePrvider Indicates yur prvider. ipgapi:transactintime xs:string The time stamp which is set by the Internet Payment Gateway befre returning the transactin apprval. ipgapi: xs:string In sme cases, this element might be PrcessrReferenceNumber empty. It stres a number allwing the credit card prcessr t refer t this transactin. Yu d nt need t prvide this number in any further transactin. Hwever, have that number ready, in case yu detect any prblems with yur transactin and ipgapi: PrcessrRespnseMessage ipgapi: PrcessrRespnseCde xs:string xs:string yu want t cntact supprt. In case f an apprval, this element cntains the string: Functin perfrmed errr-free The respnse cde frm the credit card prcessr ipgapi:errrmessage xs:string This element is empty in case f an apprval. ipgapi:orderid xs:string This element cntains the rder ID. Fr Sale, PreAuth, FrceTicket, and Credit transactins, a new rder ID is returned. Fr PstAuth, Return, and Vid transactins, supply this number in the v1:orderid element fr making clear t which transactin yu refer. The ipgapi:orderid element f a transactin apprval t a PstAuth, Return, r Vid transactin simply returns the rder ID, such a transactin has referred t. ipgapi:apprvalcde xs:string Stres the apprval cde the transactin prcessr has created fr this transactin. Yu d nt need t prvide this cde in any further transactin. Hwever, have that number ready, in case yu detect any prblems with yur transactin and yu want t cntact supprt. ipgapi:avsrespnse xs:string Returns the address verificatin system (AVS) respnse. ipgapi:tdate xs:string Stres the TDate yu have t supply when viding this transactin (which is nly pssible fr Sale and PstAuth transactins). In this case, pass its firstdata.cm 35

36 value in the v1:tdate element f the Vid transactin yu want t build. ipgapi:transactinresult xs:string Stres the transactin result which is always set t APPROVED in case f an apprval. ipgapi:terminalid xs:string The Terminal ID used fr this transactin Transactin Failure As shwn in the previus chapter, a SOAP fault message, resulting frm the credit card prcessr having failed t prcess yur transactin, cntains an ipgapi:ipgapiorderrespnse element passed as child f a SOAP detail element. Nte that its sub elements are exactly the same as in the transactin apprval case. Their meaning in the failure case is described belw: Path/Name XML Schema type Descriptin ipgapi: xs:string CmmercialServicePrvider Indicates yur prvider. ipgapi:transactintime xs:string The time stamp which is set by the Internet Payment Gateway befre returning the transactin failure. ipgapi: xs:string In sme cases, this element might be PrcessrReferenceNumber empty. Stres a number allwing the credit card prcessr t refer t this transactin. Yu d nt need t prvide this number in any further transactins. Hwever, have that number ready, in case yu detect any prblems with yur transactin and ipgapi: PrcessrRespnseMessage ipgapi: PrcessrRespnseCde ipgapi: PrcessrApprvalCde ipgapi: PrcessrReceiptNumber ipgapi: PrcessrTraceNumber xs:string xs:string xs:string xs:string xs:string yu want t cntact supprt. Stres the errr message the credit card prcessr has returned. Fr instance, in case f an expired credit card this might be: Card expiry date exceeded The respnse cde frm the credit card prcessr The apprval cde frm the credit card prcessr The receipt number frm the credit card prcessr The trace number frm the credit card prcessr ipgapi:errrmessage xs:string Stres the errr message returned by the Internet Payment Gateway. It is always encded in the frmat SGS- XXXXXX: Message with XXXXXX being a six digit errr cde and Message describing the errr (this descriptin might be different frm the prcessr respnse message). Fr instance, in the abve example the firstdata.cm 36

37 errr message SGS : Card expiry date exceeded is returned. Make sure t have the errr cde and message ready when cntacting supprt. ipgapi:orderid xs:string Stres the rder ID. In cntrast t an apprval, this rder ID is never required fr any further transactin, but needed fr tracing the cause f the errr. Hence, make sure t have it ready when cntacting supprt. ipgapi:apprvalcde xs:string This element is empty in case f a transactin failure. ipgapi:avsrespnse xs:string Returns the address verificatin system (AVS) respnse. ipgapi:tdate xs:string Stres the TDate. Similar t the rder ID, the TDate is never required fr any further transactin, but needed fr tracing the errr cause. Hence, make sure t have it ready when cntacting supprt. ipgapi:transactinresult xs:string In the failure case, there are three pssible values: DECLINE FRAUD FAILED DECLINE is returned in case the credit card prcessr des nt accept the transactin, e.g. when finding the custmer s funds nt t be sufficient. FRAUD is returned in case a fraud attempt is assumed by the Internet Payment Gateway. If an internal gateway errr shuld ccur, the returned value is FAILED. ipgapi:terminalid xs:string The Terminal ID used fr this transactin. 12 Building an HTTPS POST Request Building an HTTPS POST request is a task yu rarely have t d by hand. There are plenty f tls and libraries supprting yu in the cmpsitin f HTTPS requests. Mstly, the required functinality fr ding this task is cntained in the standard set f libraries cming with the technlgical envirnment in which yu develp yur nline stre. Since all f these libraries slightly differ in their usage, n general building prcess can be described. In rder t illustrate the basic cncepts, the fllwing chapters will give examples shwing hw t build a valid HTTPS request in PHP and ASP. In general, the set f parameters yu have t prvide fr building a valid HTTPS request in whatever technlgy is as fllws: firstdata.cm 37

38 Parameter Value Descriptin URL test.ipg-nline.cm/ ipgapi/services This is the full URL f the First Data API Web Service depending n the functinality yu use fr building HTTP requests, yu might have t split this URL int hst and service and prvide this infrmatin in the apprpriate HTTP request headers. Cntent-Type text/xml This is an additinal HTTP header needed t be set. This is due t the SOAP request message being encded in XML and passed as cntent in the HTTP POST request bdy. Authrizatin Type: Basic Username: WSstreID._.userID Passwrd: yurpasswrd Yur stre is identified at the Internet Payment Gateway by checking these credentials. In rder t use First Data API, yu have t prvide yur stre ID, user ID, and passwrd as the cntent f an HTTP Basic authrizatin header. Fr instance, if yur stre ID is 101, yur user ID 007, and yur passwrd mypw, the authrizatin user name is WS101._.007. The cmplete HTTP authrizatin header wuld be: Authrizatin: Basic V1MxMDEuXy4wMDc6bXlQVw== Nte that the latter string is the base 64 encding result f the string WS101._.007:myPW. HTTP Bdy SOAP request XML The HTTP POST request bdy takes the SOAP request message 12.1 PHP Ding HTTP cmmunicatin in PHP is mstly accmplished with the aid f curl which is shipped bth as library and cmmand line tl. In newer PHP versins, curl is already included as extensin which has t be activated, thus making the curl functinality available in any PHP script. While this is a rather straightfrward task in case yur Web server perates n Micrsft Windws, it might require t cmpile PHP n Unix/Linux machines. Therefre, yu might cnsider t call the curl cmmand line tl frm yur PHP script instead f using the curl extensin. Bth variants are cnsidered in the fllwing beginning with the usage f the curl extensin in PHP running n a Windws machine Using the curl PHP Extensin Mstly, activating the curl extensin in PHP simply requires t uncmment the fllwing line in yur php.ini cnfiguratin file: ;extensin=php_curl.dll Nte that ther PHP versins might require ther actins in rder t enable curl supprt in PHP. Refer t yur PHP dcumentatin fr mre infrmatin. After activating curl, an HTTP request with the abve parameters is set up with the fllwing PHP statements: <?php firstdata.cm 38

39 // string the SOAP message in a variable nte that the plain XML cde // is passed here as string fr reasns f simplicity, hwever, it is // certainly a gd practice t build the XML e.g. with DOM furthermre, // when using special characters, yu shuld make sure that the XML string // gets UTF-8 encded (which is nt dne here): $bdy = "<SOAP-ENV:Envelpe...>...</SOAP-ENV:Envelpe>"; // initializing curl with the IPG API URL: $ch = curl_init(" // setting the request type t POST: curl_setpt($ch, CURLOPT_POST, 1); // setting the cntent type: curl_setpt($ch, CURLOPT_HTTPHEADER, array("cntent-type: text/xml")); // setting the authrizatin methd t BASIC: curl_setpt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC); // supplying yur credentials: curl_setpt($ch, CURLOPT_USERPWD, "WS101._.007:myPW"); // filling the request bdy with yur SOAP message: curl_setpt($ch, CURLOPT_POSTFIELDS, $bdy);...?> Setting the security ptins which are necessary fr enabling SSL cmmunicatin will be discussed in the next chapter extending the abve script Using the curl Cmmand Line Tl Fr the reasns described abve, yu might cnsider using the curl cmmand line tl instead f the extensin. Using the tl des nt require any PHP cnfiguratin effrts yur PHP script simply has t call the executable with a set f parameters. Since the security settings are pstpned t the next chapter, the fllwing script nly shws hw t set up the standard HTTP parameters, i.e. the script is extended with the SSL parameters in the next chapter. <?php // string the SOAP message in a variable nte that yu have t escape // " and \n, since the latter makes the cmmand line tl fail, // furthermre nte that the plain XML cde is passed here as string // fr reasns f simplicity, hwever, it is certainly a gd practice // t build the XML e.g. with DOM finally, when using special // characters, yu shuld make sure that the XML string gets UTF-8 encded // (which is nt dne here): $bdy = "<SOAP-ENV:Envelpe...>...</SOAP-ENV:Envelpe>"; // setting the path t the curl cmmand line tl adapt this path t the // path where yu have saved the curl binaries: $path = "C:\curl\curl.exe"; // setting the IPG API URL: $apiurl = " // setting the cntent type: $cntenttype = " --header \"Cntent-Type: text/xml\""; // setting the authrizatin methd t BASIC and supplying // yur credentials: $user = " --basic --user WS101._.007:myPW"; // setting the request bdy with yur SOAP message this autmatically // marks the request as POST: $data = " --data \"".$bdy."\""....?> firstdata.cm 39

40 12.2 ASP There are multiple ways f building an HTTP request in ASP. Hwever, in the fllwing, the usage f WinHTTP 5.1 is described as it ships with Windws Server 2003 and Windws XP SP2. Furthermre, nly a few lines f cde are required in rder t set up a valid HTTP request. Nte that the fllwing cde fragment is written in JavaScript. Using VB Script instead des nt fundamentally change the shwn statements. <%@ language="javascript"%> <html>...<bdy> <% // string the SOAP message in a variable nte that the plain XML cde // is passed here as string fr reasns f simplicity, hwever, it is // certainly a gd practice t build the XML e.g. with DOM furthermre, // when using special characters, yu shuld make sure that the XML string // gets UTF-8 encded (which is nt dne here): var bdy = "<SOAP-ENV:Envelpe...>...</SOAP-ENV:Envelpe>"; // cnstructing the request bject: var request = Server.createObject("WinHttp.WinHttpRequest.5.1"); // initializing the request bject with the HTTP methd POST // and the IPG API URL: request.pen("post", " // setting the cntent type: request.setrequestheader("cntent-type", "text/xml"); // setting the credentials: request.setcredentials("ws _.1001", "testinger", 0);... %> </bdy></html> Nte that the abve script is extended in the next chapter by setting the security ptins which are required fr establishing the SSL channel. 13 Establishing an SSL cnnectin Befre sending the HTTP request built in the previus chapter, a secure cmmunicatin channel has t be established, guaranteeing bth that all data is passed encrypted and that the client (yur applicatin) and server (running the First Data API Web Service) can be sure f cmmunicating with each ther and n ne else. Bth are achieved by establishing an SSL cnnectin with the client and server exchanging certificates. A certificate identifies a cmmunicatin party uniquely. Basically, this prcess wrks as fllws: 1. The client starts t establish the secure cnnectin by sending its client certificate t the server. 2. The server receives the client certificate and verifies it against the client certificate it has stred fr this client. 3. If valid, the server respnds by sending its server certificate. 4. The client receives the server certificate and verifies it against the trusted server certificate. 5. If valid, bth parties establish the SSL channel, as they can be sure that they are cmmunicating with each ther and n ne else. All data exchanged between bth parties is encrypted. firstdata.cm 40

41 Fllwing this prcess, yur applicatin has t d tw things: First, start the cmmunicatin by sending its client certificate. Secnd, verify the received server certificate. Hw this is accmplished differs frm platfrm t platfrm. Hwever, in rder t illustrate the basic cncepts, the PHP and ASP scripts started in the previus chapter will be cntinued by extending them with the relevant statements necessary fr setting up an SSL cnnectin PHP Picking up the distinctin between using either the PHP curl extensin r the cmmand line tl, the fllwing tw sectins will cntinue the tw different ways f enabling secure HTTP cmmunicatin. Hwever, regardless f which apprach yu intend t use, yu will be cnfrnted with ne special feature f curl: curl requires the client certificate t be passed as PEM file with the client certificate private key passed in an extra file. Finally, the client certificate private key passwrd has t be supplied. Simply spken, the PEM file cntains the certificate with all infrmatin necessary fr allwing the server t identify the client. The private key is nt really necessary fr this kind f cmmunicatin. Hwever, it is crucial fr making curl wrk Using the PHP curl Extensin Building n the script started in the previus chapter, the parameters which are necessary fr establishing an SSL cnnectin with curl are set in the fllwing statements: <?php... // telling curl t verify the server certificate: curl_setpt($ch, CURLOPT_SSL_VERIFYPEER, 1); // setting the path where curl can find the certificate t verify the // received server certificate against: curl_setpt($ch, CURLOPT_CAINFO, "C:\certs\getrust.pem"); // setting the path where curl can find the client certificate: curl_setpt($ch, CURLOPT_SSLCERT, "C:\certs\WS101._.007.pem"); // setting the path where curl can find the client certificate s // private key: curl_setpt($ch, CURLOPT_SSLKEY, "C:\certs\WS101._.007.key"); // setting the key passwrd: curl_setpt($ch, CURLOPT_SSLKEYPASSWD, "ckp_ ");...?> Nte that this script is extended in the next chapter by the statements ding the actual HTTP request Using the curl Cmmand Line Tl Building n the script started in the previus chapter, the statements which initialize the SSL parameters passed t the curl cmmand line tl are as fllws: <?php... // setting the path where curl can find the certificate t verify the // received server certificate against: $servercert = " --cacert C:\certs\getrust.pem"; // setting the path where curl can find the client certificate: $clientcert = " --cert C:\certs\WS101._.007.pem"; // setting the path where curl can find the client certificate s // private key: firstdata.cm 41

42 $clientkey = " --key C:\certs\WS101._.007.key"; // setting the key passwrd: $keypw = " --pass ckp_ ";...?> Nte that this script is extended in the next chapter by the statements ding the actual HTTP request ASP Fr making the abve SSL initializatin prcess wrk, ASP requires bth the client and the server certificate t be present in certificate stres. In ther wrds, befre ASP can cmmunicate via SSL, bth certificates have t be installed first. The fllwing steps which assume ASP running n Micrsft IIS 5.1 under Windws XP, will guide yu thrugh this set up prcess: 1. Click Start, click Run..., type mmc and click OK. 2. Open the File menu, select Add/Remve Snap-In. 3. Click Add. 4. Under Snap-In chse Certificates and click Add. 5. Yu will be prmpted t select the accunt fr which yu want t manage the certificates. Since IIS uses the cmputer accunt, chse Cmputer Accunt and click Next. 6. Chse Lcal Cmputer and click Finish. 7. Click Clse and then OK. 8. Expand the Certificates (Lcal Cmputer) tree - the client certificate will be installed in the Persnal flder. 9. Therefre, right click the Certificates flder, select All Tasks, click Imprt... this will pen the Certificate Imprt Wizard. 10. Click Next. Chse yur client certificate p12 file and click Next. 11. Prvide the client certificate installatin passwrd and click Next. 12. Select Place all certificates in the fllwing stre and brwse fr the Persnal flder if nt yet displayed. Click Next. 13. Check the displayed settings and click Finish. Yur client certificate is nw installed in the lcal cmputer s persnal certificates stre. Here, IIS (running ASP) can lkup the client certificate when cmmunicating with anther server via HTTP. 14. Nw, the server certificate has t be installed in the Trusted Rt Certificatin Authrities stre. The certificates in this stre are used fr verificatin whenever receiving a certificate frm a server. That means the First Data API server certificate has t be installed here. In this way, IIS is able t verify the server certificate received when cntacting the Web Service. Therefre, chse Trusted Rt Certificatin Authrities frm the Certificates (Lcal Cmputer) tree pen the sub flder Certificates. 15. Right click the Certificates flder, select All Tasks, click Imprt... this will pen the Certificate Imprt Wizard again. 16. Click Next. Chse the server certificate PEM file and click Next. 17. Select Place all certificates in the fllwing stre and brwse fr the Trusted Rt Certificatin Authrities flder if nt yet displayed. Click Next. 18. Check the displayed settings and click Finish. The server certificate is nw installed in the lcal cmputer s trusted certificates stre. Here, IIS can lkup the server certificate fr verificatin against the First Data API server certificate received during the SSL setup prcess. After installing bth certificates ne culd assume that the envirnment allwing ASP t cmmunicate via SSL is set up. Hwever, there is still ne thing which makes the firstdata.cm 42

43 cmmunicatin fail: IIS running yur ASP has a Windws user which des nt have the necessary rights t access the client certificate private key. Althugh accessing the private key is nt really necessary fr establishing the SSL cnnectin t the Internet Payment Gateway, the IIS user needs access rights fr running the authenticatin prcess in ASP. Fr granting rights t a user, Micrsft prvides the WinHttpCertCfg.exe tl yu can dwnlad fr free under: After installing the tl, pen a cmmand prmpt, switch t the directry where yu have installed the tl, and type in the fllwing line fr granting access t the IIS user: winhttpcertcfg -g -c LOCAL_MACHINE\My -s WS101._.007 -a IWAM_MyMachine LOCAL_MACHINE\My determines the key stre where the persnal certificates fr the lcal machine accunt are stred. After installing the client certificate in the persnal certificates stre as described abve, the client certificate can be fund under this path, s there is n need t prvide anther path. WS101._.007 is the name f the client certificate. Yu have t adapt this name t the name f yur client certificate. Therefre, check the name displayed fr the client certificate in the mmc cnsle after installing it as described abve. Finally, IWAM_MyMachine dentes the IIS user name. Nte that IIS 5.1 uses IWAM_MachineName by default. That means if yur machine has the name IISServerMachine, the IIS user will be called IWAM_IISServerMachine. Nte that ther IIS versins might use a different naming scheme. If yu d nt knw yur machine name r IIS user name, check the IIS dcumentatin and cntact yur administratr. Nw yu are ready t use SSL in yur ASP cde. The cde extending the ASP script started in the previus chapter is reduced t nly ne additinal statement which tells WinHTTP which client certificate t send (and where t find it) when cntacting the Internet Payment Gateway: <%@ language="javascript"%> <html>...<bdy> <%... // setting the path where the client certificate t send can be fund: request.setclientcertificate("local_machine\\my\\ws101._.007");... %> </bdy></html> Nte that if yu use VB Script, the cde lks almst the same hwever, d nt frget t replace the dubled backslashes in the path with single nes (i.e. the path t the certificate wuld be "LOCAL_MACHINE\My\WS101._.007" instead). Nte that this script is extended in the next chapter by the statements ding the actual HTTP request. 14 Sending the HTTPS POST Request and Receiving the Respnse The actual cmmunicatin with the First Data API Web Service takes place when sending the HTTPS request and waiting fr a respnse. Again, hw this is dne depends n the firstdata.cm 43

44 technlgy yu are using. Mst HTTP libraries fully cver the underlying cmmunicatin details and reduce this prcess t a single peratin call returning the HTTP respnse as result bject. In any case, the parameters which are required fr successfully perfrming an HTTP POST request ver SSL and receiving the respnse (carrying a 200 HTTP status cde) have been described in the previus tw chapters. Setting invalid r incrrect parameters results in the web server running the First Data API Web Service t return a standard HTTP errr cde in the HTTP header f the respnse r sending an SSL failure. Their meanings can be fund in any HTTP/SSL guide. Hwever, there is ne imprtant exceptin: In case the HTTP parameters yu have prvided are crrect, but the Web Service has failed t prcess yur transactin due t an incrrect value cntained in the SOAP request message (e.g. an invalid credit card number), a SOAP exceptin is thrwn and transferred in the bdy f an HTTP respnse carrying the errr cde 500. Details abut the exceptin cause are prvided in the SOAP fault message which is described in the cntext f the next chapter. In rder t cmplete the PHP and ASP scripts, built gradually in the previus chapters, the fllwing tw chapters will prvide the statements necessary fr ding an HTTP call using these technlgies PHP Again, the distinctin between the PHP curl extensin and the curl cmmand line tl is made in the fllwing: Using the PHP curl Extensin The PHP script using the curl extensin is finally cmpleted by ding the call with the statements shwn belw. Nte that the HTTP call returns a SOAP respnse r fault message in the HTTP respnse bdy. <?php... // telling curl t return the HTTP respnse bdy as peratin result // value when calling curl_exec: curl_setpt($ch, CURLOPT_RETURNTRANSFER, 1); // calling curl and saving the SOAP respnse message in a variable which // cntains a string like "<SOAP-ENV:Envelpe...>...</SOAP-ENV:Envelpe>": $result = curl_exec($ch); // clsing curl: curl_clse($ch);?> Using the curl Cmmand Line Tl Ding the HTTP call with the curl cmmand line tl simply requires cmpleting the cmmand line statement and executing the external tl. Hwever, reading the HTTP respnse is mre cmplicated as the PHP exec cmmand saves each line returned by an external prgram as ne element f an array. Cncatenating all elements f that array results in the SOAP respnse r fault message which has been returned in the HTTP respnse bdy. The fllwing statements handle the HTTP call and cmplete the script: <?php... // saving the whle cmmand in ne variable: firstdata.cm 44

45 $curl = $path. $data. $cntenttype. $user. $servercert. $clientcert. $clientkey. $keypw. $apiurl; // preparing the array cntaining the lines returned by the curl // cmmand line tl: $returnarray = array(); // perfrming the HTTP call by executing the curl cmmand line tl: exec($curl, $returnarray); // preparing a variable taking the cmplete result: $result = ""; // cncatenating the different lines returned by the curl cmmand // line tl this result in the variable $result carrying the entire // SOAP respnse message as string: freach($returnarray as $item) $result = $result.$item;?> 14.2 ASP Ding the actual HTTP call with WinHTTP in ASP is limited t ne simple peratin call taking the SOAP request XML as a parameter. After successfully perfrming the request a SOAP respnse r fault message is returned which can be retrieved as a string by accessing the request bject s respnsetext prperty. Hw such a SOAP respnse message lks like is described in the next chapter. The fllwing statements cmplete the ASP script: <%@ language="javascript"%> <html>...<bdy> <%... // ding the HTTP call with the SOAP request message as input: request.send(bdy); // saving the SOAP respnse message in a string variable: var respnse = request.respnsetext; %> </bdy></html> 15 Using a Java Client t cnnect t the web service Fr quick and simple integratin, First Data prvides a Java Client t cnnect t the Internet Payment Gateway web service. An instance f the IPGApiClient class manages the cnnectin t the web service, builds XML and the SOAP messages and evaluates the respnses. T cnstruct a transactin r t handle a respnse, the develper wrks with simple Java bean classes. firstdata.cm 45

46 15.1 Instance an IPGApiClient There are several cnstructrs available t instantiate the IPGApiClient. The example belw illustrates hw t use the easiest ne f the cnstructrs. The getbytes methd is als included fr the cmpletin and simplificatin f the example. String url = " String streid = "yur stre id"; String passwrd = "yur passwrd"; byte[] key = getbytes("/path/t/yur/keystre.ks"); String keypw = "yur key stre passwrd"; IPGApiClient client = new IPGApiClient(url, streid, passwrd, key, keypw); /** * getbytes * reads a resurce and returns a byte array resurce the resurce t read the resurce as byte array */ public static byte[] getbytes(final String resurce) thrws IOExceptin { final InputStream input = IO.class.getResurceAsStream(resurce); if (input == null) { thrw new IOExceptin(resurce); } try { final byte[] bytes = new byte[input.available()]; input.read(bytes); return bytes; } finally { try { input.clse(); } catch (IOExceptin e) { lg.warn(resurce); } } } 15.2 Hw t cnstruct a transactin and handle the respnse There are different classes fr transactins with the fllwing card types: Credit Card German Direct Debit UK Debit Cards. The fllwing factry class can be used t generate the class yu need: de.firstdata.ipgapi.client.transactin.ipgapitransactinfactry The fllwing example shws a Credit Card Sale transactin fr an amunt f 7 Eurs: Amunt amunt = new Amunt("7", "978"); // ISO 4217: EUR = 978 CreditCard cc = new CreditCard(" ", "07", "17", null); CCSaleTransactin transactin = IPGApiTransactinFactry.createSaleTransactinCredit(amunt, cc); firstdata.cm 46

47 // sme transactins may include further infrmatin e.g. the custmer transactin.setname("a name"); try { IPGApiResult result = client.cmmittransactin(transactin); // nw yu can read the cnclusin System.ut.println(result.getOrderId()); System.ut.println(result.getTransactinTime()); //... } catch (PrcessingExceptin e) { // ERROR: transactin nt passed } 15.3 Hw t cnstruct an actin The fllwing Factry Class can be used t generate the class yu need: de.firstdata.ipgapi.client.transactin.ipgapiactinfactry T cmmit an actin yu need t use the cmmitactin methd f the IPGApiClient. The further prcess is similar t payment transactins Hw t cnnect behind a prxy Befre yu use the IPGApiClient behind a prxy yu must set the prxy cnfiguratin f the client with the IPGApiClient methd: IPGApiClient.setPrxy( final String hst, final Integer prt, final String user, final String dmain, final String passwrd) The parameters user, dmain and passwrd shuld be null if n identificatin needed. If yu need t identify n a MS Windws prxy yu must set the parameter dmain. T identify n systems like Unix the parameter dmain must be null. Fr mre infrmatin see the apache javadc f UsernamePasswrdCredentials fr Unix systems: 3.x/apidcs/rg/apache/cmmns/httpclient/UsernamePasswrdCredentials.html#Username PasswrdCredentials(java.lang.String,%20java.lang.String) r NTCredentials fr MS Windws: 3.x/apidcs/rg/apache/cmmns/httpclient/NTCredentials.html#NTCredentials(java.lang.Stri ng,%20java.lang.string,%20java.lang.string,%20java.lang.string) After setting the prxy parameters yu must call the IPGApiClient.init() methd. firstdata.cm 47

48 Appendix ipgapi.xsd <?xml versin="1.0" encding="utf-8"?> <xs:schema xmlns:xs=" xmlns:ipgapi=" xmlns:a1=" xmlns:v1=" elementfrmdefault="qualified" targetnamespace=" <xs:imprt namespace=" schemalcatin="v1.xsd" /> <xs:imprt namespace=" schemalcatin="a1.xsd" /> <! > <!-- Request > <! > name="ipgapiorderrequest"> <xs:cmplextype> <xs:chice> ref="v1:transactin" /> </xs:chice> </xs:cmplextype> name="ipgapiactinrequest"> <xs:cmplextype> <xs:chice> ref="a1:actin" /> </xs:chice> </xs:cmplextype> <! > <!-- Respnse > <! > name="ipgapiorderrespnse"> <xs:cmplextype> <xs:all> name="apprvalcde" type="xs:string" /> name="avsrespnse" type="xs:string" /> name="cmmercialserviceprvider" type="xs:string" /> name="errrmessage" type="xs:string" />

49 name="orderid" type="xs:string" /> name="prcessrapprvalcde" type="xs:string" /> name="prcessrreceiptnumber" type="xs:string" /> name="prcessrreferencenumber" type="xs:string" /> name="prcessrrespnsecde" type="xs:string" /> name="prcessrrespnsemessage" type="xs:string" /> name="prcessrtracenumber" type="xs:string" /> name="tdate" type="xs:string" /> name="terminalid" type="xs:string" /> name="transactinresult" type="xs:string" /> name="transactintime" type="xs:string" /> </xs:all> </xs:cmplextype> name="ipgapiactinrespnse"> <xs:cmplextype> <xs:sequence> name="successfully" type="xs:blean" /> name="orderid" type="xs:string" ref="a1:errr" minoccurs="0" maxoccurs="unbunded" /> ref="a1:transactinvalues" minoccurs="0" maxoccurs="unbunded" /> </xs:sequence> </xs:cmplextype> </xs:schema>

50 v1.xsd <?xml versin="1.0" encding="utf-8"?> <xs:schema xmlns:xs=" xmlns:v1=" targetnamespace=" elementfrmdefault="qualified"> <! > <!-- main > <! > name="transactin" type="v1:transactin" /> <xs:cmplextype name="transactin"> <xs:sequence> <xs:chice> <xs:sequence> name="creditcardtxtype" type="v1:creditcardtxtype" /> name="creditcarddata" type="v1:creditcarddata" ref="v1:creditcard3dsecure" </xs:sequence> <xs:sequence> name="custmercardtxtype" type="v1:custmercardtxtype" /> name="custmercarddata" type="v1:custmercarddata" </xs:sequence> <xs:sequence> name="de_directdebittxtype" type="v1:de_directdebittxtype" /> name="de_directdebitdata" type="v1:de_directdebitdata" </xs:sequence> <xs:sequence> name="uk_debitcardtxtype" type="v1:uk_debitcardtxtype" /> name="uk_debitcarddata" type="v1:uk_debitcarddata" </xs:sequence> </xs:chice> ref="v1:payment" ref="v1:transactindetails"

51 ref="v1:billing" ref="v1:shipping" </xs:sequence> </xs:cmplextype> <! > <!-- Optins > <! > <xs:cmplextype name="creditcardtxtype"> <xs:cmplexcntent> <xs:extensin base="v1:optins"> <xs:sequence> name="type"> <xs:simpletype> <xs:restrictin base="xs:string"> <xs:enumeratin value="credit" /> <xs:enumeratin value="frceticket" /> <xs:enumeratin value="pstauth" / <xs:enumeratin value="preauth" /> <xs:enumeratin value="return" /> <xs:enumeratin value="sale" /> <xs:enumeratin value="vid" /> </xs:restrictin> </xs:simpletype> </xs:sequence> </xs:extensin> </xs:cmplexcntent> </xs:cmplextype> <xs:cmplextype name="custmercardtxtype"> <xs:cmplexcntent> <xs:extensin base="v1:optins"> <xs:sequence> name="type"> <xs:simpletype> <xs:restrictin base="xs:string"> <xs:enumeratin value="frceticket" /> <xs:enumeratin value="bwlistcheck" /> <xs:enumeratin value="sale" /> </xs:restrictin> </xs:simpletype> </xs:sequence> </xs:extensin> </xs:cmplexcntent> </xs:cmplextype> <xs:cmplextype name="de_directdebittxtype"> <xs:cmplexcntent>

52 <xs:extensin base="v1:optins"> <xs:sequence> name="type"> <xs:simpletype> <xs:restrictin base="xs:string"> <xs:enumeratin value="sale" /> <xs:enumeratin value="vid" /> </xs:restrictin> </xs:simpletype> </xs:sequence> </xs:extensin> </xs:cmplexcntent> </xs:cmplextype> <xs:cmplextype name="uk_debitcardtxtype"> <xs:cmplexcntent> <xs:extensin base="v1:optins"> <xs:sequence> name="type"> <xs:simpletype> <xs:restrictin base="xs:string"> <xs:enumeratin value="credit" /> <xs:enumeratin value="return" /> <xs:enumeratin value="sale" /> <xs:enumeratin value="vid" /> </xs:restrictin> </xs:simpletype> </xs:sequence> </xs:extensin> </xs:cmplexcntent> </xs:cmplextype> <xs:cmplextype name="optins"> <xs:sequence> name="streid" type="v1:string20max" </xs:sequence> </xs:cmplextype> <! > <!-- Card > <! > <xs:cmplextype name="creditcarddata"> <xs:sequence> <xs:chice> <xs:sequence> <xs:grup ref="v1:card" name="cardcdevalue" type="v1:cardcdevalue"

53 </xs:sequence> name="trackdata" type="v1:trackdata" /> </xs:chice> </xs:sequence> </xs:cmplextype> <xs:cmplextype name="custmercarddata"> <xs:sequence> <xs:chice> <xs:grup ref="v1:card" /> name="trackdata" type="v1:trackdata" /> </xs:chice> </xs:sequence> </xs:cmplextype> <xs:cmplextype name="de_directdebitdata"> <xs:sequence> <xs:chice> <xs:sequence> name="bankcde"> <xs:simpletype> <xs:restrictin base="xs:string"> <xs:pattern value="[0-9]{8}" /> </xs:restrictin> </xs:simpletype> name="accuntnumber"> <xs:simpletype> <xs:restrictin base="xs:string"> <xs:pattern value="[0-9]{1,10}" /> </xs:restrictin> </xs:simpletype> </xs:sequence> name="trackdata" type="v1:trackdata" /> </xs:chice> </xs:sequence> </xs:cmplextype> <xs:cmplextype name="uk_debitcarddata"> <xs:sequence> <xs:grup ref="v1:card" /> name="cardcdevalue" type="v1:cardcdevalue" name="issuen" minoccurs="0"> <xs:simpletype> <xs:restrictin base="xs:string"> <xs:pattern value="[0-9]{0,4}" /> </xs:restrictin> </xs:simpletype> </xs:sequence> </xs:cmplextype> <xs:grup name="card"> <xs:sequence>

54 name="cardnumber"> <xs:simpletype> <xs:restrictin base="xs:string"> <xs:pattern value="[0-9]{13,24}" /> </xs:restrictin> </xs:simpletype> name="expmnth"> <xs:simpletype> <xs:restrictin base="xs:string"> <xs:pattern value="(0[1-9]) (1[0-2])" /> </xs:restrictin> </xs:simpletype> name="expyear"> <xs:simpletype> <xs:restrictin base="xs:string"> <xs:pattern value="[0-9]{2}" /> </xs:restrictin> </xs:simpletype> </xs:sequence> </xs:grup> <xs:simpletype name="cardcdevalue"> <xs:restrictin base="xs:string"> <xs:pattern value="[0-9]{3,4} " /> </xs:restrictin> </xs:simpletype> <xs:simpletype name="trackdata"> <xs:restrictin base="xs:string"> <!-- track 1 length + track 2 length + track 3 length = = > <xs:pattern value="[a-za-z0-9;%=^?/ ]{1,261}" /> </xs:restrictin> </xs:simpletype> <! > <!-- cmmn > <! > name="creditcard3dsecure"> <xs:cmplextype> <xs:all> name="verificatinrespnse"> <xs:simpletype> <xs:restrictin base="xs:string"> <xs:enumeratin value="n" /> <xs:enumeratin value="u" /> <xs:enumeratin value="y" /> </xs:restrictin> </xs:simpletype> name="payerauthenticatinrespnse" minoccurs="0"> <xs:simpletype>

55 <xs:restrictin base="xs:string"> <xs:enumeratin value="a" /> <!-- xs:enumeratin value="e" /--> <xs:enumeratin value="n" /> <xs:enumeratin value="u" /> <xs:enumeratin value="y" /> </xs:restrictin> </xs:simpletype> name="authenticatinvalue" type="v1:string20" name="xid" type="v1:string20" </xs:all> </xs:cmplextype> name="payment"> <xs:cmplextype> <xs:sequence> name="hsteddataid" type="v1:string128max" <xs:grup ref="v1:amunt" </xs:sequence> </xs:cmplextype> <xs:grup name="amunt"> <xs:sequence> name="chargettal"> <xs:simpletype> <xs:restrictin base="xs:decimal"> <xs:pattern value="([1-9]([0-9]{0,12}))?[0-9](\.[0-9]{1,2})?" /> </xs:restrictin> </xs:simpletype> name="currency"> <xs:simpletype> <xs:restrictin base="xs:string"> <! > <! > <xs:pattern value="[0-9]{3}" /> </xs:restrictin> </xs:simpletype> </xs:sequence> </xs:grup> name="transactindetails"> <xs:cmplextype> <xs:all> name="invicenumber" type="v1:string48max"

56 name="orderid" type="v1:string100max" name="ip" minoccurs="0"> <xs:simpletype> <xs:restrictin base="xs:string"> <xs:pattern value="(25[0-5] (2[0-4] 1[0-9] [1-9])?[0-9])\.(25[0-5] (2[0-4] 1[0-9] [1-9])?[0-9])\.(25[0-5] (2[0-4] 1[0-9] [1-9])?[0-9])\.(25[0-5] (2[0-4] 1[0-9] [1-9])?[0-9]) " /> </xs:restrictin> </xs:simpletype> name="referencenumber" minoccurs="0"> <xs:simpletype> <xs:restrictin base="xs:string"> <xs:pattern value="(new)?[0-9a-za-z]{1,6}" /> </xs:restrictin> </xs:simpletype> name="tdate" minoccurs="0"> <xs:simpletype> <xs:restrictin base="xs:string"> <xs:pattern value="[0-9]{10} " /> </xs:restrictin> </xs:simpletype> name="transactinorigin" default="eci" minoccurs="0"> <xs:simpletype> <xs:restrictin base="xs:string"> <xs:enumeratin value="eci" /> <xs:enumeratin value="mail" /> <xs:enumeratin value="telephone" /> <xs:enumeratin value="moto" /> <xs:enumeratin value="retail" /> </xs:restrictin> </xs:simpletype> </xs:all> </xs:cmplextype> name="billing"> <xs:cmplextype> <xs:all> name="custmerid" type="v1:string32max" name="name" type="v1:string96max"

57 name="cmpany" type="v1:string96max" name="address1" type="v1:string96max" name="address2" type="v1:string96max" name="city" type="v1:string96max" name="state" type="v1:string96max" name="zip" type="v1:string24max" name="cuntry" type="v1:string32max" name="phne" type="v1:string32max" name="fax" type="v1:string32max" name=" " type="v1:string64max" <!-- DEPRECATED, this field is nt evaluated and will be remved in v2.xsd --> name="addrnum" type="v1:string96max" </xs:all> </xs:cmplextype> name="shipping"> <xs:cmplextype> <xs:all> name="type" type="v1:string20max" name="name" type="v1:string96max"

58 name="address1" type="v1:string96max" name="address2" type="v1:string96max" name="city" type="v1:string96max" name="state" type="v1:string96max" name="zip" type="v1:string24max" name="cuntry" type="v1:string32max" </xs:all> </xs:cmplextype> <! > <!-- simple types > <! > <xs:simpletype name="string128max"> <xs:restrictin base="xs:string"> <xs:maxlength value="128" /> </xs:restrictin> </xs:simpletype> <xs:simpletype name="string100max"> <xs:restrictin base="xs:string"> <xs:maxlength value="100" /> </xs:restrictin> </xs:simpletype> <xs:simpletype name="string96max"> <xs:restrictin base="xs:string"> <xs:maxlength value="96" /> </xs:restrictin> </xs:simpletype> <xs:simpletype name="string64max"> <xs:restrictin base="xs:string"> <xs:maxlength value="64" /> </xs:restrictin> </xs:simpletype> <xs:simpletype name="string32max"> <xs:restrictin base="xs:string"> <xs:maxlength value="32" /> </xs:restrictin>

59 </xs:simpletype> <xs:simpletype name="string24max"> <xs:restrictin base="xs:string"> <xs:maxlength value="24" /> </xs:restrictin> </xs:simpletype> <xs:simpletype name="string20max"> <xs:restrictin base="xs:string"> <xs:maxlength value="20" /> </xs:restrictin> </xs:simpletype> <xs:simpletype name="string20"> <xs:restrictin base="xs:string"> <xs:length value="20" /> </xs:restrictin> </xs:simpletype> </xs:schema>

60 a1.xsd <?xml versin="1.0" encding="utf-8"?> <xs:schema xmlns:xs=" xmlns:a1=" xmlns:v1=" xmlns:ipgapi=" targetnamespace=" elementfrmdefault="qualified"> <xs:imprt namespace=" schemalcatin="ipgapi.xsd" /> <xs:imprt namespace=" schemalcatin="v1.xsd" /> <! > <!-- Request > <! > name="actin"> <xs:cmplextype> <xs:sequence> <xs:chice> ref="a1:initiateclearing" /> ref="a1:inquiryorder" /> ref="a1:strehsteddata" /> ref="a1:recurringpayment" /> </xs:chice> </xs:sequence> </xs:cmplextype> name="initiateclearing"> <xs:cmplextype> <xs:sequence> name="streid" type="v1:string20max" </xs:sequence> </xs:cmplextype> name="inquiryorder"> <xs:cmplextype> <xs:all> name="streid" type="v1:string20max" name="orderid" minoccurs="0"> <xs:simpletype> <xs:restrictin base="xs:string"> <xs:maxlength value="100" /> </xs:restrictin> </xs:simpletype>

61 </xs:all> </xs:cmplextype> name="strehsteddata"> <xs:cmplextype> <xs:sequence> name="streid" type="v1:string20max" name="datastrageitem" maxoccurs="unbunded"> <xs:cmplextype> <xs:sequence> <xs:chice> name="creditcarddata" type="v1:creditcarddata" /> name="custmercarddata" type="v1:custmercarddata" /> name="de_directdebitdata" type="v1:de_directdebitdata" /> name="uk_debitcarddata" type="v1:uk_debitcarddata" /> </xs:chice> name="hsteddataid" type="v1:string128max" /> </xs:sequence> </xs:cmplextype> </xs:sequence> </xs:cmplextype> name="recurringpayment"> <xs:cmplextype> <xs:all> name="functin"> <xs:simpletype> <xs:restrictin base="xs:string"> <xs:enumeratin value="cancel" /> <xs:enumeratin value="install" /> <xs:enumeratin value="mdify" /> </xs:restrictin> </xs:simpletype> name="orderid" type="v1:string100max"

62 </xs:all> </xs:cmplextype> name="streid" type="v1:string20max" ref="a1:recurringpaymentinfrmatin" <!-- n trackdata --> name="creditcarddata" type="v1:creditcarddata" <!-- n hsteddataid --> ref="v1:payment" name="recurringpaymentinfrmatin"> <xs:cmplextype> <xs:all> name="recurringstartdate" minoccurs="0"> <xs:simpletype> <xs:restrictin base="xs:string"> <!-- YYYYMMDD --> <xs:pattern value="[0-9]{8}" /> </xs:restrictin> </xs:simpletype> <! = unlimited --> name="installmentcunt" minoccurs="0"> <xs:simpletype> <xs:restrictin base="xs:integer"> <xs:maxinclusive value="999" /> <xs:mininclusive value="1" /> </xs:restrictin> </xs:simpletype> <!-- fr future use --> name="maximumfailures" minoccurs="0"> <xs:simpletype> <xs:restrictin base="xs:integer"> <xs:maxinclusive value="5" /> <xs:mininclusive value="1" /> </xs:restrictin> </xs:simpletype> name="installmentfrequency" type="xs:psitiveinteger" name="installmentperid" minoccurs="0"> <xs:simpletype> <xs:restrictin base="xs:string">

63 <xs:enumeratin value="day" /> <xs:enumeratin value="week" /> <xs:enumeratin value="mnth" /> <xs:enumeratin value="year" /> </xs:restrictin> </xs:simpletype> </xs:all> </xs:cmplextype> <! > <!-- Respnse > <! > name="errr"> <xs:cmplextype> <xs:all> name="errrmessage" type="xs:string" /> </xs:all> <xs:attribute name="cde" type="xs:string" /> </xs:cmplextype> name="transactinvalues"> <xs:cmplextype> <xs:cmplexcntent> <xs:extensin base="v1:transactin"> <xs:sequence> ref="ipgapi:ipgapiorderrespnse" /> name="receiptnumber" type="xs:string" /> name="respnsecde" type="xs:string" /> name="tracenumber" type="xs:string" /> name="transactinstate" type="xs:string" /> </xs:sequence> </xs:extensin> </xs:cmplexcntent> </xs:cmplextype> </xs:schema>

64 Trubleshting - Merchant Exceptins <detail> XML is nt wellfrmed: Premature end f message. </detail> Pssible Explanatin: Yu have sent an abslutely empty message. The message cntains neither a sap message nr an IPG API message r any ther characters in the http bdy. <detail> XML is nt wellfrmed: Cntent is nt allwed in prlg. </detail> Pssible Explanatin: The message can t be interpreted as an XML message. <detail> XML is nt wellfrmed: XML dcument structures must start and end within the same entity. </detail> Pssible Explanatin: The message starts like an XML message but the end tag f the first pen tag is missing. <detail> XML is nt wellfrmed: The element type "SOAP-ENV:Bdy" must be terminated by the matching end-tag "</SOAP-ENV:Bdy>". </detail> Pssible Explanatin: T an pen internal tag (nt the tp level tag) the end tag is missing. In this example the end tag </SOAP-ENV:Bdy> is missing. <detail> XML is nt wellfrmed: Element type "irgend" must be fllwed by either attribute specificatins, ">" r "/>". </detail> Pssible Explanatin: The message isn t an XML message r a crrect XML message. A > character is missing fr the tag irgend. <detail> XML is nt wellfrmed: Open qute is expected fr attribute "xmlns:ns3" assciated with an element type "ns3:ipgapiorderrequest". </detail>

65 Pssible Explanatin: The value f ne attribute isn t enclsed in qutatin marks. In IPG API attributes are nly used fr the name spaces. <detail> XML is nt wellfrmed: The prefix "ipgapi" fr element "ipgapi:ipgapiorderrequest" is nt bund. </detail> Pssible Explanatin: The name space ipgapi isn t declared. T declare a name space use the xmlns prefix. In this case yu shuld take xmlns:ipgapi= as attribute in the tp level tag f the IPG API message (IPGApiOrderRequest r IPGApiActinRequest). <detail> XML is nt wellfrmed: The prefix "xmln" fr attribute "xmln:ns2" assciated with an element type "ns3:ipgapiorderrequest" is nt bund. </detail> Pssible Explanatin: T declare an wn name space, nly the predefined name space xmlns allwed. In this case the prefix is written as xmln and nt as xmlns. <detail> XML is nt wellfrmed: Unable t create envelpe frm given surce because the namespace was nt recgnized </detail> Pssible Explanatin: The message culd be interpreted as an XML message and the enclsing sap message is crrect, but the including IPG API message in the sap bdy has n name spaces r the name spaces are nt declared crrectly. The crrect name spaces are described in the xsd. <detail> XML is nt wellfrmed: The prcessing instructin target matching "[xx][mm][ll]" is nt allwed. </detail> Pssible Explanatin: The whle message must be a crrect XML message s that the including IPG API message must nt cntains the xml declaratin <?xml?>. <detail> Unexpected characters befre XML declaratin </detail> Pssible Explanatin:

66 The XML must start with <?xml. Please check, if yu send an empty line r anther white space character in frnt f the xml and remve them. <detail> XML is nt a SOAP message: Unable t create envelpe frm given surce because the rt element is nt named "Envelpe" </detail> Pssible Explanatin: The message seems t be a crrect XML message but nly sap messages are accepted. This message must be enclsed by a sap message. <detail> XML is nt a valid SOAP message: Errr with the determinatin f the type. Prbably the envelpe part is nt crrect. </detail> Pssible Explanatin: The sap bdy tag is missing. <detail> Surce bject passed t ''{0}'' has n cntents. </detail> Pssible Explanatin: The sap bdy is empty. The including IPG API message is missing. <detail> Included XML is nt a valid IPG API message: unsupprted tp level {namespace}tag "irgendwas" in the sap bdy. Only ne f [ { { ] allwed. </detail> Pssible Explanatin: The first tag in the including IPG API message must be ne f IPGApiActinRequest r IPGApiOrderRequest tag and nt the tag irgendwas. In this case this tag has n namespace. <detail> Included XML is nt a valid IPG API message: unsupprted tp level {namespace}tag "{ in the sap bdy. Only ne f [ { { ] allwed. </detail> Pssible Explanatin:

67 The tp level tag f the included IPG API message n allwed tag. In this case the name space is wrng. <detail> cvc-pattern-valid: Value '1.234' is nt facet-valid with respect t pattern '([1-9]([0-9]{0,12}))?[0-9](\.[0-9]{1,2})?' fr type '#AnnType_ChargeTtalAmunt' cvc-type.3.1.3: The value '1.234' f element 'ns3:chargettal' is nt valid. </detail> Pssible Explanatin: The value f a tag des nt crrespnd with the declaratin in the xsd. The value has three decimal places but the xsd nly allws tw. <detail> cvc-cmplex-type.2.4.a: Invalid cntent was fund starting with element 'ns2:expyear'. One f '{" is expected. </detail> Pssible Explanatin: The ccurrences f the tags must be crrespnding t the xsd. We recmmend t use the tags in the same sequence as they are declared in the xsd. In this case the tag ExpMnth is expected and nt ExpYear.

68 Trubleshting - Prcessing Exceptins <detail> <ipgapi:ipgapiorderrespnse xmlns:ipgapi=" <ipgapi:cmmercialserviceprvider /> <ipgapi:transactintime> </ipgapi:transactintime> <ipgapi:prcessrreferencenumber /> <ipgapi:prcessrrespnsemessage /> <ipgapi:errrmessage> SGS-C: : illegal cmbinatin f values fr the 3DSecure: (VerificatinRespnse, PayerAuthenticatinRespnse, PayerAuthenticatinCde) Y null null </ipgapi:errrmessage> <ipgapi:orderid /> <ipgapi:apprvalcde /> <ipgapi:avsrespnse /> <ipgapi:tdate /> <ipgapi:transactinresult>failed</ipgapi:transactinresult> <ipgapi:terminalid /> <ipgapi:prcessrrespnsecde /> <ipgapi:prcessrapprvalcde /> <ipgapi:prcessrreceiptnumber /> <ipgapi:prcessrtracenumber /> </ipgapi:ipgapiorderrespnse> </detail> Explanatin: The cmbinatin f the three values VerificatinRespnse, PayerAuthenticatinRespnse and PayerAuthenticatinCde fr 3DSecure is wrng. Allwed cmbinatins are VerificatinRespnse PayerAuthenticatinRespnse PayerAuthenticatinCde null null null N null null N N null U null null Y A null Y A x Y U null Y Y null Y Y x The payer authenticatin cde x means, that the value is nt null. <detail> <ipgapi:ipgapiorderrespnse xmlns:ipgapi=" <ipgapi:cmmercialserviceprvider /> <ipgapi:transactintime> </ipgapi:transactintime> <ipgapi:prcessrreferencenumber /> <ipgapi:prcessrrespnsemessage /> <ipgapi:errrmessage> SGS :

69 The merchant is nt setup t supprt the requested service. </ipgapi:errrmessage> <ipgapi:orderid> IPGAPI-REQUEST-9c555d a2444c98c5d </ipgapi:orderid> <ipgapi:apprvalcde /> <ipgapi:avsrespnse /> <ipgapi:tdate /> <ipgapi:transactinresult>declined</ipgapi:transactinresult> <ipgapi:terminalid /> <ipgapi:prcessrrespnsecde /> <ipgapi:prcessrapprvalcde /> <ipgapi:prcessrreceiptnumber /> <ipgapi:prcessrtracenumber /> </ipgapi:ipgapiorderrespnse> </detail> Explanatin: This is an example with a German Direct Debit transactin, which is nt supprted fr the merchant. If yu shuld receive this result fr a transactin type which is included in yur agreement, please cntact ur technical supprt team. <detail> <ipgapi:ipgapiorderrespnse xmlns:ipgapi=" <ipgapi:cmmercialserviceprvider /> <ipgapi:transactintime> </ipgapi:transactintime> <ipgapi:prcessrreferencenumber /> <ipgapi:prcessrrespnsemessage /> <ipgapi:errrmessage> SGS : Duplicate transactin. </ipgapi:errrmessage> <ipgapi:orderid> IPGAPI-REQUEST-29351d8e d93-91b83704e00d </ipgapi:orderid> <ipgapi:apprvalcde /> <ipgapi:avsrespnse /> <ipgapi:tdate /> <ipgapi:transactinresult>fraud</ipgapi:transactinresult> <ipgapi:terminalid /> <ipgapi:prcessrrespnsecde /> <ipgapi:prcessrapprvalcde /> <ipgapi:prcessrreceiptnumber /> <ipgapi:prcessrtracenumber /> </ipgapi:ipgapiorderrespnse> </detail> Explanatin: After a transactin further transactins with the same data blcked are fr a cnfigurable time span. See User Guide Virtual Terminal fr details abut the fraud settings. <detail> <ipgapi:ipgapiorderrespnse xmlns:ipgapi=" <ipgapi:cmmercialserviceprvider /> <ipgapi:transactintime> </ipgapi:transactintime> <ipgapi:prcessrreferencenumber />

70 <ipgapi:prcessrrespnsemessage /> <ipgapi:errrmessage> SGS : The currency is nt allwed fr this terminal. </ipgapi:errrmessage> <ipgapi:orderid> IPGAPI-REQUEST-a58f6631-eb71-49c8-bbca-23fff53252fc </ipgapi:orderid> <ipgapi:apprvalcde /> <ipgapi:avsrespnse /> <ipgapi:tdate /> <ipgapi:transactinresult>declined</ipgapi:transactinresult> <ipgapi:terminalid /> <ipgapi:prcessrrespnsecde /> <ipgapi:prcessrapprvalcde /> <ipgapi:prcessrreceiptnumber /> <ipgapi:prcessrtracenumber /> </ipgapi:ipgapiorderrespnse> </detail> Explanatin: This is an example with US Dllar, which is n allwed currency fr this stre. <detail> <ipgapi:ipgapiorderrespnse xmlns:ipgapi=" <ipgapi:cmmercialserviceprvider /> <ipgapi:transactintime> </ipgapi:transactintime> <ipgapi:prcessrreferencenumber /> <ipgapi:prcessrrespnsemessage /> <ipgapi:errrmessage> SGS : There was an unknwn errr in the database. </ipgapi:errrmessage> <ipgapi:orderid> IPGAPI-REQUEST-d26ea5c1-d0de-41d2-8c41-3d6755fc204c </ipgapi:orderid> <ipgapi:apprvalcde /> <ipgapi:avsrespnse /> <ipgapi:tdate> </ipgapi:tdate> <ipgapi:transactinresult>declined</ipgapi:transactinresult> <ipgapi:terminalid /> <ipgapi:prcessrrespnsecde /> <ipgapi:prcessrapprvalcde /> <ipgapi:prcessrreceiptnumber /> <ipgapi:prcessrtracenumber /> </ipgapi:ipgapiorderrespnse> </detail> Pssible Explanatin: One pssible explanatin is that it has been tried t vid a credit card transactin as a different payment/transactin type. <detail> <ipgapi:ipgapiorderrespnse xmlns:ipgapi=" <ipgapi:cmmercialserviceprvider /> <ipgapi:transactintime> </ipgapi:transactintime> <ipgapi:prcessrreferencenumber />

71 <ipgapi:prcessrrespnsemessage /> <ipgapi:errrmessage> SGS : Unknwn prcessr errr ccured. </ipgapi:errrmessage> <ipgapi:orderid> IPGAPI-REQUEST-b3223ee5-156b-4d22-bc3f d59202 </ipgapi:orderid> <ipgapi:apprvalcde /> <ipgapi:avsrespnse /> <ipgapi:tdate> </ipgapi:tdate> <ipgapi:transactinresult>declined</ipgapi:transactinresult> <ipgapi:terminalid /> <ipgapi:prcessrrespnsecde /> <ipgapi:prcessrapprvalcde /> <ipgapi:prcessrreceiptnumber /> <ipgapi:prcessrtracenumber /> </ipgapi:ipgapiorderrespnse> </detail> Explanatin: If yur transactins are nrmally executed, ne pssible explanatin is that the number f Terminal IDs assigned t yur stre are nt sufficient fr yur transactin vlume. Please cntact ur Sales team t rder further Terminal IDs fr lad balancing.

72 Trubleshting - Lgin errr messages when using curl * Abut t cnnect() t test.ipg-nline.cm prt 443 (#0) * Trying cnnected * Cnnected t test.ipg-nline.cm ( ) prt 443 (#0) * unable t set private key file: 'C:\API\cnfig\WS _.1.key' type PEM * Clsing cnnectin #0 curl: (58) unable t set private key file: 'C:\API\cnfig\WS _.1.key' type PEM Explanatin: Keystre and passwrd d nt fit. Check if yu used the right keystre and passwrd. Please check if yu used the WS<streId>._.1.pem file. If yu append.cer t the file name yu can pen the certificate with a duble click. The certificate must be expsed fr yur stre. Please remve the extensin.cer after the check. * SSL certificate prblem, verify that the CA cert is OK. Details: errr: :ssl rutines:ssl3_get_server_certificate:certificate verify failed * Clsing cnnectin #0 curl: (60) SSL certificate prblem, verify that the CA cert is OK. Details: errr: :ssl rutines:ssl3_get_server_certificate:certificate verify failed Mre details here: curl perfrms SSL certificate verificatin by default, using a "bundle" f Certificate Authrity (CA) public keys (CA certs). The default bundle is named curl-ca-bundle.crt; yu can specify an alternate file using the --cacert ptin. If this HTTPS server uses a certificate signed by a CA represented in the bundle, the certificate verificatin prbably failed due t a prblem with the certificate (it might be expired, r the name might nt match the dmain name in the URL). If yu'd like t turn ff curl's verificatin f the certificate, use the -k (r --insecure) ptin Explanatin: The truststre certificate is wrng. Please verify the trustre: append.cer t the file name getrust.pem and pen the certificate with a duble click. Yu shuld see the issuer Equifax. Please change the name getrust.pem.cer after the test back t getrust.pem. <html> <head> <title>apache Tmcat/ Errr reprt</title> <style> <!-- H1 {fnt-family:tahma,arial,sans-serif;clr:white;backgrund-clr:#525d76;fntsize:22px;} H2 {fnt-family:tahma,arial,sans-serif;clr:white;backgrund-clr:#525d76;fntsize:16px;} H3 {fnt-family:tahma,arial,sans-serif;clr:white;backgrund-clr:#525d76;fntsize:14px;} BODY {fnt-family:tahma,arial,sans-serif;clr:black;backgrund-clr:white;} B {fnt-family:tahma,arial,sans-serif;clr:white;backgrund-clr:#525d76;} P {fnt-family:tahma,arial,sans-serif;backgrund:white;clr:black;fnt-size:12px;} A {clr : black;} A.name {clr : black;} HR {clr : #525D76;} --> </style>

73 </head> <bdy> <h1>http Status </h1> <HR size="1" nshade="nshade"> <p><b>type</b> Status reprt</p><p><b>message</b> <u></u></p><p><b>descriptin</b> <u>this request requires HTTP authenticatin ().</u></p> <HR size="1" nshade="nshade"> <h3>apache Tmcat/5.5.20</h3> </bdy> </html> Explanatin: Yur certificates are OK and accepted but yur passwrd r yur user is wrng.

74 Trubleshting - Lgin errr messages when using the Java Client java.i.ioexceptin: Keystre was tampered with, r passwrd was incrrect Explanatin: Yur keystre passwrd desn t fit t the keystre r the truststre passwrd t the truststre. Yu can check the passwrd with the keytl which is a cmpnent f the JDK. Yu can find it in the bin directry f the JDK. Fr testing the passwrd call c:\prgramme\java\jdk1.6.0_07\bin\keytl.exe -list -v -keystre <yur keystre r truststre> -strepass <yur keystre r truststre passwrd> javax.net.ssl.sslhandshakeexceptin: sun.security.validatr.validatrexceptin: N trusted certificate fund Explanatin: Yur truststre is wrng. Yu can inspect yur truststre with keytl, a cmpnent f the JDK. Call c:\prgramme\java\jdk1.6.0_07\bin\keytl.exe -list -v -keystre <yur truststre> -strepass <yur truststre passwrd> and yu must find the issuer Equifax OU=Equifax Secure Certificate Authrity, O=Equifax, C=US in the utput. Check the MD5 and SHA1 values t. <html> <head> <title>apache Tmcat/ Errr reprt</title> <style><!--h1 {fnt-family:tahma,arial,sansserif;clr:white;backgrund-clr:#525d76;fnt-size:22px;} H2 {fntfamily:tahma,arial,sans-serif;clr:white;backgrund-clr:#525d76;fntsize:16px;} H3 {fnt-family:tahma,arial,sans-serif;clr:white;backgrundclr:#525d76;fnt-size:14px;} BODY {fnt-family:tahma,arial,sansserif;clr:black;backgrund-clr:white;} B {fntfamily:tahma,arial,sans-serif;clr:white;backgrund-clr:#525d76;} P {fnt-family:tahma,arial,sans-serif;backgrund:white;clr:black;fntsize:12px;}a {clr : black;}a.name {clr : black;}hr {clr : #525D76;}-- ></style> </head> <bdy> <h1>http Status 401 -</h1> <HR size="1" nshade="nshade"> <p> <b>type</b> Status reprt </p> <p> <b>message</b> <u></u> </p> <p> <b>descriptin</b> <u>this request requires HTTP authenticatin ().</u> </p> <HR size="1" nshade="nshade"> <h3>apache Tmcat/5.5.20</h3>

75 </bdy> </html> Explanatin: Yur user id r passwrd is wrng.

76 2009 First Data. All rights reserved.