Allgemein

Profil

User Manual for the Ingenico ePayment Connect Shopware Plugin

 

This manual shows you step by step how to install the plugin to your online shop. Please test the installation and the configuration of the plugin on a test system before installing it on your live shop.

 

1. General

1.1 Plugin Information

1.2  About Ingenico Connect

1.3 Technical Support

2. Supported Payment methods

3. Installation

3.1 Download via Shopware Plugin Manager

3.2 Plugin Activation

4. Configuration

4.1 General Settings

4.2 Test Environment Settings

4.3 Productive Environment Settings

4.3.1 Iframe

4.3.2 Redirect

4.4 Logging

4.4.1 Log file storage

4.4.2 View log files

4.4.3 Expert options

5. Configuration of payment methods in the Shopware backend

6. Ingenico payment status mapping

7. Extending order confirmation email

8. Error messages

9. After Sales

9.1. Ingenico Connect Status and Current payment status

9.2 Fraud Approve

9.3 Capture

9.3.1 Total Capture

9.3.2 Partial Capture

9.4 Cancellation of Pending Orders

9.5 Refund



1. General

1.1 Plugin Information

Shopware versions: from 5.3.3

Plugin version: 1.0.0

Plugin language : german, english

1.2  About Ingenico Connect

Ingenico Connect is your gateway to the payment platforms within Ingenico ePayments:

  • Global Collect Payment Platform
  • Ogone Payment Platform (currently in beta)

For new merchants: You need to create an Ingenico ePayments account to use the plugin.
Please visit the site of Ingenico ePayments for more information or feel free to contact the Ingenico team

For existing merchants: Your Ingenico contract states the payment platform you can connect to. 

Ingenico Connect offers you a suite of tools and services to make integration to our payment platform simple, fast and secure by using the latest technologies.

Ingenico Connect comes with a Developer Hub. There you can find all technical information.

1.3 Technical Support

In case of a problem or a question we will kindly ask you to contact the Ingenico ePayments Support first. Ingenico decides whether the request is forwarded to mediaopt or processed in-house. For all support inquiries we ask you to name your Ingenico ePayments User ID. 

If support requests are made directly to mediaopt, we kindly ask you to clarify the assumption of costs with Ingenico ePayments, alternatively mediaopt can unfortunately only accept the support for a fee. You will receive a short info in response to your request.

 


2. Supported Payment methods

Ingenico ePayments offers more than 150 payment methods in over 170 countries for 150 currencies. In the Developer Hub you can see a list of all payment method.

Ingenico Connect reffers to the Ogone payment methods only.

 


3. Installation

Before you start with the installation process, backup your database and your online shop. If you have concerns about installing the plugin, let this job be done by a professional, or feel free to contact us for help. Please, follow this instruction carefully for an undisturbed use.

If you don’t have a test environment, we can offer you a demoshop to test this and other plugins. Please feel free to contact us motomate@mediaopt.de

3.1 Download via Shopware Plugin Manager

  • Log in to your shop backend
  • Go to: Configuration > Plugin Manager and search for the Incenico ePayments Connect platform Plugin
  • Click the Install Button

3.2 Plugin Activation

Activate the plugin in Configuration > Plugin Manager > Installed > Inactive > Ingenico ePayments Connect platform by clicking the pencil and then the Activate button. 

 


4. Configuration

4.1 General Settings

Please select a shop (right upper corner) for which you want to configure the plugin.

Enable in this subshop: You can decide for each subshop, whether the plugin should be used for it. 

Environment mode: Which environment should be used? Test or Productive Environment? Be aware also to use the right endpoints for the right environment mode. So no real money will be be transferred, when you use the "Test" mode and the right sandbox or pre-prod entpoint. But if you choose "Test" mode and you enter a productive endpoint in the productive tab, real money will be transferred even if the environment is set to "test".

Transaction Mode: Choose your transaction mode. Not all payment methods support direct capture.

Compatibility mode: Shopware provides different ways of saving attribute in the data base. It's possible to use the query builder, which saves the data directly to the database or use doctrine. Doctrine is an ORM library for PHP to handle Database data as objects. Both ways work, but sometimes other plugins can cause side effects or even errors. Since Shopware recommends to not use the ORM for frontend operations, the query builder option is preselected. If any errors occur, especially after activating other plugins, the problem may be solved by changing this option. We need this option to be compatible with other 3rd partie plugins.

