Magento 2 Plugin Integration Guide...• Managing payment forms including creating new forms or...

Magento 2 Plugin IntegrationGuide

Online payment solutions for Asia-Pacific

Table of ContentsOverview ............................................................................................................................... 3

Related Documents ....................................................................................................... 3Requirements ................................................................................................................ 3

Installation ............................................................................................................................. 4Configuration ......................................................................................................................... 6Firewall Configuration ............................................................................................................ 7

Merchant Firewall Rules/White-listing - Payment Gateway Outgoing ................................. 7Merchant Firewall Rules/White-listing - Payment Gateway IP Addresses ........................... 7

Notifications .......................................................................................................................... 8Magento Notifications ..................................................................................................... 8Viewing Notifications / Debugging Notification Issues ....................................................... 8

Order States & Events ......................................................................................................... 10Performing Transactions ...................................................................................................... 11

Capturing Transactions ................................................................................................ 11To issue a settlement from within Magento: ........................................................... 11

Voiding Transactions .................................................................................................... 13To void a transaction within Magento: .................................................................... 13

Crediting Transactions ................................................................................................. 14To issue a credit transaction within Magento: ......................................................... 14

Viewing Transaction Details .......................................................................................... 15To view transactions within Magento ..................................................................... 15

Troubleshooting ................................................................................................................... 17Change Log ........................................................................................................................ 18

Magento 2 Plugin Integration Guide

© Copyright Protected. All rights reserved.Published on 2017-11-30.

of 18

Overview

This document describes how to enable the Magento 2.0 Plugin (supports versions 2.0 / 2.1 / 2.2 ofMagento) for use with the Gateway-Hosted Payment Page. The Magento plugin provides the followingcapabilities:

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

• Allow event notifications from the Payment Gateway to be consumed and displayed within Magento.

Related DocumentsRelated 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, thenDocument Downloads.

Document Description

Secure PaymentForm API

Gateway-Hosted Payment Page - a PCI DSS compliant payment form that allowsmerchant'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 ServicesAPI

This document covers the technical specifications of the Web Services API that includesinformation on ancillary and reconciliation services. This API is used for submittingcustomer and order information along with the tokenised card data.

User Guide forManagers

This user guide provides information on the tools a manager can use on the Gatewayincluding:

• Reviewing and managing configuration

• Managing payment forms including creating new forms or addition of new fields, oradvanced 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

RequirementsTo 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 youraccount 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.



of 18

https://my.ipgpay.com/support/docs

Installation

CUSTOMISED TEMPLATESThe plugin has been designed for the default Magento template and it is not possibleto support all available customized skins. If there are compatibility issues with acustomized 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 documentationhttp://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_IPGPAYMagento2The 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



of 18

http://devdocs.magento.com/guides/v2.2/config-guide/cli/config-cli-subcommands.html



of 18

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, andused to verify notifications from the Payment Gateway.

Request Expiry Time period validity of requests to the Gateway-Hosted Payment Page. Used toensure that product prices or specials are only accepted on the Gateway-HostedPayment 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. Testmode 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 CustomerEntities

Will create a customer entity for each order.

Merchant ManagedRebilling

Will create orders capable of Merchant Managed rebilling via the Web ServicesAPI.

Payment FormApplicable Countries

Activate specific countries or all countries during checkout.

Payment Form SpecificCountries

Countries available during the checkout.

Use Popup Will use popup when payment order

• Yes: Open a popup window to payment

• No: Redirect to IPG Gateway to payment



of 18

Firewall Configuration

Merchant Firewall Rules/White-listing - Payment GatewayOutgoingIn order to connect to the Payment Gateway to issue settlements or credits you must ensure that youhave added the required rules or white-listing to your firewall or servers to allow outgoing connectionstohttps://my.ipgpay.com in your firewall.

IMPORTANTThis rule cannot be done with IP addresses as they can change at any time.

Merchant Firewall Rules/White-listing - Payment Gateway IPAddressesIn order to receive notifications from the Payment Gateway you must ensure that you have added therequired rules or white-listing to your firewall or servers to allow connections from the following IPaddresses:

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 notificationsmay fail.



of 18

https://my.ipgpay.com

Notifications

Notifications are server to server messages sent from the Payment Gateway to a Merchant or ThirdParty system endpoint, providing details on an event that happened on the Payment Gateway. Thisallows Merchants to integrate their website or application tightly with the Payment Gateway and toperform 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 theirAccount 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 NotificationsIn order for the Payment Gateway to send these notifications you need to provide your accountmanager with the endpoint of your Magento installation.

For example - if you have installed your Magento instance on a domain https://www.example.com inthe 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. Notificationscan only be sent to port 80 or 443 (http:// or https://). It is highly recommended that merchants use anSSL secured endpoint (https://) for notifications.

