Wirecard CEE Integration Documentation

Transcription

1 Created on: :53 by Wirecard CEE Integration Documentation () Created: :53 Online Guides Integration documentation 1/7

2 Created on: :53 by Integration Guide Overview To start integrating the payment process in your online shop you only need to add an HTMLform with some specific field names and values to your web page displaying the order details of your consumer. By submitting the form, and thus submitting the defined values, your consumer is forwarded to Wirecard Checkout Page. On Wirecard Checkout Page a web page from our Wirecard Checkout Server is shown to your consumer containing an HTMLform where entering of sensitive financial data is possible in a secure manner. After entering these data, your consumer commits the payment and Wirecard Checkout Page handles the entire communication with the financial service provider. After the payment process on the part of the financial service provider is completed, Wirecard Checkout Page informs your online shop about the result of the payment and forwards the consumer to a specific URL in your online shop which depends on the result of the payment process. Your online shop and your web server do not need to be PCIcompliant because all financial issues are handled by Wirecard Checkout Page which is hosted on the Wirecard Checkout Server and is itself PCIcompliant and certified for managing and storing sensitive financial data of your consumers like credit card numbers. There are four possible results which can be returned from Wirecard Checkout Page to your online shop: State Description SUCCESS The payment process has been successfully completed by your consumer. CANCEL The payment process has been canceled by your consumer. FAILURE The payment process has not been finished successfully by your consumer. PENDING The result of the payment process has yet to be determined. Typically occurs on payment methods requiring additional checks or actions by financial service providers or your consumer. When Wirecard retrieves updated information from the financial service provider, either a success or a failure is sent to your online shop. Please be aware that the state pending is only used if the request parameter pendingurl is used. Online Guides Integration documentation 2/7

3 Created on: :53 by For each possible result state a corresponding URL on your web server is called by the Wirecard Checkout Server. These URLs are defined in the HTML form when starting the payment process. Your consumer is redirected to the corresponding URL depending on the result of the payment process. Additionally, Wirecard sends the result of the payment process to the confirmurl. Therefore it is required that your production or test web server is accessible from the Internet. The integration example below is not fully functional on your local host which is typically not accessible from the Internet due to routers, firewalls and security restrictions! A graphical overview of the communication between your online shop and Wirecard Checkout Page from a technical point of view is shown below. Starting the payment process The payment process can be initiated in your online shop by adding an HTMLform to the page you want to start the payment process from. This form consists of a request with required parameters, such as customerid, language, amount, currency, and optional parameters, e.g. confirmurl, ordernumber, customerstatement. These parameters are hidden and not presented to your consumer in your online shop. For all possible request parameters please refer to Request Parameters. Online Guides Integration documentation 3/7

4 Created on: :53 by All parameters are sent as a POST request to the URL The following example can be copied into an html file. When opened in a browser, Wirecard Checkout Page opens on clicking submit. Only the payment process results will not be sent as the URLs are not valid. <form action=' method='post' name='checkout' target='_self'> <input type='hidden' name='customerid' value='d200001' /> <input type='hidden' name='language' value='en' /> <input type='hidden' name='paymenttype' value='select' /> <input type='hidden' name='amount' value='39.90' /> <input type='hidden' name='currency' value='eur' /> <input type='hidden' name='orderdescription' value='order ' /> <input type='hidden' name='successurl' value= ' /> <input type='hidden' name='cancelurl' value= ' /> <input type='hidden' name='failureurl' value= ' /> <input type='hidden' name='pendingurl' value= ' /> <input type='hidden' name='confirmurl' value= ' /> <input type='hidden' name='serviceurl' value= ' /> <input type='hidden' name='displaytext' value='thank you very much for your order.' /> <input type='hidden' name='imageurl' value= ' /> <input type='hidden' name='requestfingerprintorder' value= 'customerid,language,amount,currency,orderdescription,paymenttype,successurl, cancelurl,failureurl,pendingurl,confirmurl,serviceurl,displaytext,imageurl,r equestfingerprintorder,secret' /> <input type='hidden' name='requestfingerprint' value= 'C B27DD42323BF46F123F AA9A0BD E17A057D4751D9767B3F CF74547AAD16C7BDB32FF15970E5D0F640EE58931ADEE7AFC' /> <input type='hidden' name='windowname' value='' /> <input type='submit' name='submit' value='start Checkout'> </form> A fully functional example to run on your server is available as example code on GitHub. Please configure your firewall settings for sending data from your server to checkout.wirecard.com ( :443) correspondingly. Demo and test mode Online Guides Integration documentation 4/7