Enable card tokenization: Activate CardOnFile (one click payment). Does the merchant want to generate tokens for future usage by the consumer (if the consumer allows this online). These token enable the customer to use the same card again without entering the details and without saving any confidential information in the shop.

Number of days before cancelling pending orders: How many days an order may stay in "pending" state. 0 means unlimited This concerns only Ingenico orders in the shop. This will affect only the order status, but it won't delete the order or cancel the transaction on Ingenico site.

Email-address for fraud alert: Enter your email-address for fraud alerts. If empty this feature will be disabled.

 

4.2 Test Environment Settings

Merchant ID: Please enter your Merchant ID that you also use at Ingenico.

API endpoint: Please enter the API endpoint. Click here for more information

API secondary endpoint: Please enter the secondary API endpoint. This endpoint will be used, if the authentication with the first one fails. 

API key: Please enter your API key. Your API key can be configured at the Payment Console.

API secret: Please enter your API secret key. Your API key can be configured at the Payment Console.

Check connection: Click the button to test the credentials.

After clicking on the button, you will get your results for current configuration. You may check the connection without saving the configuration.

 

Webhooks key ID: Enter the webhook key ID, which was configured at the Payment Console before. Webhooks are used to send transaction feedback to your shop.

Webhooks secret key: Enter the webhook key ID, which was configured at the Payment Console before. This secret key will be used, if the authentication with the first one fails.

Hosted Checkout Subdomain: You will receive the information from Ingenico.

Payment processing mode: You can choose between Iframe or Redirect. Should the customer be redirected to the Ingenico payment page after the order or should an Iframe be integrated in the shop? (see 4.3.1 and 4.3.2)

Look & feel variant ID:  If you want to customize the look and feel of the hosted checkout payment page, create or edit look at feel layout at Ingenico Payment Console and insert the layout ID Here. No or false IDS will use the default layout.

 

4.3 Productive Environment Settings

see 4.2 Test Environment Settings. The same configuration options like the productive environment

4.3.1 Iframe

 

4.3.2 Redirect

4.4 Logging

You can find the logfiles at the backend of your shop in Configuration > Logfiles > System log > mopt_ingenico_connect....

The Ingenico connect plugin config contains 3 options concerning logging:

Log fetch payment list: Enable this option to additionally log the fetching of available payment methods during the checkout. Be aware, this could cause huge logfiles. Use this option for debugging reasons only.

Log level: Choose the log level which will be logged. The plugin logger supports 3 log level (error, info and debug). Shops in production mode should use error, configure different log levels for debugging.

Log rotation: How many days the log file should be stored? 0 means unlimited. A new log file is created for every day.

 

4.4.1 Log file storage

The files are stored in the Shopware log directory (SHOP_ROOT/var/log/). The files are named like the plugin with the production mode and the date added eg: mopt_ingenico_connect_test-2018-04-23.log.

4.4.2 View log files 

It's always possible to log into the server or access the server via (s)ftp to view the log files. For single instance shop (the runs on 1 single server), it's possible to use the builtin log viewer in the Shopware backend (Configuration -> Logfile -> Tab: System Log -> choose log file in drop down field).

4.4.3 Expert options

The logger uses monolog and implements the PSR log interface. Additionally, it implements the log interface from the Ingenico SDK (Ingenico\Connect\Sdk\CommunicatorLogger). Since it's using monolog it's possible to add, remove or replace handlers and formatters or to replace the whole logger. The service id is mopt_ingenico_connect.logger, so it's easy to access and modify.

We are saving ingenico data as order attributes. In some edge cases you might need to switch from "Use Doctrine query builder to save attributes" to "Use Doctrine model manager to save attributes". You may consult with you developing team if you should to switch this option or not.

 

4.4.1 Iframe

 

4.4.2 Redirect

 

5. Configuration of payment methods in the Shopware backend

Go to Configuration > payment methods > Ingenico ePayments.

Please also get sure, that this payment method is also available in the selected countries.

Therefor you have to go to the country tab and select all countries, where Ingenico ePayments should be also available.

The customer will see a dynamic list of payment providers, which the merchant had chosen at the Ingenico Plattform. Please reach out to Ingenico for the payment methods configuration.

Note: Surcharge or discounts will count for all Ingenico ePayments payment methods.

 


6. Ingenico payment status mapping

You can edit and configure the Ingenico payment status mapping in Configuration > Ingenico Connect > Payment status mapping. A list will show you the current configuration of the status.

