1. Introduction

Our e-Commerce is the ideal solution to offer your customers online payments in your web shop. It is a combination of high versality 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 from any payment method our platform supports!

The 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! Once you want to go live, check out here how to get a production account or contact us!

2. Get Started

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

  • You have a on our platform
  • 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. If you do not wish to develop software on you own, check out our Plugins and extensions. Any of these full-fledged solutions will help get started quickly! 

3. Integrate with e-Commerce

·       Do not include empty parameters in the concatenated string

·       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

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

The 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.

2’ (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
    1. ’ (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

classic.urltestorderstandard_utf8.asp

Endpoint URL LIVE

classic.urlprodorderstandard_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="classic.urltestorderstandard_utf8.asp" id=form1 name=form1><!—Mandatory / recommended / optional 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="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=""><input type="hidden" name="SHASIGN" value=""><!—Layout customisation --><input type="hidden" name="TP" value="template.html"><!—Customer redirection / Get transaction feedback --><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 / category
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

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.

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 to learn 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 Ingenico.

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 Ingenico. 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
    • 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.

    Have a look at all our payment page recommendation to optimise your business!

    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 Ingenico 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 “IngenicoResponsivePaymentPageTemplate_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 “IngenicoResponsivePaymentPageTemplate_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{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 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 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

      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

      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.

      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.

      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*
      06 = White Listing
      07 = Corporate
      08 = Delayed Shipment
      09 = Delegated authentication (certified wallet)

      * 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.

      Soft Decline

      A typical flow of a soft declined transaction looks like this:

      1. In your first request, you send FLAG3DS=N only and no further authentication parameter. This way you indicate that you wish to skip 3-D Secure. The transaction might be accepted already now.
        If it is rejected by your customer’s bank because it insists on 3-D Secure, we will indicate this in the feedback parameter by sending NCERROR=40001139. The transaction will be put in status 2.
      2. To recover this declined transaction, resubmit the transaction by sending the following parameters to our platform
        1. The standard request for e-Commerce / DirectLink parameters as sent in your first request as a new order
        2. FLAG3DS=Y to indicate 3-D Secure needs to be rolled out
        3. The 3DSv2 authentication parameters as described here
        4. Mpi.threeDSRequestorChallengeIndicator=04 to indicate that your customer’s bank insists on 3-D Secure following the Soft Decline

      Your customer will have to pass the 3-D Secure authentication during this second request. Finally, the transaction will reach either status 2 or 9. This depends on both whether your customer passed the authentication and the payment is accepted by both your and your customer’s bank.

      Soft Decline is currently available for payment methods Visa, MasterCard, American Express and Carte Bancaire.

      Mastercard+ 3DSv2

      To maximize the chance of a frictionless flow, MasterCard has developed the specific extension “MasterCard 2.1+”. That means that you can send three more parameters on top of the recommended parameters.

      <th">Name

      Parameter / Name

      Mpi.merchantFraudRate / 

      Merchant Fraud Rate

      Merchant fraud rate in the EEA (all EEA card fraud divided by all EEA card volumes) calculated as per PSD2 Regulatory Technical Standards (RTS).

      Make sure to calculate the rate according to PSD2 RTS Article 19 regulation, as neither MasterCard nor we will validate the score.

      Length: max 2 characters
      Format: integer 1=> 99
      Values accepted:

      • 1 (represents fraud rate less than or equal to 1 basis point [bp], which is 0.01%)
      • 2 (represents fraud rate between 1 bp + - and 6 bps)
      • 3 (represents fraud rate between 6 bps + - and 13 bps)
      • 4 (represents fraud rate between 13 bps + - and 25 bps)
      • 5 (represents fraud rate greater than 25 bps)

      Sending these parameters will provide all parties involved with much more information. This will not only lead to more frictionless flows, but also to higher approval rates and less fraud cases.
      Please note that these additional parameters are only working with MasterCard transactions. Using them with any other payment method will not have any effect

      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

      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

      More test cards numbers can be downloaded here.

      8. Use additional possibilities

      FAQs

      In your Ingenico account menu, you can easily lookup your transactions by choosing "Operations" and then clicking either "View transactions" or "Financial history", depending on the type of transaction results you're looking for.

      Go to Consult your transactions for more information.

      By default you can send goods or deliver your service once a transaction has reached the status "9 - Payment requested". However, although status 5 is a successful status, it's only a temporary reservation of an amount of money on the customer's card. A transaction in status 5 still needs to be confirmed (manually or automatically) to proceed to the status 9, which is the final successful status for most payment methods.

      Go to Transaction statuses for more information.

      You can easily refund a payment with the "Refund" button in the order overview of a transaction (via View transactions). If your account supports it, you can also make refunds with a DirectLink request or with a Batch file upload (for multiple transactions).

      Please note that the Refunds option has to be enabled in your account.

      Go to Maintain your transactions for more information.

      If you want to check specific details of an order/transaction or perform maintenance on transactions, you should use View transactions. "Financial history" is the most convenient to periodically check incoming and outgoing funds.

      For more information, go to View transactions vs Financial history.

      You can only perform refunds on transactions which have already received status 9 for at least 24 hours. A cancellation or deletion can be done within approximately 24 hours after final status has been received (status 9 or 5).

      To know the cut-off time of the acquirer, we recommend you to check directly with our Customer Care department.

      The message "An error has occurred; please try again later. If you are the owner or the integrator of this website, please log into the Ingenico back office to see the details of the error." is a generic error message which is returned if a specific technical issue occurs at the moment the payment page is called. We don't display the actual error on the payment page, mainly because of security reasons, but also not to confuse your customers.

      In your Ingenico account, via "Configuration" > "Error logs", you can easily look up the errors that occurred when the generic error message was displayed. The actual meaning of these errors are described on the Possible errors page.