Viewing Notifications / Debugging Notification IssuesIf you are having issues receiving notifications the Payment Gateway has tools to help you view thenotification 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 successfullyadded to your firewall/system. Double check your firewall/system logs to ensure the notifications are notbeing blocked/dropped.

To view notifications log into the Payment Gateway and from the top navigation menu clickeCommerce, then Notifications. You will be able to view/search for notifications that have beenattempted by the Payment Gateway. The status and type of notification are displayed, along with thefirst and last time the notification was attempted.

To retry the notification - click the Resend button. The Payment Gateway will then attempt to send thenotification again.



of 18

https://www.example.com/

To view the raw request data for a notification click the Notification ID - you can then see the endpointURL used - and the HTTP response code returned by the endpoint. If you click request details you cansee the raw and tabular data sent to the endpoint.



of 18

Order States & Events

Event Order State Information

Customer confirms order andredirected to the Gateway-Hosted Payment Page

Pending Awaiting customer to complete payment.

Customer completed order andreturns to cart / Paymentnotification received

Auth: PendingPayment

Sale: Processing

Payment has been received. Authorisationtransactions will still require settlement usingCapture functionality within Magento admin.

Sale transactions will automatically createInvoices.

Invoice created within Magentowith Capture Online option

Processing Payment will be automatically settled in thePayment Gateway. It settlement fails, the invoicewill not be created. Order will be indicated as paid.

Void issued from withinMagento

Processing Payment will be automatically voided in thePayment Gateway.

Credit memo issued fromwithin Magento

Processing Payment will be automatically credited in thePayment Gateway.

Rebilling cancelled from withinMagento

Not Applicable Cancelling rebilling is not associated with an orderstatus.

Settlement issued from thePayment Gateway

Processing If an Authorisation transaction is settled from thePayment Gateway, an invoice within Magentoadmin is created automatically.

Void issued from the PaymentGateway

Cancelled Orders will be cancelled if voided from thePayment Gateway.

Credit issued from thePayment Gateway

No change Credits issued form the Payment Gateway do notchange the order status in Magento.

Rebilling instalment issuedfrom the Payment Gateway

Not Applicable Recurring transactions are not associated with anorder status.



of 18

Performing Transactions

Capturing TransactionsAuthorisation transactions require settlement before the funds will be cleared. It is recommended thatsettlements are issued when the goods are shipped. The settlements can be issued from withinMagento, or from within the Payment Gateway via the Order Management page. Settlements are onlypossible on transactions that have not previously been settled or voided. To issue a Settlement fromwithin 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



of 18

• Click Submit Invoice. If the settlement is successful, an invoice will be created.



of 18

• Transaction information will also be attached to the order comments

Voiding TransactionsCancelling an Authorisation transaction is possible by issuing a Void. A Void will return funds to the cardholder by cancelling the transaction. Voids are only possible on Authorisation transactions that have notbeen previously settled or voided. Voids can be issued from within Magento or from within the PaymentGateway via the Order Management page. To issue Voids from within the Payment Gateway, pleaserefer to the User Guide for Managers.

To void a transaction within Magento:




• 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



of 18

Crediting TransactionsCredit transactions can be issued from the Credit Memo workflow within Magento or from within thePayment Gateway from the Order Management page. Credits can only be issued on Sale transactionsor Authorisation transactions that have been settled and have an invoice attached.

To issue a credit transaction within Magento:

• Login to te Magento admin.



• Locate the relevant invoice you wish to credit. Note: Online credits can only be issued from theinvoice 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.



of 18

• 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 DetailsIndividual transaction information is stored within Magento and linked to the relevant order. Detailedinformation about each transaction is viewable from the Transaction Management page and from theorder page.

To view transactions within Magento


• Go to Sales -> Transactions.

• Locate and click the relevant transaction



of 18



of 18

Troubleshooting

Symptom Resolution

IPGPAY payment option doesnot appear on the Magentofront end

• Ensure files are copied to the correct location

• Clear Magento cache

• Run ./bin/magento module:enable --clear-static-contentIPGPAY_Gateway

• Ensure Enabled = Yes in the plugin configuration

Magento workflow does nottrigger/Orders do not changestatus

• Ensure that the Notification URL is correctly configured in yourGateway account configuration

• Ensure you do not have firewalls blocking notifications from theGateway

• Ensure the secret key is correctly configured and matches yourGateway account configuration

Capture/Void from withinMagento does not work

• Ensure API key is correctly configured

• Ensure firewall is configured to allow outbound connections to PaymentGateway IP Addresses listed above

"Data tempering detected"error message shown whenloading the Payment Form

• Ensure the secret key is correctly configured and matches yourGateway account configuration



of 18

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

• Added Notifications information on configuring and debugging notification events.

2016-10-08 Initial Draft



of 18

Magento 2 Plugin Integration Guide...• Managing payment forms including creating new forms or...

Documents

Transcript of Magento 2 Plugin Integration Guide...• Managing payment forms including creating new forms or...