You can decide, which response of Ingenico Connect will be allowed to create an order. After a payment the customer will be either redirected to your finish site or back to the checkout overview depending on the acceptance of the state.

Additionally, you can map each Ingenico state to one of your Shopware status, which will change the payment status to the last response of Ingenico.

 


7. Extending order confirmation email

The plugin will modify the following variables during the confirmation email rendering:

  1. $additional.payment.description - used payment product name and logo will appear here.
  2. $additional.payment.additionaldescription - if there are any payment instructions, they will appear here as html.

You can also use these variables in the confirmation mail template (Configuration > Email templates > System mails >sORDER):

$additional.user.mopt_ingenico_payment_id = 'Ingenico payment product id' - not rendered right now.
$additional.user.mopt_ingenico_payment_name - a string like 'Visa'
$additional.user.mopt_ingenico_payment_logo - a string like 'https://full/path/to/a/brand/logo.png'
$attributes.mopt_ingenico_payment_instructions - a json encoded string with instructions like '{'showData': [{'key': 'IBAN', 'value': '123456'}, ...]'

 


8. Error messages

All payment status messages are Snippets, which can be edit under Configuration > Snippets > frontend -> moptIngenicoConnect -> paymentStatus by clicking into the "Value"

 


9. After Sales

The Ingenico ePayments Connect Plugins allows you to capture and refund orders. Click on Customers > Orders.

There you will see a list of all orders, which you can edit, capture, refund and so on. Choose an order, which you want to edit. You can also choose several orders to capture or cancel then.

9.1. Ingenico Connect Status and Current payment status

In the order overview you can see the current payment status of the orders. These give you the information, if a payment is completed, open or also if a review is necessary. The Ingenico Connect Status shows you via Icons (see list below) the Ingenico Connect status these status are also related to the current payment status. The Ingenico Status is just shown for orders, which were paid with an Ingenico Connect payment method.

Icons   Ingenico connect status Current payment status
We have matched the incoming funds to the transaction. Completely paid
Instruction have been provided and we are waiting for the money to come in. open
The Transaction is in the queue to be captured. reserved
The transaction is awaiting approval from you to proceed with the single capturing of the funds. Transactions in this state can be captured only once. open
The Transaction has been marked for manual review after an automatic fraud screening. Review necessary
You have cancelled the transaction. The process has been cancelled
no Icon This is not a payment with an Ingenico Connect payment method -

 

9.2 Fraud Approve

If an order is marked with this icon  than you have to check the order because the order might be suspicious. 

You can approve the order or cancel it by clicking on the right button. 

If you approve the fraud status, the current payment status will change from "Review necessary" into "Open" and the Ingenico Connect Icon will change, depending on the payment method.

In case of a Fraud detection you will recieve a notification mail with the order number and all important information.

9.3 Capture

You can easily capture an order or also made a partial capture by selecting the position you want to capture. But be aware, that you can capture only once.

9.3.1 Total Capture

There are two ways to capture an order. First option is by choosing an order from the order overview list and then clicking the "Capture selected orders". It is also possible to choose more than one order to capture them.

 

The other way is, by editing an order and clicking on the button "Capture"

9.3.2 Partial Capture

It is also possible not to capture the whole order but only one or several positions of the order. Therefor you go to the order and then to the register "Position". 

There you can choose the position you would like to capture and click on "Capture selected positions"

Another window will be opened where you cat the information of the selected position, which you going to capture. You can also decide, whether you want to capture also the shipping cost or not.

It is possible to make just one single capture for this order. The other position won’t be capturable.

 

You can also undo a capture before the amout is real captured. This action will retun to the previous payment status.

Therefore you click on the "Undo Capture" Button in the order, which you have captured before.

 

9.4 Cancellation of Pending Orders

You can cancel orders while there the payment process is still open. Therefore, you can click in the selected order the "Cancel" Button. With this button you are going to cancel the payment transaction at the Ingenico Connect platform. This makes it impossible to process the payment. You are not able to undo this action!

9.5 Refund

If a payment is completely paid, you can also refund the amount or a part of the amount or even several positions.

Therefore you need to go to a paid marked order and edit it by clicking on the "Refund" Button.

In the Order Overview page you can only refund the total amount with shipping costs.

If you want to refund just selected position, you need to go to the register "Positions" and select the products you want to refund and click on the "Refund selected Positions" Button. You can decide whether you want to refund also the shipping costs or not.

You can also cancel a refund by clicking the "Cancel Refund" Button. This will cancel the refund process.