1. Introduction

Our e-Commerce is ideal to offer your customers online payments in your web shop. It is a combination of high versatility with minimum requirements:

  • It’s safe: Keep a low PCI profile by outsourcing the handling of sensitive data to our platform!
  • It’s flexible: Adapt our payment page using the countless possibilities for visual adaptation!
  • It’s customer-friendly: Let your customers choose any of our payment methods!

hpp-shortThe graph above graphic provides you a broad overview on the parties involved and their responsibilities in the payment process.

Before you process live transactions, feel free to use our test environment to learn our solution without costs or any commitments involved!

2. Get Started

To process transaction on our platform with e-Commerce, make sure that

  • You fulfil the mandatory PCI requirements
  • You have at least one payment method activated in your account (Check via Configuration > Payment methods)
  • Your webshop is hosted on a server that enables HTML forms notification
  • 3. Integrate with e-Commerce

    Our e-Commerce channel allows you to process transactions for all payment methods we offer. Check out here how it works and what you need to do.

    Understand payment flow

    HPP-longThe graphic above explains all the steps of a typical e-Commerce transaction

    1. Your customer goes to your check-out pages and finalises the purchase on your check-out page
    2. You send the payment request without credit card details to our e-Commerce endpoint-URL composed of a set of mandatory / recommended / optional parameters. By doing so, your customer is also redirected to our e-Commerce.
    • (Optional) We retrieve the template to adapt the look and feel of the e-Commerce
    1. Your customer enters her/his credit card details on our secure e-Commerce
    • (Optional) We perform a Fraud check thanks to our fraud offering tools.
    1. We redirect the customer to her/his issuing bank for 3-D Secure authentication
    2. The cardholder identifies herself/himself. Our system receives the result from the issuer
    3. Based on the result, two scenarios are possible
    • If the identification was unsuccessful, we redirect the card holder to the DECLINEURL, ending the flow. You receive the result via eCommerce mode feedback channels.
    • If the identification was successful, we submit the actual financial transaction to the acquirer to process the transaction
    1. We return the payment result to you. Depending on the acquirer’s result, we redirect the card holder to either the ACCEPTURL / DECLINEURL / EXCEPTIONURL. You receive the result via eCommerce mode feedback channels
    2. If the transaction was successful, you can deliver the goods / services

    Target endpoint URLs in test / live

    Our platform allows you to send requests for new transactions either to our Test environment or Live environment

    Endpoint URL TEST

    https://mdepayments.epdq.co.uk/ncol/test/orderstandard_utf8.asp

    Endpoint URL LIVE

    https://payments.epdq.co.uk/ncol/prod/orderstandard_utf8.asp

    For test transactions with no financial impact, use the TEST-URL. The transactions will be sent to our test environment thereby to your test account.


    For real transactions with financial impact, use the PRODUCTION-URL. The transactions will be sent to our live environment thereby to your live account.

    Make sure to switch to the LIVE-URL as soon as you have finalised your tests.

    Send transaction request

    Once your customer finalises the purchase on your check-out page for the actual payment, your server makes an HTTP POST or GET request.

    Send the request to the e-Commerce endpoint URL with a set of mandatory / recommended / optional and redirect your customer to this URL at the same time.

    A typical request looks like this:

    
    <form method="post" action="https://mdepayments.epdq.co.uk/ncol/test/orderstandard_utf8.asp" id=form1 name=form1>
    
    <!-- general parameters: see Form parameters -->
    <input type="hidden" name="PSPID" value="">
    <input type="hidden" name="ORDERID" value="">
    <input type="hidden" name="AMOUNT" value="">
    <input type="hidden" name="CURRENCY" value="">
    <input type="hidden" name="LANGUAGE" value="">
    <input type="hidden" name="CN" value="">
    <input type="hidden" name="EMAIL" value="">
    <input type="hidden" name="OWNERZIP" value="">
    <input type="hidden" name="OWNERADDRESS" value="">
    <input type="hidden" name="OWNERCTY" value="">
    <input type="hidden" name="OWNERTOWN" value="">
    <input type="hidden" name="OWNERTELNO" value="">
    
    <!-- check before the payment: see Security: Check before the payment -->
    <input type="hidden" name="SHASIGN" value="">
    <!-- layout information: see Look and feel of the payment page -->
    <input type="hidden" name="TITLE" value="">
    <input type="hidden" name="BGCOLOR" value="">
    <input type="hidden" name="TXTCOLOR" value="">
    <input type="hidden" name="TBLBGCOLOR" value="">
    <input type="hidden" name="TBLTXTCOLOR" value="">
    <input type="hidden" name="BUTTONBGCOLOR" value="">
    <input type="hidden" name="BUTTONTXTCOLOR" value="">
    <input type="hidden" name="LOGO" value="">
    <input type="hidden" name="FONTTYPE" value="">
    
    <!-- post payment redirection: see Transaction feedback to the customer -->
    <input type="hidden" name="ACCEPTURL" value="">
    <input type="hidden" name="DECLINEURL" value="">
    <input type="hidden" name="EXCEPTIONURL" value="">
    <input type="hidden" name="CANCELURL" value="">
    <input type="submit" value="" id=submit2 name=submit2>
    
    </form>
        

    Although our platform allows both GET and POST requests, we strongly recommend using POST. This will ensure a maximum of security during the payment process and no parameters are lost due to character length limitations for GET requests.

    Send mandatory / recommended / optional parameters

    You need to include a set of parameters for every transaction. Find detailed information (short description, format, maximum length and so on) for each parameter in our Parameter Cookbook.

    Have a look on the mandatory, recommended and optional parameters for a typical transaction request:

    Mandatory

    Parameter Description / Possible values 
    PSPID

    The name of your account on our platform to which you send the transaction request.

    ORDERID

    A unique order number for each request.

    The parameter ORDERID is used to check whether requests are accidentally sent twice to our platform.
    If two transactions with the same value for ORDERID are sent within 45 days, we will block the second transaction. This check applies only if the first transaction’s PAYIDSUB has reached one of the following statuses:

    2
    5

    Consequentially, an ORDERID can be used only once within 45 days. After that period, ORDERIDs already sent can be re-used

    AMOUNT

    Amount to be paid by your customer

    Multiply the amount by 100 as this parameter must not contain any decimals or other separators

    Example:

    If the order is 12,34 €, you need to send AMOUNT=1234

    CURRENCY

    Currency of the amount in ISO 4217 format (ie EUR, GBP etc.)

    LANGUAGE

    The language our e-Commerce is displayed to your customer.

    The value is a combination of ISO 639-1 (language) and ISO 3166-1 (country)

    Examples:

    en_US

    fr_FR

    Find a full list of all language we support in our Parameter Cookbook.

    SHASIGN

    Unique character string for order data validation. It is used to make sure that the transaction request is indeed from your server and has not been manipulated by an unauthorised third party.

     

    Learn here to learn how to construct it.

    Recommended

    EMAIL

    Your customer’s address / contact data

    OWNERADDRESS

    OWNERZIP

    OWNERTOWN

    OWNERCTY

    OWNERTELNO

    TP

    PMLISTTYPE

    Modify the look and feel of the e-Commerce

    Learn here how to do it

    Optional

    COMPLUS

    Fields to send any additional data you would like to receive in the transaction feedback

    Learn here to learn how to use them

    PARAMPLUS

    PM

    Make specific payment methods (un)available on the e-Commerce or redirect your customers directly to third-party payment method services (ie. Paypal, iDEAL etc.)

    Learn here how to use them

    BRAND

    PMLIST

    EXCLPMLIST

    CREDITDEBIT

    OPERATION

    Override the default operation code in your Back Office for each transaction 

    Learn here how to use it

    USERID

    Link transactions to a specific user in your data bases

    Learn here how to use it

    ACCEPTURL

    DECLINEURL 

    EXCEPTIONURL

    CANCELURL

    HOMEURL 

    CATALOGURL 

    BACKURL

    URLs to receive transaction feedback and to redirect your customers depending on the outcome

    Learn here to learn how to use them

    Calculate SHASIGN value

    An integral part of the transaction flow is to make sure that transactions sent to our platform are legitimate.

    To rule out that an unauthorised third party has manipulated any of your transaction request, we use a method that is both safe and easy for you to implement: by sending the parameter SHASIGN. The SHASIGN is a unique character string that can only be constructed by two parties: You and ePDQ.

    The string is based on data sent along with the transaction and security settings in your Back Office. These settings are only accessible to both you and ePDQ. For each transaction, our system will reconstruct the string sent in SHASIGN. If both strings match, our platform considers the transaction of legitimate origin and will process it.

    Construct the value for SHASIGN following these rules

    1. Concatenate all parameters / values to one string according to this formula

    Parameter name + = + parameter value + SHA-IN passphrase

    Make sure to

    • Use the SHA-IN passphrase as defined in your Back Office in Configuration > Technical Information > Checks for e-Commerce & Alias Gateway > SHA-IN pass phrase
    • Include all parameters (and only these) our system takes into account and to sort them alphabetically as defined in this list
    • Normalise the data (ie remove leading / trailing spaces)

    An example (using only mandatory parameters) looks like this:
    Parameters from the transaction request

    AMOUNT=1500 (15.00 x100)
    CURRENCY=EUR
    LANGUAGE=en_US
    ORDERID=1234
    PSPID=MyPSPID

      SHA-IN passphrase as defined in Back Office

      Mysecretsig1875!?

      Concatenated string:

      AMOUNT=1500Mysecretsig1875!?CURRENCY=EURMysecretsig1875!?LANGUAGE=en_USMysecretsig1875!?
      ORDERID=1234Mysecretsig1875!?PSPID=MyPSPIDMysecretsig1875!?

      2. Hash the concatenated string according to the selected hashing method in your Back Office in Configuration > Technical Information > Global security parameters > Hash algorithm

      Resulting digest (for SHA-1 method):

      F4CC376CD7A834D997B91598FA747825A238BE0A

      3. Send your transaction request including the digest in parameter SHASIGN

      Parameters from the transaction request

      AMOUNT=1500 (15.00 x100)
      CURRENCY=EUR
      LANGUAGE=en_US
      ORDERID=1234
      PSPID=MyPSPID

      SHASIGN=F4CC376CD7A834D997B91598FA747825A238BE0A

      As soon as we receive a transaction request, we recalculate the string according to the parameters you sent and the SHA-IN passphrase / Hash method as defined in your Back Office.

      If we get the same value you sent, we will redirect the customer to our e-Commerce, allowing your customer to enter her/his credit card details.

      If there is a mismatch, we redirect the customer to an error page, abandoning the transaction.

      For troubleshooting these kind of transactions, check the Back Office in Configuration > Error where we log these kind of transactions as “unknown order”. Our system will display there the SHASIGN you sent and the one our system constructed. This will help you amend your SHASIGN calculation. Our Troubleshooting guide contains more information on solving this issue.  

      • Do not include empty parameters in the concatenated string
      • Use upper case letters for parameter names
      • URL-decode the string-to-hash before you calculate the hash
      • All characters in the concatenated string must be in upper case
      • Although we support hashing methods SHA-1 / SHA-256 / SHA-512, we recommend using SHA-256 or SHA-512. This will provide maximum security for the verification process.
      • For extra safety, we request that you use different SHA passphrases in our Test environment and  Live environment

      Define Back Office settings

      To successfully process transactions, you also need to define some settings in your Back Office. They are in different tabs under Configuration > Technical information.   

      Have a look on the mandatory, recommended and optional settings

      Mandatory

      Back Office module  Description / function
      Global Security parameters > Hashing method > Hash algorithm Define the hashing method for the concatenated string to calculate the SHASIGN value
      Data and origin verification > Checks for e-Commerce & Alias Gateway > SHA-IN pass phrase Define the SHA-IN passphrase that is added to the concatenated string to calculate the SHASIGN value

      Recommended

      Back Office module  Description / function
      Global transaction parameters > Payment retry Attempts per transaction request you grant your customers to successfully finalise their payment. After the last try fails, the transaction reaches status 2.
      Global transaction parameters > Processing for individual transactions

      Our platform offers you to time the payment requests we send to our acquirers in three different ways. Select the one that fits business model best:

      • Always online (Immediate): We send the transaction right after we receive the request from you. If the acquirer is unavailable, the transaction reaches status 2. Appropriate for goods/services you need to deliver right after the purchase
      • Online but switch to offline when the online acquiring system is unavailable: ): We send the transaction right after we receive the request from you. If the acquirer is unavailable, we will try to recover it by resending it at a later time. Appropriate for goods/services for which a time gap between purchase and delivery is acceptable
      • Always offline (Scheduled): We send the transaction at specific cut-off times (around 4hrs after you have sent it). As your customer will not have to wait for the real-time result, the purchase is faster finalised than the other methods. Consequentially, both you and your customer receive a final transaction status with a delay of several hours. Appropriate for goods/services for which a time gap between purchase and delivery is acceptable
      Transaction feedback > eCommerce > HTTP redirection in the browser Define the URLs your customers are redirected to depending on the result. Learn more in our dedicated chapter.
      Transaction feedback > eCommerce > Direct HTTP server-to-server request Define the URLs and the timing when you wish to receive transaction feedback. Learn more in our dedicated chapter.
      Transaction feedback > eCommerce > Dynamic e-Commerce parameters Select the parameters you wish to be included in the transaction feedback. Learn more in our dedicated chapter.
      Transaction feedback > eCommerce > All transaction submission modes > Security for request parameters Define a SHA-OUT pass phrase to validate the transaction feedback’s origin. Learn more in our dedicated chapter.
      Transaction feedback > eCommerce > All transaction submission modes > HTTP request for status changes Define the URL and the timing when you wish to receive feedback for transactions status changes after the initial purchase. Learn more in our dedicated chapter.

      Optional

      Back Office module 

      Description / function

      Global transaction parameters > Default operation code

      Define whether our platform should process your transactions as authorisations (status 5) or direct sales (status 9) at the timing of the request. Learn more in our dedicated chapter

      Global transaction parameters > Default data capture (payment) procedure

      Define the method and the timing to capture status 5 transactions. Learn more in our dedicated chapter

      Payment page > Cancel button

      Make a button on our e-Commerce appear / disappear that allows your customers to abandon the transaction

      Payment page > Back button redirection

      Define the URL your customers are sent to when clicking on the “Back” button on our e-Commerce

      Payment page > General terms and conditions

      Make a link to your general terms and conditions appear on our e-Commerce

      Transaction e-mails > E-Mails to the merchant

      Define whether you wish to receive e-mails from our system for processed transactions. Learn more in our dedicated chapter

      Transaction e-mails > E-mails to the customer

      Define whether your customers should receive e-mails from our system for processed orders

      Learn more in our dedicated chapter

      4. Customise payment page look and feel

      Our platform allows you to adapt the look and feel of our e-Commerce to a great extent. Adapting the payment page to your corporate identity will encourage your customers to finalise their order after they are redirected to the e-Commerce.

      Learn here how to use this feature and the manifolds ways to enhance your customer’s payment experience.

      Using our platform to host templates will not change your PCI level. If you choose to host the template on your own, you might be required to fulfil a higher PCI level. Contact your acquirer for detailed information.

      Use ePDQ Responsive Payment Page template

      The easiest way to modify our e-Commerce is using our Responsive Payment Page template (RPP). It is perfect for a multi-screen online shopping experience for your customers. It ensures you an optimised conversion on both desktop and mobile devices.

      To give you an easy start and to learn about all its possibilities, we provide you with a complete demo template. Follow these steps to use it

        1. Download the zip file.
        2. Login to the Back Office. Go to Configuration > Template > Template selection > eCommerce payment page and click on “ACTIVATE”.
        3. Go to Configuration > Template > File Manager > Upload Template Files. Upload the whole content from the zip file. After a couple of minutes, our system has validated the files (In “Uploaded Files”, they appear as “Validated” in column “Status”). They are now ready to be used on our e-Commerce
        4. Go to Configuration > Template > Template selection > eCommerce payment page. Select the HTML file “ePDQResponsivePaymentPageTemplate_index.html” from the dropdown menu “Default merchant template”.

          • For our Responsive Payment Page template, you need to arrange the display of the payment methods in a vertical order. You can achieve this by sending the additional parameter PMLISTTYPE=2 for each transaction
          • We recommend that you limit the size of your logos to 300px for both width and height. This will ensure that the loading time on mobile devices is kept to a minimum

          Create individual Responsive Payment Page templates

          Our platform also allows you to modify the demo file completely at your liking and thereby create templates by yourself from scratch and to set up templates to be used based on specifics occasions, like Black Friday or End of Year seasons.

          Include these elements to do so:

          • HTML file: The basis for every template (just like “ePDQResponsivePaymentPageTemplate_index.html"from the demo file).
            The template page can be designed completely to your liking. The only requirement is that it must contain the placeholder string "$$$PAYMENT ZONE$$$":

          <html>$$$PAYMENT ZONE$$$</html>

          This placeholder is reserved space for the fields your customers enter their credit card data. You can modify the elements in this space by using a CSS file.
          You can include the following file types in your template: .css, .jpg, .jpeg, .gif, .png, .html, .js.
          Use “ $$$TP RESOURCES URL$$$/[your file name]” to reference them in the file.

          <html><head>        <link rel=”stylesheet” type=”text/css” href=”$$$TP RESOURCES URL$$$/yourFile.css”>        <script scr=”$$$TP RESOURCES URL$$$/test.js”></script></head><body><div>$$$PAYMENT ZONE$$$</div></body></html>

          Be sure to upload all references files in the Back Office via Configuration > Template > File Manager > Upload Template Files.

          Do not use BASE tags, frames or FORM tags to encapsulate the $$$PAYMENT ZONE$$$ string.

          CSS file: You can use style sheets to adapt both your elements in the HTML file and the reserved space for the fields your customers enter their credit card data. To adapt the latter, we have defined a class for the various elements in this space. You need to add the following block of code between the tags <head></head> and change the properties of those classes to fit to the look and feel of your site:

          <style type="text/css"><!--td.ncolh1 {background-color : #006600; color : yellow; font-family : verdana}td.ncoltxtl {background-color : #ffffcc; color : black; text-align : right; font-weight : bold}td.ncoltxtl2 {background-color : #ffffcc; color : black; text-align : right; font-weight : bold}td.ncoltxtr {background-color : #ffffcc; color : black; text-align : left; font-weight : bold}td.ncoltxtc {background-color : #ffffcc; color : black; text-align : center; font-weight : bold}td.ncolinput {background-color : #ffffcc; color : black}td.ncolline1 {background-color : #ffffff; color : black}td.ncolline2 {background-color : #ffffcc; color : black}
          input.ncol {background-color : #006600; color : white}td.ncollogoc {background-color : #ffffcc; color : black; text-align : center; font-weight : bold}table.ncoltable1 { background-color: #ffffcc; }table.ncoltable2 { background-color: #ffffcc; border-width : medium; border-color : green; }table.ncoltable3 { background-color: #ffffcc; }--></style>

          These screenshots of the payment selection screen, the payment form and the result page show which elements exactly you can modify with the properties.  

          As with the HTML file, you can reference files in your CSS. Instead of “ $$$TP RESOURCES URL$$$/[your file name]”, use simply "./[your file name]”

          • Make sure to stick to the established cascading style sheet syntax.
          • Test your CSS it in various browsers, as the way they handle style may differ

          Create mobile templates

          Although the Responsive Payment Page template is suitable for all devices, we also offer you specialised files to enhance the payment experience on mobile devices. Take a look at the branded one and the “stripped” version. You can download both here.

          The basis for both versions is a HTM file called “StandardMobileTemplate” and “StandardMobileTemplate_Generic” respectively.  Unlike the standard Responsive Payment Page template, it is a combination of an HTML and CSS file. The CSS properties are located as follows:

          Example screenshot Properties

          The header part of the payment page:

          https://shared.ecom-psp.com//v2/images/guides/e-commerce/e-com-adv_css_01.jpg?language_id=1

          .securedBG{background: #797979;}.secured{padding: 8px 20px 0px 40px;color: #ffffff;width: 235px;margin: 0 auto;background: url("lock.png") 5px no-repeat #797979;
          height: 30px;
          }- Order Summarytable.ncoltable1{width: 100%;margin: 0 auto;min-width: 300px !important;}td.ncoltxtl{font-family: open-sans ,Verdana,sans-serif;font-size: 14px;background-color:#ffffff;text-align : left !important;font-weight : bold !important;vertical-align:bottom;}td.ncoltxtr{text-align: left;font-weight: normal;font-family: open-sans ,Verdana,sans-serif;font-size: 14px;background-color:#ffffff;}

          The payment detail section the customers enter their credit card details:

          https://shared.ecom-psp.com/v2/images/guides/e-commerce/Group 18.svg?language_id=1

          td.ncolinput{text-align: left;font-weight: normal;font-size: 14px;font-family: open-sans ,Verdana,sans-serif;
          display: block;box-shadow: none !important;}input.ncol{background-color: #ffffff;height: 40px;font-size: 14px;text-align: center;padding: 0px;font-family: open-sans ,Verdana,sans-serif;margin: 0 35px 20px;border-bottom: 1px solid #999999;border-radius: 0px;-webkit-appearance: none !important;-webkit-border-radius: 0 !important;}td.ncoltxtl2{text-align: left;font-family: open-sans ,Verdana,sans-serif;white-space: nowrap;display: block;
          font-size: 14px;background-color:#ffffff;}

          The footer part of the payment page:

          https://shared.ecom-psp.com/v2/images/guides/e-commerce/Group 18.svg?language_id=1

          td.ncollogoc{text-align: center;font-weight: normal;font-size: 14px;padding: 2px;vertical-align: top !important;}td.ncollogoc IMG{width: 90px;height: 55px;margin-right: 4px;}.ncollogoc td .ncol{width: auto;padding-right: 10px;padding-left: 10px;cursor:pointer;}.ncollogoc input.ncol{margin-top:10px !important;-webkit-appearance: none !important;-webkit-border-radius: 0 !important;}

          The payment status page your customers are redirected after the validation of the credit card details:

          https://shared.ecom-psp.com/v2/images/guides/e-commerce/Group 18.svg?language_id=1

          td.ncoltxtc{background-color:#ffffff;color:#999999;padding: 0px;text-align: left;font-weight: normal;font-size: 14px;border-top: 0px solid #ffffff;font-family: open-sans ,Verdana,sans-serif;}td.ncoltxtc h3</code{text-align: center;font-weight: normal !important;padding: 5px;font-family: open-sans ,Verdana,sans-serif;}td.ncoltxtmessage{background-color: #ffffff;color: #999999;text-align: left;font-weight: normal;}

          Use multiple templates

          You can upload multiple templates to the Back Office and reference them for transactions individually.

          Per default, the template selected in the Back Office in Configuration > Template > Template selection > eCommerce payment page > from the dropdown menu “Default merchant template” will be used for every transaction. However, you can override this setting by sending an additional parameter with your transaction request

          Parameter Description / Possible values
          TP

          By sending the file name of any of your HTML files uploaded in the Back Office (Configuration > Template > File Manager > Uploaded files), you can select a specific template for the transaction

          Example: “myTemplate.html”


          Use Dynamic template

          Our platform also allows you to adapt our e-Commerce by hosting a template on your own server.

          Creating the HTML/CSS follows the same process as described in the previous chapter. However, as you do not upload the template in the Back Office but host it on your own, some differences apply

          • To instruct our system to load the template from your server, you must send an additional parameter for all of your transaction requests:

          Parameter

          Description / Possible values

          TP

          The URL of the dynamic template page

          The URL must be absolute (contain the full path) and cannot be relative.

          Do not specify any ports in your URL, we only accept ports 443 and 80.

          Any component included in the template page must also have an absolute URL.

           

          • Although you can use the same template page for all orders (or vary it by sending parameter TP), your application can generate it dynamically according to the order parameters. To achieve this, use a fixed template URL returning a result derived from the order number. Our system adds the main payment data – including the merchant’s order reference number – when it retrieves the template page:

          HTTP request = url_page_template?ORDERID=...&AMOUNT=...&CURRENCY=…

          • If you choose to host the template on your own, you might be required to fulfil a higher PCI level. Contact your acquirer for detailed information
          • As loading the template from your server takes more time to load from our own, the overall payment process takes longer. Our system is configured with a 5-second time-out for the request to retrieve the dynamic template. Contact our support team to change the duration of the time-out.
          • If one of your elements used in the dynamic template page is not hosted on a secure server, most browsers will not recognise the connection to our platform as secure. Therefore, we strongly encourage you to host all your files on a secure server

          Enable template security control

          To protect your customers from fraud, we have established several security checks for the template.

          Login to the Back Office and go to Configuration > Template > Advanced configuration. You can adapt the following settings

          • Go to Global > Enable JavaScript check on template
            When activated, our platform checks whether JavaScript is used on the template page. If JavaScript is detected, we will block the template and use a default template instead
          • Dynamic template 

          If you select “Yes” for “Allow usage of dynamic template”, you need to configure one or more trusted website name(s) hosting the dynamic template. If you enter multiple ones, separate them by semicolon (“;”). Make sure to add the full URL domain path (sub directories where the template is located can be left out).
          For each transaction, our system compares the value sent in parameter TP with the website names configured in the Back Office. In case of a mismatch, we block the dynamic template and load a template you have uploaded in the Back Office instead. If you have not uploaded any template, our system will load a default template instead.  

          https://shared.ecom-psp.com//v2/images/guides/e-commerce/e-com-adv_css_01.jpg?language_id=1

          5. Redirect customer after purchase

          After your customer has entered her/his credit card details, we send the data to the acquirer for validation. Once we receive the result, we redirect your customer on a page of your choice.

          For each scenario, you can define a separate URL. Calculate SHASIGN value

          You have two options to define these URLs:

          1. Via the Back Office: Go to Configuration > Technical Information > Transaction feedback > eCommerce > HTTP redirection in the browser.Enter a URL in the field for the respective scenario:

          Field

          Description

          Accepturl

          Successful transactions (status 5, 41 or 9)

          Declineurl

          Declined transactions (status 2)

          Exceptionurl

          Cancelled transactions (status 1)

          Cancelurl

          Transactions with an uncertain result (status 51 or 92)

          2. Send the following additional parameters for every transaction request:

          Parameter

          Description / Possible values

          ACCEPTURL

          Successful transactions (status 5, 41 or 9)

          DECLINEURL

          Declined transactions (status 2)

          CANCELURL

          Cancelled transactions (status 1)

          EXCEPTIONURL

          Transactions with an uncertain result (status 51 or 92)

          • If you have defined URLs as described in option 1. and also send values for the parameters as described in option 2., the URLs in the Back Office will be overwritten by the parameter values.
          • If any of your URLs does not comply with the HTTPS protocol but with the HTTP protocol only, your customer might get a browser alert about entering a non-secure environment. For such cases, we can display a notification to your customers right before the redirection takes place. Activate it in the Back Office via Configuration > Technical Information > Transaction feedback > eCommerce > HTTP redirection in the browser by flagging “I would like Ingenico to display a short text to the customer on the secure payment page if a redirection to my website is detected immediately after the payment process.”
          • If any of your server-to-server feedback URLs (as configured in your account under Configuration > Technical Information > Transaction Feedback > Direct HTTP server-to-server request) replies with a text, plain HTML code or a HTTP 302 redirection command, our system will show the page as-is to your customer. Neither of the redirection URLs (ACCEPTURL etc.) will be shown to your customers.

          If you choose neither of the options, we redirect your customers to one of our generic result pages instead. The pages will state the result in the respective language you have sent with parameter LANGUAGE (ie. “Authorised” for status 5).

          You can add a catalogue and / or home URL on our result page you can redirect your customer to.  This requires you to send the following parameters along with the transaction request

          Parameter

          Description / Possible values

          CATALOGURL

          URL of your catalogue

           

          If sent, a “Back to our catalouge” button will be visible on our generic result page

          HOMEURL

          URL of your home page

           

          If sent, a “Back to merchant site” button will be visible on our generic result page

           

          Can also be defined in the Back Office via Configuration > Technical Information > Payment page > Back button redirection, but will be overwritten if you send this parameter

          If you send the value "NONE", the button is not displayed

          6. Get transaction feedback

          To keep track of the transaction results, our platform offers multiple ways to send feedback to your server. You can use this information to access the transaction at a later point to perform maintenance operations (i.e. a refund) at a later point.

          Select feedback parameters

          Depending on your database’s requirements, you can define exactly what kind of information you want to receive. As we send the feedback by individual parameters, you can select them freely in the Back Office:

          • Go to Configuration > Technical Information > Transaction feedback > eCommerce > Dynamic e-Commerce parameters
          • Move the parameters you would like to receive in the feedback from the “Available” box to the “Selected” box. The following parameters will always be included in the feedback and cannot be deselected:

          NCERROR

          PAYID

          ORDERID

          STATUS

          Calculate SHASIGN value for feedback requests

          In the same way we validate requests from your server, you can also validate the origin of our feedback.

          To ensure that the received feedback is legitimate and not an intrusion from a third party, we offer you to send a digest based on the parameters sent in the feedback. By recalculating this digest based on these parameters on your own, you can easily verify the legitimacy of the feedback.

          The way this digest is calculated follows the same principle as described in this chapter. As some differences apply, have a look at the following summary of all steps:

          1. The feedback your server receives includes a parameter called SHASIGN, containing the digest

          To recalculate the digest, concatenate all parameters / values to one string according to the formula

          Parameter name + = + parameter value + SHA-OUT pass phrase

          Make sure to

          • Use the SHA-OUT pass phrase as defined in your Back Office in Configuration > Technical Information > Transaction feedback > All transaction submission modes > SHA-OUT pass phrase
          • Include all parameters (and only these) our system takes into account and to sort them alphabetically as defined in this separate SHA-OUT parameter list

          1. Hash the concatenated string according to the selected hashing method in your Back Office in Configuration > Technical Information > Global security parameters > Hash algorithm

          2. Compare you digest with the one you received from us. If you have a match, you have the confirmation that the received feedback is legitimate
          • This feature is optional, as the server request is a closed loop with additional security layers (TLS / HTTPS / IP filters on your server - please check our Firewall documentation for that)
          • If you still want to use this feature, make sure to configure a SHA-OUT pass phrase. Otherwise, we will not send a digest in the feedback

          Get feedback

          After you have selected the feedback parameters and defined a SHA-OUT, you are ready to receive feedback. Our platform offers you two ways:

          1. Receive feedback on redirection URLs: As soon as your customers end up on one of these URLs, we send a GET request accordingly. To use this option, set the following flag in Configuration > Technical Information > Transaction feedback > eCommerce > HTTP redirection in the browser:

          This option will only work if your customers close their browser after the redirection is completed. To be independent of your customers’ behaviour, we offer a second option as described below

           2. Receive server-to-server feedback: You can define separate URLs and a choose a time spot to receive the feedback. To use this option, go to Configuration > Technical Information > Transaction feedback > eCommerce > Direct HTTP server-to-server request. Define the following:

          Timing of the request

          • Always deferred (not immediately after the payment).
          • Online
          • Online but switch to a deferred request when the online requests fail.

          Get feedback either

          • 10 minutes after the purchase
          • Right after the purchase
          • Right after the purchase or 10 minutes after the purchase should the initial feedback transfer fail

          If the payment's status is "accepted", "on hold" or "uncertain".

          Get feedback for transactions that end up in status 5 / 9 or 51 / 91 on an URL of your choice

          If the payment's status is "cancelled by the client" or "too many rejections by the acquirer".

          Get feedback for transactions that end up in status 1 or 2 on an URL of your choice

          Request method

          Get feedback as GET or POST

           

          • To ensure that your server accepts our feedback, make sure to set up your firewall correctly
          • For timing options “Always deferred” and “Online but switch to a deferred request […]” our platform will try four times to send you the feedback should we be unable to send the feedback in the first place
          • For security reasons, we recommend selecting POST over GET

          Get feedback for subsequent status changes

          In some cases, your transactions’ status will change at a later point after the initial purchase. To get feedback for these so-called “offline” status changes, go to Configuration > Technical Information > Transaction feedback > All transaction submission modes > HTTP request for status change. Define the following:

          Timing of the request

          • Only at the time of the order authorisation request
          • For each offline status change (payment, cancellation, etc.).

          Get feedback either

          5 / 51 / 52

          91 / 92

          61 / 62

          81 / 82

          91 / 92

          URL on which the merchant wishes to receive a deferred HTTP request, should the status of a transaction change offline.

          Get the feedback on an URL of your choice

          Resend feedback

          In some cases, a redirection / feedback request is not performed properly. This can happen i.e. if your customers click on the back button in their browser. To avoid confusion on your customers’ side and to ensure you get the feedback after all, flag go to Configuration > Technical Information > Transaction feedback > General  and flag “I would like Ingenico to re-launch the "end of transaction" (post-payment request/redirection) process if required.” This will ensure that

          • Your customers ends up on the proper redirection URL after the purchase
          • You receive the feedback on your URLs

          7. Secure payment with 3-D Secure

          An important part of the transaction processing flow for your customer is the 3-D Secure (3DS). There is no effort for you involved, except having 3DS active on all your card payment methods, and we will take care of everything necessary.

          If you’re looking to make use of 3D Secure on the test environment, be sure to check the following link to ensure that it’s enabled and active on your test or trial PSPID.

          Following the introduction of 3DSv2, new rules apply. Although we collect all relevant data for you during the payment process, you can still make the 3DSv2 approach to risk evaluation more effective. You can achieve this by sending additional parameters along with the transaction.

          Have a look on the recommended and optional parameters for a typical transaction request. These parameters need to be included in the SHA-calculation.

          PSD2 enhances the transparency of the payment process for you and your customers. This is especially helpful when dealing with status 2 transactions.
          Our feedback parameter CH_AUTHENTICATION_INFO provides you with detailed information from the issuers when they reject your customers' transactions.
          Share this information with your customers to help them understand why their bank declined their transaction.

          To receive CH_AUTHENTICATION_INFO in your redirection URLs, select this parameter in the Back Office via Configuration > Technical information > Transaction feedback > Dynamic e-Commerce parameters. This will also ensure that this information is visible in the transaction overview via Operations > View transactions / Financial history.
          As you will not receive the information early enough to modify your redirection URLs accordingly once a transaction is finalised, we recommend flagging "I would like ePDQ to display a short text to the customer on the secure payment page if a redirection to my website is detected immediately after the payment process." in the Back Office via Configuration > Technical information > Transaction feedback > eCommerce > HTTP redirection in the browser. Our platform will then redirect your customers to our intermediate result page showing the information before your customers end up on your redirection URLs eventually.

          Note that not all issuers share information about why they decline transactions. Therefore, in some cases, CH_AUTHENTICATION_INFO is empty.

          Use the following card numbers in our Test environment to simulate an issuer response:
          Amex: 349586710563469
          MasterCard: 5111823134937549
          Visa: 4010759044222272

          7.1 Exclusions and exemptions for 3DSv2

          Some transactions are excluded from PSD2. If any of your transactions are among them, 3-D Secure will not be rolled out. This also applies to recurring transaction that you initiate. To mark these so-called merchant-initiated transactions (MIT) as such, you need to send additional parameters to our platform.

          You can request to omit 3-D Secure either during


          Choose only one of the ways when requesting transactions, as they are mutually exclusive.

          Frictionless / challenge flow and indication of preferred flow

          You can enhance the chance of skipping SCA (resulting in a frictionless flow) by sending the following parameter.
          Depending on your assessment of the risk of fraud, you may send specific values (i.e. for low risk assessment: 02, for an increased risk of fraud: 03.

          The below parameters are Mandatory (in case for a preference for a specific flow).

          Parameter
          Values
          Mpi.threeDSRequestorChallengeIndicator

          Length: 2 characters
          Data Type: String
          Values accepted:

          • 01 = No preference
          • 02 = No challenge requested
          • 03 = Challenge requested: merchant Preference
          • 04 = Challenge requested: Mandate
          • 05 = No Challenge Requested [transactional risk analysis is already performed]
          • 06 = No Challenge Requested [Data share only]
          • 07 = No Challenge Requested [SCA is already
            Performed]
          • 80-99 = Reserved for DS use

          You can even increase the chance of a frictionless flow and a higher conversion rate by sending more optional parameters.

          Exemptions of 3DS

          To skip 3-D secure altogether, send the following parameters:

          Parameter
          Values
          FLAG3D N = Skip the 3DS authentication process
          3DS_EXEMPTION_INDICATOR

          03 = Issuer TRA*
          04 = Low amount exemption
          05 = Merchant/Acquirer TRA*
          08 = Delayed Shipment

          * Transaction risk analysis

          However, it is still up to the issuer whether an authentication process must take place. In case the issuer insists on 3DS, the transaction will be declined.

          Important

          Transactions for which 3-D Secure should be skipped can only be processed as authorisations (which will end up in status 5 if they are successful). To receive the funds for these transactions, you will have to capture them at a later point. Successfully captured transaction will reach status 9.

          7.2 Test cards

          You can use the following test card to simulate a 3-D Secure registered card in our test environment:

          Frictionless Flow
          Brand Card number Expiry date
          VISA 4186455175836497 Any date in the future
          Mastercard 5137009801943438 Any date in the future
          American Express 375418081197346 Any date in the future
          Carte Bancaire 4150557357382737 Any date in the future

          Challenge Flow
          Brand Card number Expiry date
          VISA 4874970686672022 Any date in the future
          Mastercard 5130257474533310 Any date in the future
          American Express 379764422997381 Any date in the future
          Carte Bancaire 4150550997933993 Any date in the future

          More test cards numbers can be downloaded here.

          8. Use additional possibilities

          Our e-Commerce offers many more features. They make this solution even more adaptable to your individual needs and offer you additional possibilities to make your business thrive.

          Process transactions via Alias Manager

          As with all our solutions, you can use our Alias Manager to create, store and update card data with e-Commerce. Check out our dedicated chapter to make your customer journey even more conventient and seamless!

          Receive and send e-mails for orders

          Our system can send order confirmation emails to both you and your customers once a payment has been finalised. To use this option, go to Configuration > Technical Information > Transaction e-mails > E-mails to the merchant / E-mails to the customer. Make the following selection

            • E-mails to the merchant

            E-mail address(es) for transaction-related e-mails

            Your email address(es) to which the e-mails are sent to.

            Receive transaction confirmation e-mails

            • Yes, but only for e-Commerce transactions.
            • Yes, for all transaction submission modes.

            Get e-mails for transactions you process via

            • e-Commerce

            Receive e-mails in the event of offline transaction status changes

            • Yes, but only at the time of the order authorisation request.
            • Yes, for each offline status change (payment, cancellation, etc.).

            Get e-mails

            5 / 51 / 52
            91 / 92
            61 / 62
            81 / 82
            91 / 92

             

            • E-mails to the customer

            Support E-mail address to include in transaction-related e-mails

            Include your email address in the e-mail

            Support Phone number to include in transaction-related e-mails

            Include your phone number in the e-mail

            • I would like Ingenico to send a transaction confirmation e-mail to the customer.
            • I would like Ingenico to send a transaction confirmation e-mail to the customer at the time of the capture.
            • I would like Ingenico to send a transaction confirmation e-mail to the customer at the time of the refund.

            You customers receive emails for transactions that receive

            Send payment link via e-mail

            Instead of redirecting your customers to our payment page in real-time, you can let your customers choose to enter their credit card data anytime they want!

            As our platform accepts payment requests in both POST/GET mode, you can achieve this by sending your customers an e-mail, containing either the request as

            • POST: an HTML form with hidden HTML fields to send us the necessary parameters
              This HTML form works in the same way as shown in our example for your webshop checkout page

            • GET: a link consisting of the endpoint and the necessary parameters added to it:
              https://mdepayments.epdq.co.uk/ncol/test/orderstandard.asp / orderstandard_utf8.asp?PSPID=TESTSTD&OrderID=order123&amount=12500¤cy=EUR&SHASIGN=8DDF4795640EB9FE9B367315C48E47338129A4F5& …

            In both cases, your customers end up on our secure payment page as described in step 2 in our payment flow overview, starting the payment flow at that point.

            • Include parameter SHASIGN in the HTML form/link as you do with any other payment request
            • Leave field "URL of the merchant page containing the payment form that will call the page: orderstandard.asp" (Technical information > Data and origin verification > Checks for e-Commerce & Alias Gateway) empty in your PSPID the request is sent to (parameter PSPID). Otherwise, our platform rejects the request with an "unknown order/1/r/” error message

            Preselect payment methods available on eCommerce

            By default, our platform will display all payment methods on the e-Commerce that are active in your Back Office (Configuration > Payment methods). Sending one or more of the following parameters along with your transaction requests defines the list of available payment methods on the payment selection screen.

            Find detailed information (short description, format, maximum length and so on) for each parameter in our Parameter Cookbook.

            Parameter

            Description / Possible values

            PM

            Payment method (ie. Visa) or payment method group (ie. credit cards)

            • To display only one specific payment method on the e-Commerce, send this parameter together with the according value for BRAND:

              PM=CreditCard
              BRAND=VISA

              If the payment method belongs to a third-party payment method services (ie. Paypal, iDEAL etc.), we will redirect your customer directly to the respective homepage, omitting a redirection to our e-Commerce
            • To display a payment method group (ie. credit cards), send only this parameter:

              PM=CreditCard

            Find a list of all accepted values.

            BRAND

            Specifies the payment method brand (ie. VISA) from the payment method group (ie. credit cards) as defined by PM

            Find a list of all accepted values.

            PMLIST

            Define a list of available payment methods on the e-Commerce. Combine multiple values of parameter PM (separate them by  a “;” (semicolon)):

            PMLIST=VISA;iDEAL

            Find a list of all accepted values for parameter PM.

            EXCLPMLIST

            Define a list of payment methods that should not be available on e-Commerce
            Combine multiple values of parameter PM (separate them by  a “;” (semicolon))

            EXCLPMLIST= VISA;iDEAL

            Find a list of all accepted values for parameter PM.

            CREDITDEBIT

            Split payment methods Visa and MasterCard as separate credit and debit payment methods.

            This allows your customers to choose either of them by sending it along PM / BRAND:

            • C: offer payment method as credit card
            • D: offer payment method as debit card

            PM=CreditCard

            BRAND=VISA

            CREDITDEBIT=C

            Display e-Commerce in iframe

            Iframes allow you to integrate the e-Commerce on your website, while maintaining your own URL in the browser. This gives your customers the illusion of staying in your environment for during the whole payment process.

            However, due to its limitations, we do not recommend using this feature for various reasons

            • If your URL works with HTTP protocol only, the padlock icon will not appear in your customer’s browser. This may cause your customers doubt the security of the payment page
            • Third-party payment method services (ie. Paypal, iDEAL etc.) will not work well with iframes, causing poor layout results during the payment process

            Instead of iframes we suggest using the established possibilities to adapt the look and feel of the e-Commerce or integrating via FlexCheckout.

            If you still want to use iframes, make sure to

            • Use them only on the payment method selection screen
            • Use pop-ups for external payment methods whenever possible, to ensure the visibility of third-party web applications

            Get extra data in transaction feedback

            On top the feedback parameters you can choose in the Back Office, you can define you own parameters that should be included in the feedback. These are pass-through parameters you send in the transaction request and that are identically sent in the feedback. Use the following parameters to use this feature:

            Parameter

            Description / Possible values

            COMPLUS

            Pass a value within this parameter you would like to receive in the feedback

            Sending COMPLUS=1234 would be sent in the feedback like this:

            https://www.yourwebsite.com/acceptpage.asp?[…standard.parameters…]&COMPLUS=1234 […standard.parameters…]

            PARAMPLUS

            Pass both parameter names and values you would like to receive in the feedback

            Sending PARAMPLUS=SessionID=126548354&ShopperID=73541312 would be sent in the feedback like this:

            https://www.yourwebsite.com/acceptpage.asp?[…standard.parameters…]&

            SessionID=126548354&ShopperID=73541312

            Use variable transaction feedback URLs

            If you have multiple shops, you can adapt the feedback URL in the Back Office for each transaction individually.

            To do so, take care of the following:

            • In the Back Office, go to Configuration > Technical Information > Transaction feedback > eCommerce > Direct HTTP server-to-server request. Add the placeholder “<Paramvar>” for the part of the URL you want to change on transaction level.


            Example:
            https://www.yourwebsite.com/<PARAMVAR>/yourpage.asp

            • In your transaction request, send for parameter PARAMVAR the value that will fill for the placeholder “<Paramvar>”

              Example:
              For PARAMVAR=shop1, the feedback for this transaction would be sent to
              https://www.yourwebsite.com/shop1/yourpage.asp

            Define operation code per transaction

            Per default, our platform processes every transaction request as an authorisation (status 5) or direct sales (status 9). You can override this Default operation code for each transaction individually with the additional parameter OPERATION. This enables you to decide from case to case whether you want to request an authorisation or a direct sale:

            Parameter

            Description / Possible values

            OPERATION

            Send for each transaction to override the Back Office configuration

            Accepted values:

             

            Link transactions to user

            If you have multiple employees working with your Back Office and your web shop, you might want to register transactions associated with a specific user (ie. call center agents creating transactions via the payment link feature). You can achieve this by sending the following parameter:

            Parameter

            Description / Possible values

            USERID

            The name of the user as defined in your Back Office (Configuration > Users)

            In the transaction overview (Operations > View transactions / Financial History), the creator of the transaction is named by the formula “UserID/PSPID/User type”.

            If the USERID does not exist, we will replace it by the default USERID of the account (your PSPID)