Online payment solutions
for Asia-Pacific
Magento 2 Plugin Integration
Guide
Magento 2 Plugin Integration Guide
Table of Contents
Overview ............................................................................................................................... 3
Related Documents ....................................................................................................... 3
Requirements ................................................................................................................ 3
Installation ............................................................................................................................. 4
Configuration ......................................................................................................................... 6
Firewall Configuration ............................................................................................................ 7
Merchant Firewall Rules/White-listing - Payment Gateway Outgoing ................................. 7
Merchant Firewall Rules/White-listing - Payment Gateway IP Addresses ........................... 7
Notifications .......................................................................................................................... 8
Magento Notifications ..................................................................................................... 8
Viewing Notifications / Debugging Notification Issues ....................................................... 8
Order States & Events ......................................................................................................... 10
Performing Transactions ...................................................................................................... 11
Capturing Transactions ................................................................................................ 11
To issue a settlement from within Magento: ........................................................... 11
Voiding Transactions .................................................................................................... 13
To void a transaction within Magento: .................................................................... 13
Crediting Transactions ................................................................................................. 14
To issue a credit transaction within Magento: ......................................................... 14
Viewing Transaction Details .......................................................................................... 15
To view transactions within Magento ..................................................................... 15
Troubleshooting ................................................................................................................... 17
Change Log ........................................................................................................................ 18
© Copyright Protected. All rights reserved. Page 2 of 18
Published on 2017-11-30.
Magento 2 Plugin Integration Guide
Overview
This document describes how to enable the Magento 2.0 Plugin (supports versions 2.0 / 2.1 / 2.2 of
Magento) for use with the Gateway-Hosted Payment Page. The Magento plugin provides the following
capabilities:
• Allow Magento to redirect customers to the Gateway-Hosted Payment Page.
• Allow Magento to perform actions on existing orders such as crediting or settling an Authorisation
transaction.
• Allow event notifications from the Payment Gateway to be consumed and displayed within Magento.
Related Documents
Related Documents are available from the Payment Gateway at https://my.ipgpay.com/support/docs.
Alternatively log into the Payment Gateway and from the top navigation menu click Support, then
Document Downloads.
Document Description
Secure Payment Gateway-Hosted Payment Page - a PCI DSS compliant payment form that allows
Form API merchant's to process payments securely for a variety of supported payment methods.
This document provides technical information on the Application-Programming Interface
(API) for merchant's to complete their integration.
Web Services This document covers the technical specifications of the Web Services API that includes
API information on ancillary and reconciliation services. This API is used for submitting
customer and order information along with the tokenised card data.
User Guide for This user guide provides information on the tools a manager can use on the Gateway
Managers including:
• Reviewing and managing configuration
• Managing payment forms including creating new forms or addition of new fields, or
advanced customisation of existing forms
• Managing notifications, including notification endpoints and configuration
• Managing predefined items
• Managing passwords & password realms
• Managing integration errors
• Managing/searching existing orders
Requirements
To use the Magento plugin, the folllowing items are required:
• A working and properly configured Magento installation
• A valid Payment Gateway merchant account
• Payment Form URL, Secret Key, Manager Account ID, API Key and API Base URL provided by your
account manager.
• A Payment Form ID from a Payment Form created in the Payment Gateway.
• A notification URL that points to your Magento installation configured in the Payment Gateway.
© Copyright Protected. All rights reserved. Page 3 of 18
Published on 2017-11-30.
Magento 2 Plugin Integration Guide
Installation
CUSTOMISED TEMPLATES
The plugin has been designed for the default Magento template and it is not possible
to support all available customized skins. If there are compatibility issues with a
customized template we recommend contacting the supplier of the template.
To install and configure the Magento plugin:
1. Installation of the IPGPAY Payment Method requires the command line interface for Magento 2.
For more information about the command line, please see the official Magento documentation
http://devdocs.magento.com/guides/v2.2/config-guide/cli/config-cli-subcommands.html.
2. In the command line prompt, execute the following in your Magento folder:
# Update composer (this will take a while)
$ composer update
# Install the IPGPAY magento payment module
$ composer require ipgpay/ipgpay-magento2-payment-module
# Enable the module
$ magento module:enable IPGPAY_IPGPAYMagento2
The following modules have been enabled:
- IPGPAY_IPGPAYMagento2
# Run the scripts and clear the cache after installing new modules
$ magento setup:upgrade
$ magento cache:flush
3. If installed correctly, the payment module should be visible in Stores -> Configuration -> Sales ->
Payment Methods.
4. Ensure module is active - Enabled= Yes.
5. Configure the module with values supplied by your account manager
© Copyright Protected. All rights reserved. Page 4 of 18
Published on 2017-11-30.
Magento 2 Plugin Integration Guide
© Copyright Protected. All rights reserved. Page 5 of 18
Published on 2017-11-30.
Magento 2 Plugin Integration Guide
Configuration
The following configuration options are available in the Magento plugin:
Option Description
Enabled Enable or disable the Magento plugin.
Title The title displayed to the customer on the store front during checkout.
Payment Form URL Gateway-Hosted Payment Page URL assigned by your account manager.
Payment Form ID ID of the Payment Form created in the Payment Gateway.
Secret Key Secret key used in forming requests to the Gateway-Hosted Payment Page, and
used to verify notifications from the Payment Gateway.
Request Expiry Time period validity of requests to the Gateway-Hosted Payment Page. Used to
ensure that product prices or specials are only accepted on the Gateway-Hosted
Payment Page for the specified time period.
Account ID Your assigned Manager ID within the Payment Gateway.
API key Key to access the Web Services API.
API Base URL Base URL of the Payment Gateway.
Test Mode Checkout in Liveor Testmode. Live mode will perform financial transactions. Test
mode will perform non-financial transactions for the purpose of testing.
New Order Status The initial state of orders before payment has been completed by the customer.
Create Customer Will create a customer entity for each order.
Entities
Merchant Managed Will create orders capable of Merchant Managed rebilling via the Web Services
Rebilling API.
Payment Form Activate specific countries or all countries during checkout.
Applicable Countries
Payment Form Specific Countries available during the checkout.
Countries
Use Popup Will use popup when payment order
• Yes: Open a popup window to payment
• No: Redirect to IPG Gateway to payment
© Copyright Protected. All rights reserved. Page 6 of 18
Published on 2017-11-30.
Magento 2 Plugin Integration Guide
Firewall Configuration
Merchant Firewall Rules/White-listing - Payment Gateway
Outgoing
In order to connect to the Payment Gateway to issue settlements or credits you must ensure that you
have added the required rules or white-listing to your firewall or servers to allow outgoing connections
tohttps://my.ipgpay.com in your firewall.
IMPORTANT
This rule cannot be done with IP addresses as they can change at any time.
Merchant Firewall Rules/White-listing - Payment Gateway IP
Addresses
In order to receive notifications from the Payment Gateway you must ensure that you have added the
required rules or white-listing to your firewall or servers to allow connections from the following IP
addresses:
217.119.96.3 217.119.96.4 217.119.98.3 217.119.98.4
It is important that all the above IP addresses are white-listed in your system, otherwise notifications
may fail.
© Copyright Protected. All rights reserved. Page 7 of 18
Published on 2017-11-30.
Magento 2 Plugin Integration Guide
Notifications
Notifications are server to server messages sent from the Payment Gateway to a Merchant or Third
Party system endpoint, providing details on an event that happened on the Payment Gateway. This
allows Merchants to integrate their website or application tightly with the Payment Gateway and to
perform actions on their own system in response to events.
The Merchant must create their own script/application on their server and provide the URL to their
Account Manager to be configured in their Merchant Configuration, events will then be sent to this URL.
Types of notification events include:
• New Payment Orders.
• Payment Completion (for Payment Methods where the payment is asynchronous).
• Fraud advice received for previous Orders/Transactions.
Please refer below for a full list of supported notification events.
Magento Notifications
In order for the Payment Gateway to send these notifications you need to provide your account
manager with the endpoint of your Magento installation.
For example - if you have installed your Magento instance on a domain https://www.example.com in
the root ( / ) directory - your notification endpoint would be:
https://www.example.com/ipgpay/notification/handle
For merchants running a multilingual Magento installation, the URL would be:
https://www.example.com/store/en/ipgpay/notification/handle
You will need to confirm this on your own environment to ensure the URL is correct.
The URL must be a fully qualified host/domain name - IP Addresses are not supported. Notifications
can only be sent to port 80 or 443 (http:// or https://). It is highly recommended that merchants use an
SSL secured endpoint (https://) for notifications.
Viewing Notifications / Debugging Notification Issues
If you are having issues receiving notifications the Payment Gateway has tools to help you view the
notification data, response to the notification request and also to trigger a notification to be resent.
The first thing you should verify is that the Payment Gateway IP addresses have been successfully
added to your firewall/system. Double check your firewall/system logs to ensure the notifications are not
being blocked/dropped.
To view notifications log into the Payment Gateway and from the top navigation menu click
eCommerce, then Notifications. You will be able to view/search for notifications that have been
attempted by the Payment Gateway. The status and type of notification are displayed, along with the
first and last time the notification was attempted.
To retry the notification - click the Resend button. The Payment Gateway will then attempt to send the
notification again.
© Copyright Protected. All rights reserved. Page 8 of 18
Published on 2017-11-30.
Magento 2 Plugin Integration Guide
To view the raw request data for a notification click the Notification ID - you can then see the endpoint
URL used - and the HTTP response code returned by the endpoint. If you click request details you can
see the raw and tabular data sent to the endpoint.
© Copyright Protected. All rights reserved. Page 9 of 18
Published on 2017-11-30.
Magento 2 Plugin Integration Guide
Order States & Events
Event Order State Information
Customer confirms order and Pending Awaiting customer to complete payment.
redirected to the Gateway-
Hosted Payment Page
Customer completed order and Auth: Pending Payment has been received. Authorisation
returns to cart / Payment Payment transactions will still require settlement using
notification received Capture functionality within Magento admin.
Sale: Processing
Sale transactions will automatically create
Invoices.
Invoice created within Magento Processing Payment will be automatically settled in the
with Capture Online option Payment Gateway. It settlement fails, the invoice
will not be created. Order will be indicated as paid.
Void issued from within Processing Payment will be automatically voided in the
Magento Payment Gateway.
Credit memo issued from Processing Payment will be automatically credited in the
within Magento Payment Gateway.
Rebilling cancelled from within Not Applicable Cancelling rebilling is not associated with an order
Magento status.
Settlement issued from the Processing If an Authorisation transaction is settled from the
Payment Gateway Payment Gateway, an invoice within Magento
admin is created automatically.
Void issued from the Payment Cancelled Orders will be cancelled if voided from the
Gateway Payment Gateway.
Credit issued from the No change Credits issued form the Payment Gateway do not
Payment Gateway change the order status in Magento.
Rebilling instalment issued Not Applicable Recurring transactions are not associated with an
from the Payment Gateway order status.
© Copyright Protected. All rights reserved. Page 10 of 18
Published on 2017-11-30.
Magento 2 Plugin Integration Guide
Performing Transactions
Capturing Transactions
Authorisation transactions require settlement before the funds will be cleared. It is recommended that
settlements are issued when the goods are shipped. The settlements can be issued from within
Magento, or from within the Payment Gateway via the Order Management page. Settlements are only
possible on transactions that have not previously been settled or voided. To issue a Settlement from
within the Payment Gateway, please refer to the User Guide for Managers.
To issue a settlement from within Magento:
• Login to the Magento admin.
• Go to Sales -> Orders.
• Locate and click the relevant order.
• Click the Invoice button at the top of the order.
• Ensure that Capture Online is selected at the bottom of the Invoice
© Copyright Protected. All rights reserved. Page 11 of 18
Published on 2017-11-30.
Magento 2 Plugin Integration Guide
• Click Submit Invoice. If the settlement is successful, an invoice will be created.
© Copyright Protected. All rights reserved. Page 12 of 18
Published on 2017-11-30.
Magento 2 Plugin Integration Guide
• Transaction information will also be attached to the order comments
Voiding Transactions
Cancelling an Authorisation transaction is possible by issuing a Void. A Void will return funds to the card
holder by cancelling the transaction. Voids are only possible on Authorisation transactions that have not
been previously settled or voided. Voids can be issued from within Magento or from within the Payment
Gateway via the Order Management page. To issue Voids from within the Payment Gateway, please
refer to the User Guide for Managers.
To void a transaction within Magento:
• Login to the Magento admin.
• Go to Sales -> Orders.
• Locate and click the relevant order.
• Click the Void button at the top of the order.
• When prompted, confirm the Void request
• If successful, the transaction will be confirmed
• Transaction information will be stored against the order comments
© Copyright Protected. All rights reserved. Page 13 of 18
Published on 2017-11-30.
Magento 2 Plugin Integration Guide
Crediting Transactions
Credit transactions can be issued from the Credit Memo workflow within Magento or from within the
Payment Gateway from the Order Management page. Credits can only be issued on Sale transactions
or Authorisation transactions that have been settled and have an invoice attached.
To issue a credit transaction within Magento:
• Login to te Magento admin.
• Go to Sales -> Orders.
• Locate and click the relevant order.
• Locate the relevant invoice you wish to credit. Note: Online credits can only be issued from the
invoice page in Magento, and not from the Order page.
• Select the invoice, and enter the invoice page by clicking View.
• Click the Credit Memo button at the top of the Invoice.
© Copyright Protected. All rights reserved. Page 14 of 18
Published on 2017-11-30.
Magento 2 Plugin Integration Guide
• Click the Refund button at the bottom of the page.
• If successful, the transaction will be confirmed and the credit memo issued
• The transaction will be stored in the order history
Viewing Transaction Details
Individual transaction information is stored within Magento and linked to the relevant order. Detailed
information about each transaction is viewable from the Transaction Management page and from the
order page.
To view transactions within Magento
• Login to the Magento admin.
• Go to Sales -> Transactions.
• Locate and click the relevant transaction
© Copyright Protected. All rights reserved. Page 15 of 18
Published on 2017-11-30.
Magento 2 Plugin Integration Guide
© Copyright Protected. All rights reserved. Page 16 of 18
Published on 2017-11-30.
Magento 2 Plugin Integration Guide
Troubleshooting
Symptom Resolution
IPGPAY payment option does • Ensure files are copied to the correct location
not appear on the Magento
• Clear Magento cache
front end
• Run ./bin/magento module:enable --clear-static-content
IPGPAY_Gateway
• Ensure Enabled = Yes in the plugin configuration
Magento workflow does not • Ensure that the Notification URL is correctly configured in your
trigger/Orders do not change Gateway account configuration
status
• Ensure you do not have firewalls blocking notifications from the
Gateway
• Ensure the secret key is correctly configured and matches your
Gateway account configuration
Capture/Void from within • Ensure API key is correctly configured
Magento does not work
• Ensure firewall is configured to allow outbound connections to Payment
Gateway IP Addresses listed above
"Data tempering detected" • Ensure the secret key is correctly configured and matches your
error message shown when Gateway account configuration
loading the Payment Form
© Copyright Protected. All rights reserved. Page 17 of 18
Published on 2017-11-30.
Magento 2 Plugin Integration Guide
Change Log
The last 10 change events are shown below.
Date Comment
2017-11-30 Add Composer installation instructions
2017-09-27 Add Pop-Up payment form reference
2016-10-12 Documentation:
• Updated formatting and added to the Document Downloads section in the Payment
Gateway.
• Added Notifications information on configuring and debugging notification events.
2016-10-08 Initial Draft
© Copyright Protected. All rights reserved. Page 18 of 18
Published on 2017-11-30.