5 Created on: :53 by For data to test your integration, i.e. demo values for payment method specific values, please refer to demo mode and test mode. Receiving the payment process result Wirecard Checkout Page informs your online shop about the result of your consumers payment by calling one of the URLs you provided when starting the payment process. The call includes values which can be used for further processing. The payment process can result in one of four possible states as described above: Success, Cancel, Failure or Pending. For each state, the corresponding specific URL is called and Wirecard Checkout Page submits return parameters in a POST request to the corresponding URL. Please visit Response Parameters for a detailed description of the parameters you receive which may vary depending on the payment method. Additionally, if the optional request parameter confirmurl is set, Wirecard Checkout Page calls the given URL with a 30 second timeout using the same return values as for successurl, cancelurl, failureurl or pendingurl. If for any reason your server is not reachable at the moment, the confirmation can be sent again at a later time. Please contact our support teams to enable this feature. If you did not set the optional request parameter confirmurl but instead the optional parameter confirmmail, you receive an regarding the result of the payment. Please contact our sales teams to enable this feature. If you set neither the confirmurl nor confirmmail you may not be informed about the result of the payment process if your consumer closes the browser window prematurely! Optionally you have the possibility to get an for each transaction irrespective of the parameters confirmurl or confirmmail. Please contact our sales teams to enable this feature. If your consumer does not finish the payment process within a time frame of 30 minutes, we check if the payment has been successfully completed. If the result of the check is a successful payment, a success notification is sent to the URL set in the request parameter confirmurl. If the payment is not successful a failure notification is sent to the same URL instead. Therefore we strongly recommend setting the confirmurl! Checking if returned values are valid To check the authenticity of the return values sent from the Wirecard Checkout Server to your online shop, compare the responsefingerprint with an hash of the return values. Create a string by concatenating all returned parameters based on the order in the return parameter responsefingerprintorder. Then hash the string with an HMACSHA512 algorithm using the secret as cryptographic key and compare the result with the value of the return parameter responsefingerprint. If both values are identical, the response is authentic, i.e. the confirmation Online Guides Integration documentation 5/7

6 Created on: :53 by was indeed sent by Wirecard. If these values are not identical, recheck the calculation and consider that someone compromised the return values or has sent a possibly false confirmation for the payment. Therefore, do not trust these return values and do not assume that the payment was made even if it appears that way to you! In order to ensure a secure communication it is essential that you never disclose or share your secret with persons who are not involved in developing the online shop! Also, never forward the secret via unsecured communication channels e.g. mail, , fax or instant messaging. When the secret is submitted by fax make sure that the contents of the fax is disclosed only to authorized persons! If you suspect that your secret is known to unauthorized persons contact our support teams immediately to request a new secret! Storing the payment process result To ensure a persistent storage of all data relevant to the payment process of your consumers, it is strongly recommended to save all relevant data either in a file or in a database. Payment related data Please note that connection problems, technical issues on your web server or any issues at your consumer may result in a loss of sessionrelated information regarding your consumer, e.g. the content of the shopping cart or an already generated unique order number for a specific order. Especially if the consumer successfully finished the payment process it may not be possible to correlate the sessionrelated information regarding the order details to the successful payment of your consumer. To prevent such situations we strongly recommend that you store all sessionrelated information during the overall payment process persistently, e.g. in a file or a database. Also use the possibility of custom parameters to pass a unique ID corresponding to a payment process to Wirecard Checkout Page. All of your custom parameters are returned to your online shop as return values after the payment process has been finished. Return values To be able to identify each payment of your consumers at a later time and to correlate them to the corresponding session and order, store all return values of Wirecard Checkout Page in relation to that session and order. This is required to ensure a welldefined relation between the session data, the order of your consumer and the results of the payment process. Therefore, save all return values after the payment process or at least the returned order number you received by Wirecard Checkout Page via successurl, cancelurl, failureurl, pendingurl or the confirmurl. Also ensure that you can relate the values to the data you saved before starting Online Guides Integration documentation 6/7

7 Created on: :53 by Wirecard Checkout Page. Displaying the payment process result to consumers At the end of each payment process, Wirecard Checkout Page calls, if provided, the confirmurl and then forwards your consumer to one of the URLs you defined via the request parameters successurl, cancelurl, pendingurl or failureurl. Best Practices Before starting a payment process and in order to avoid pitfalls ensure that the following issues are fulfilled: Save all relevant data regarding the payment process in a persistent manner, e.g. in a file or a database, including all request parameter values. In the required request parameter orderdescription set a unique ID regarding the session of your consumer. This can be a sessionid, an order number or a debit number. The response parameters are validated via the fingerprint and you are alerted to any failed validations. Wirecard Checkout Journal To check your integration of Wirecard Checkout Page you may use Wirecard Checkout Journal as a debugging tool which gives you an overview of your transaction details when doing a checkout. Note that due to data protection regulations no test mode transactions are possible. Please enter the username and password you receive from Wirecard to have access to all transactions regarding your specific customerid. Wirecard Checkout Journal URL Online Guides Integration documentation 7/7