Cartis Payments & Magento Guide
Below is an indepth guide on installing the Converge plugin for Magento.
Magento Guide
Need Help? We are here to help you grow no matter what your payment needs are.
Introduction and Installation
Back Office Configuration
Customer View
Admin View
Subscriptions
Introduction and Installation
This guide contains step-by-step instructions on installing the Converge plugin for Magento. It also shows how to use all the plugin’s features. In order to get started, you must have the following items:
- Converge Merchant ID
- Converge API User ID
- Converge User PIN
- Download our free plugin
The plugin has been tested and proven to work with the Community 2.4.3-p1 version of Magento 2.
To integrate using Magento, you will need to contact the Support Team at 1-888-712-0770 to:
- Register and add the IP address and Web URL of your server as allowed sites.
- Set a Converge User ID with a Hosted Payment API User status with permission to post a session token request.
- Associate the Converge User ID with the eCommerce terminal.
Installation Steps
1.1 Installation Requirements and Guide for Magento 2
You have to install Magento 2 before you can install the Converge plugin for Magento.
Magento provides a list of the requirements for installing Magento 2 on their website.
To install Magento 2, please follow the Magento Installation available
Important
Only Linux distributions support Magento.
Magento is not supported on machines running Windows or Mac OS.
Please see the Magento site for more detail:
1.2 Installation for Converge Plugin using COMMAND LINE
- Download the plugin.
- Unzip archive
- Login to your Magento 2.x hosting site using SSH connection
- Open the Magento root directory
- The content of unzipped extension should be copied into the Magento “app/code” folder
Magento root folder structure should look like the below image - To enable module from console line open the Magento root directory and run command: bin/magento module:enable Elavon_ConvergePayment
- To update the database schema and modules run command: bin/magentosetup:upgrade
- To clear the cache run the command:bin/magento cache:flush
This completes the module installation.
Back Office Configuration
After successful installation, please follow the steps below to configure the various integration options supported by this plugin.
Log in to the Magento Admin Panel and navigate to Stores -> Configuration under the Sales heading click the Payments Methods.
On top of the page there will be a field called Store View, where you can find different levels for your configuration. Choosing one of the levels available will influence the fields available for configuration for the Converge Gateway payment method.
The only field from the configuration page available for the store level is the title of plugin.
Under the OTHER PAYMENT METHODS section you can find Converge Gateway configuration panel. The configuration panel contains three sections:
- The first section – “Converge Gateway”
- The second section – “Basic Converge Payment Settings”
- The third section – “Advanced Converge Payment Settings”
Converge Gateway Configuration
This section is displayed under the title of the payment method, the other two sections being collapsed by default. It contains the following fields:
- Environment
- Gateway Region
- Module version
- Merchant ID
- User ID
- User PIN
- Terminal name
Environment
This dropdown is used to switch between Sandbox and Production environment. By default Sandbox is selected and this enables users to test out payment method without using real credit cards.
Converge Gateway Region
This option has currently only one value, Converge NA. Converge EU will be added once the functionalities are available.
Module version
This option is not configurable, it is showing the currently installed version of Converge plugin.
Merchant ID, User ID and User PIN
To configure the plugin to work with Converge, you will need to have the following data and enter them in their corresponding fields:
- Converge Merchant ID
- Converge User ID
- Converge User pin
Terminal name
This field represents the name provided by Converge once a new terminal is setup. The values for this field is displayed after you click “Terminal Setup”.
Basic Payment Settings
Title
This option allows you to enter a specific title. By default, the title is set to Payment method (ConvergeGateway).
Enabled
By default this option is set to NO and it needs to be changed to YES for Converge plugin option to show up on checkout page.
Recurring Enabled
The value for this field is determined based on the options supported by the terminal and cannot be edited. Also, the value for this field determines if the section for subscriptions from the product configuration is displayed or not.
Important
If recurring is enabled on the terminal, the following options are not currently supported:
- Wallets/gift cards will not be supported
- HPP will not be displayed as an integration method
Payment Action
This dropdown enables user to select how they want transaction to be captured in Converge:
- Authorize -> Order amount will only be authorized on Credit Card used for the transaction, and merchant will have to create invoice to capture this amount from Magento.
- Authorize and Capture -> Sale transaction will be captured for this option, invoice will be created automatically and no additional action is needed from merchant side for this transaction to be settled.
Integration Method
This dropdown enables user to select the integration method:
- Hosted Payment Page (PCI SAQ A) -> the merchant redirects the customer away from the merchant’s website to the securely externally-hosted HPP.
- Checkout.js (PCI SAQ A-EP) -> this is an integration method where the webpage is generated by Magento and displayed on the cardholder browser. The Payment data is collected on the browser and sent to Converge for processing. The response is sent back to the browser and appropriate action taken.
License Code
This value for this field is provided by Converge and should be sent with each transaction.
Save for later use message
This field allows the merchant to define a message that is displayed to the user when they are trying to save card for later use.
Disclosure message for subscription options
This field allows the merchant to define a message that is displayed to the user when he is trying to place an order with subscription products. The default message will be: “By placing your order, you agree to the recurring charges.” This message will be displayed to the customer next to the Place Order button.
Advanced Payment Settings
Merchant name
This option is not editable and is loaded from Converge.
Region
This option is not configurable and is loaded from Converge, displayed to the user and used to limit the selection for other options like the language.
Payment Types Accepted
This field is not configurable, it is displaying the available options for the selected terminal. Besides the response from Converge Terminal, the options are influenced by the Payment action type. If Authorize option is selected, all options except Credit Card are removed.
The possible values are:
- Credit Card
- ACH
- Gift Card
Credit Cards Accepted
This field is not configurable, it is displaying the available options for the selected terminal. The possible values are:
- VISA
- Master Card
- American Express
- Discover
- JCB (Japan Credit Bureau)
- CUP (China UnionPay)
Wallets enabled
This field is not configurable, it is displaying the available options for the selected terminal. The possible values are:
- Click to Pay
- PayPal
- Apple Pay
Please note that If the recurring functionality is enabled, wallets will be disabled. The wallets form this field will be hidden and replaced with the message “None – Recurring is enabled”.
Currency Conversion
Values for this option are loaded from Converge, displayed to the user and use only to show the possible features in the future.
The possible values are:
- Multi-Currency Conversion – coming soon
- Dynamic Currency Conversion – coming soon
Language Translations
This field is a dropdown where the language options are displayed for a selected region.
Value Added Service
Values for this option are loaded from Converge, displayed to the user based on terminal settings. The possible values are:
- Recurring billing – if this option is available for the terminal, the merchant will be able to configure subscriptions for a product.
- Tokenization – if the terminal allows tokenization, the customers will have the option to save cards for later use.
- Level 3 data – this options allow sending additional data with each transaction based on the data provided by the merchant.
- 3D Secure – if this option is enabled for the terminal, the transactions will be authenticated using 3D Secure in case the card is enrolled in 3DS.
Log level
This field allows you to define the level for the logging. The options are Debug, Error, and Critical. These values indicate the severity, Debug being the lowest level and Critical the highest one. By default, the value is set to Debug.
Currency Setup
Based on terminal settings, the values for Base Currency, Default Display Currency and Allowed Currencies from Stores -> Configuration -> General -> Currency setup are filled automatically and are disabled for the user.
Customer View
Below you will find an overview of the most important features in the daily usage of the Converge Plugin.
Important
The transaction management between Converge and your shop isn’t synchronized.
Any action performed directly through Converge back office will not be synchronized with Magento. To keep record in both places, you must initiate actions such as capture, delete etc… from your Magento back office only.
Placing an Order
To capture new Authorization Only transaction using Converge Payment plugin you need to make sure that payment action option is set to Authorize along with other options:
- Enabled = Yes
- Environment = Sandbox (if this is a test transaction)
- Merchant ID, API User ID, User PIN = ID information provided by Converge
- Payment Action = Authorize
For Authorization and Capture transaction only one option should be changed:
- Enabled = Yes
- Environment = Sandbox (if this is a test transaction); Merchant ID, API User ID, User PIN = ID information provided by Converge
- Payment Action = Authorize and Capture
Payment procedure is similar for guest and logged in user, with only exception that logged in user has option to save credit card for later use.
To initiate actual payment via Converge you will have to access Checkout page from Magento store view. After you populate Shipping Address (for products with weight) and click on the next button you will be presented with Review and Payments page where you can select Converge Gateway as payment method.
Payment with HPP
If HPP is selected in the configuration page, once you select Converge Payment you will be presented with several additional options:
- option to use previously entered Shipping Address as Billing Address
- option to Place Order
- option to Save card for later use (for logged in user only)
Clicking Place Order opens HPP.
From this page you will have the option to:
- Cancel Payment or
- to proceed to next step screen of HPP
HPP – Cancel payment
For Cancel button to work you need to set actual link where the click on this button will lead you.
Best practice is to set this link to return to payment methods:
- Magento_base_url/checkout/#payment (make sure that you are making changes for appropriate terminal indicated in the upper right corner)
HPP – Checkout
If you do not want to Cancel your payment, you need to click the Checkout button.
Once you reach the next step of payment process on HPP you will be presented with page that will be automatically populated with Shipping and Billing details from Magento, and the user will have option to change them directly on HPP.
After you enter card details you should scroll down to Submit Payment button. Two possible outcomes can happen after you click on Submit Payment button:
- Payment is Declined
- Payment is Accepted
HPP Checkout – Declined
If the payment is declined, error message is displayed to the user and he will be presented with two options:
- RETURN TO MERCHANT
- TRY AGAIN
Return to Merchant
When payment is declined, user will have option to return to Magento by clicking RETURN TO MERCHANT. For this button to work you need to make additional changes in the Converge-Back office.
Please refer to Converge User guide to configure the Cancel URL.
There you will need to set return to merchant link, and best practice is to set this link to return to cart page:
- Magento_base_url/checkout/cart (make sure that you are making changes for appropriate terminal indicated in the upper right corner)
Try Again
When payment is declined, user has the option to re-enter card details or to try again with same card by clicking the TRY AGAIN button. You will be presented with the same page as if you have reached the HPP Checkout screen for the first time and the possible outcomes are also the same.
HPP Checkout – Accepted
When your payment is accepted by Converge, you will be redirected back to Magento and new order will be created. For this to happen you need to set approval link in Converge-Back office.
This link needs to be set to the following location:
- Magento_base_url/converge/payment/iframeresponse
Once link is updated, you should be re-directed back to Magento after each successful payment on HPP. In Magento, you should see the number of newly created order:
You will find more details on how to see payment details and how to manage captured transactions in section describing the use of Magento Admin.
Payment with Checkout.js
If Checkout.js is selected in the configuration page, once you select Converge Payment you will be presented with several additional options:
- option to use previously entered Shipping Address as Billing Address
- option to Place Order
- option to Save card for later use (for logged in user only)
Also, based on other options selected in the configuration page, the following options are available:
- payment with credit card, where you should provide the following details: Credit Card Number, Expiration Date and Card Verification Number
- Payment with gift card, where you should provide the following details: Card number and Expiration Date.
- Payment with Electronic Check (ACH), where you should provide the following details: Bank Routing/Transit Number, Bank Account Number, Check Number, Bank Account Type, First Name, Last Name and to agree to the displayed message.
Stored Card
Add Card
Logged in users have additional option to store credit card used for payment on HPP so it can be used for future payments without leaving Magento store.
To do this, the user has to have an active account created in the Magento store and they need to be logged in before reaching the checkout page. In that case, on the checkout page, user will see an additional option to Store card for later use.
Once you make successful payment, with this option selected, you will save the card used to process payment in both Converge and Magento.
To view card stored in Magento you should navigate to the following screen:
- Magento Store (Logged In) -> My Account -> Stored Payment Methods
Delete card
You have an option to delete stored card directly from Magento, by clicking on the Delete button next to the card, and the card will also be deleted from Converge. If merchant deletes card from Converge, synchronization with Magento does not exists so user will still be able to see the card in Magento with an option to delete it manually.
Pay with stored card
Once the card is stored, you can use it to initiate a payment. To do that, perform the same steps as for HPP payment for the logged in user until Review & Payments screen. New section with the option to select stored cards will be visible and once you select one of the stored cards Place Order button will appear:
Once you click the Place Order button, an API call to Converge is made, and depending on the response we will get:
- Error message -> in case when the payment is declined by Converge
- Newly created order number -> in case when the payment is accepted by Converge
3D Secure
If 3DSecure is enabled within your plug-in configuration, as soon as the customer clicks Place Order a request is sent to ConvergeGateway to check that their card is enrolled in 3DSecure.
If their card is not enrolled in 3Dsecure the authorization will be processed as usual. Data within the authorization message will notify ConvergeGateway that the check was performed and that the cardholder was not participating.
If the cardholder is participating, they will be redirected to their issuing bank’s Access Control Server (ACS). This is the page where the customer enters the passphrase associated with their card. The customer will be redirected to either the success or failure page, depending on whether the 3Dsecure outcome falls under the allowed scenarios.
Wallets
If the terminal supports wallets, the list of available wallets will be displayed at checkout.
PayPal Checkout
After selecting the PayPal Checkout option, you will be redirected to the login page. You can continue as a new or a registered customer.
If you select the Pay with Debit or Credit card option, you can check out as a guest.
If you checkout as a logged in user, clicking on the Log in button will take you to the page where you have the list of payments options.
After choosing a payment method, the new page will review the shipping details and the chosen payment option.
Once you click Continue, you will be redirected to Magento. If the payment was successful, you will see the number of the new order.
PayPal Credit
After selecting the PayPal Credit option, you will be redirected to the login page. You can continue as a new or a registered customer.
If you select the Create an account option, you can check out as a guest.
If you checkout as a logged in user, clicking on the Log in button will take you to the page where you have the list of payments options.
Once you click on continue, you will be redirected to Magento. If the payment was successful, you will see the number of the new order.
View Order Details
After successful payment, order details can be seen by navigating to the following screen:
- Magento Store (Logged In) ->My Account->My Orders->View Order
In case of Authorization Only transaction, Invoice details will not be visible as it has to be created first.
In case of Authorization and Capture transaction invoice details will be visible as the invoice is created automatically for this types of transactions.
Admin View
As a merchant you will be able to perform additional action on already captured transactions directly from Magento Admin page without opening Converge screens.
Cancel
Cancel action is only permitted on Authorization Only transactions in Magento. Once this type of transaction is captured from Store View, the merchant can go to the following screen:
- Magento Admin -> Sales -> Orders -> View Order -> View (actual order #)
Clicking Cancel in Magento deletes the transaction in Converge (similar to the Void action). The transaction is in a cancelled state in Magento which prevents the merchant from making any additional changes to this order, even offline.
Void
Void action is only permitted on Sale transactions in Magento.
Clicking Void in Magento deletes the transaction in Converge, but the status of the order in Magento will stay in ‘processing’ state. Once the transaction is Voided, the connection between Magento and Converge is lost and any further changes to this order are limited to Magento only; no changes to Converge are possible.
Capture (Convert to Sale)
The Capture action is available for Authorization only transactions, as they have to be converted to Sale before Invoice is created for them. To convert Authorization only transactions to Sale you will need to create it, open the order from Magento Admin (same as canceling a payment) and click the Invoice button.
You will be presented with Invoice creation screen. At the bottom of the screen you see a dropdown with 3 options:
- Not Capture
- Capture Offline
- Capture Online
Not Capture
Selecting Not Capture in the dropdown and clicking the Submit Invoice button will create new Invoice in Magento, but nothing will be sent to Converge. The invoice will stay in Pending state, and once invoice is opened you will have Capture button which can be used to actually Capture (convert to Sale) the transaction in Converge.
Capture Offline
Selecting Capture Offline in the dropdown of Invoice creation screen and clicking on Submit Invoice button is used when the merchant wants to manually convert a transaction to Sale (e.g. problem occurred). In Magento, the invoice will be captured with status PAID, but nothing will be sent to Converge, so merchant needs to make sure that transaction in Converge is properly processed. Merchant will no longer have option to make changes to transaction in Converge from Magento screens.
Capture Online
Selecting Capture Online in the dropdown of Invoice creation screen and clicking Submit Invoice is used when the merchant wants to automatically convert an underlying transaction to Sale in Converge. Invoice will be captured with status PAID, but unlike the capture offline action, merchant will still be able to make additional API calls to Converge for this transaction (e.g. refund…).
Partial Capture (Partial Invoice)
Similar to previously explained action for capturing invoice, there is one more functionality where merchants may choose to create several invoices for the same order (when quantity is > 1).
To be able to capture partial invoice you have to either create order with quantity > 1 and it should be created as Authorization Only transaction.
Once created, you should perform all the same steps as for normal Capture action with one small difference where you need to update quantity of each product for each invoice you want to create. you can repeat this process until sum of quantities on all invoices is equal to total original quantity on order.
On invoice creation screen you will see an option to update quantity for each product on the order, which will, after you click on Update Qty’s button, update the amount that will be sent to Converge. You will still have same options as if you were capturing full invoice (Not Capture, Capture Offline and Capture Online).
To view all created invoices and their statuses, navigate to the Invoices tab on selected order.
Manual Settle
All previously explained actions were related to Authorization Only transactions. For settlement you need to have captured transaction meaning that you either create Authorization Only transaction and you convert it to Sale, or you use Authorize and Capture option and create transaction and Invoice automatically.
Each captured transaction will have Invoice in PAID state, so to trigger Settle manually you need to open paid Invoice. Merchant will use this option when he wants to send transaction to settled batch earlier than usual, as usually all Sale transactions are automatically sent to settled batch in Converge at the end of business day.
Once you open Invoice with status PAID, you will see Settle button which will move transaction to Settled Batch in Converge immediately (not waiting end of the day). This action can be performed only once and it is available only during the day when the transaction is captured.
After you click Settle, the transaction is moved to Settled Batch in Converge, and you will see that status in the comment section of the order. An example message is, “Customer NOT NOTIFIED. Invoice is scheduled for Settlement.”
Refund (Credit Memo)
As cancel action is only available for Authorization Only transaction, the merchant will need to capture Credit Memo to return funds to the Credit Card owner.
Once you open invoice with status paid, you will see Credit Memo button to initiate creation of refund transaction. Clicking on the button will open Credit Memo capture screen and on the bottom of that screen you will see two options:
- Refund Offline
- Refund
Refund Offline
This option is used when merchants wants to create Refund transaction manually in Converge, so this will only update Magento flow to match whatever is done manually. Clicking on the button will not send anything to Converge.
Refund Online
This option is used when merchant wants to initiate Refund transaction directly from Magento screen. Once you click on the Refund button, Return transaction with amount indicated on Credit Memo screen will be sent to Converge.
Magento framework is making sure that you are not able to create refund amount greater than total amount on original transaction as well as shipping amount greater than original shipping amount.
Partial Refund
Similar to Partial Invoice merchant has an option to create Partial Refund (Credit Memo) based on the quantity of products on selected invoice.
Once you open invoice (with quantity > 1) and start creating Credit Memo for it, you will be presented with option to update quantity field, which will automatically update amounts (total, shipping) on credit memo screen.
Once updated you will still have an option to perform both Refund Offline and Refund actions as for normal Credit Memo with added functionality that you can have more than one Credit Memo per Invoice.
Magento will make sure that sum of all credit memos created for same invoice is not larger than original amount on invoice.
Order creation in merchant view
As a merchant, you can create an order by navigating to Sales -> Orders and click Create New Order.
Once you have selected the button for creating a new order, you will have to choose a customer from the list or create a new one.
After selecting the customer, you have to select the products that you would like to include in the new order and to click on the “Add Selected Product(s) to Oder” button.
After selecting the product, you will have to review the information for billing and shipping addresses and to define the payment and shipping methods. Once you click on Submit order, the order will be created.
Subscriptions
Merchant View
As a merchant, you can define which products allow subscriptions, view and edit subscription records, and create an order with subscription products.
Product configuration
If the terminal supports subscriptions, you can create a subscription product. Go to Catalog -> Product and create a new product or edit the product you want to turn into a subscription. On the product form, go to the Subscriptions section toward the bottom.
- Enable: This option controls if the product can be purchased as a subscription or not. If set to yes, then the subscription options will take effect after save.
- Allow one-time purchase: The product can be also purchased without subscriptions, by setting this option to yes. Therefore, you can configure a product to support both options: with and without subscriptions.
- Subscription options. If subscriptions are allowed,
- Billing cycle: this option represents the frequency of the recurring payments and can have one of the following values: Daily, Weekly, Biweekly, Semimonthly, Monthly, Bimonthly, Quarterly, Semester, Semiannually and Annually.
- Bill on half: this option is available only if the Billing Cycle is Semimonthly. The values for this field are: 1st and the 15th of the month and 15th and the last day of the month.
- End of Month: this option is available only if the Billing Cycle is Monthly, Bi-Monthly, Quarterly, Semester or Semi-Annually, Annually. The values for this field are: Yes and No.
- Price: this option represents the value that will be added (if positive) or subtracted (if negative) to/from the product price. Please do not define a negative price higher than the product price.
- Price Type: this field has two options: “Fixed” and “Percent.” The default value is “Fixed”.
View subscription table
As a merchant, you can view the list of subscriptions under Sale -> Subscriptions. If you select one of the subscriptions, you can view more details and edit it.
Once you have selected a subscription from the table, the first tab contains details about the subscription and account information. You can edit the billing cycle, bill on half, and end of month fields. The next payment date will be calculated automatically based on changes for the billing cycle, bill on half, end of month and you will be informed about those changes when trying to save the subscription.
The second tab in the detailed view for the subscription contains information about the items ordered, such as product name, price, taxes, shipping, discounts and total amount. This information cannot be edited.
The third tab in the detailed view for the subscription contains information about card, expiration date and the billing address. All fields can be edited.
The fourth tab in the detailed view for the subscription contains information about the shipping address, the shipping method and shipping amount. The fields for the shipping address can be edited.
The fifth tab in the detailed view for the subscription contains information about what happened with the subscription since it was created.
Customer view
Placing an order with subscription products
You can select products with subscriptions from the store and add them to the cart.
When you select one of the subscription options for which the merchant has defined a price, you will see the product price changing based on the price for the selected subscription.
The price change defined for one subscription option applies at product level. Therefore, if you buy more than one product, each product price will be modified with the amount defined for the subscription option.
After choosing a subscription option for the product, the details can be reviewed by opening the shopping cart.
View my subscriptions
Customers can view their subscriptions by navigating to the following screen: Magento Store -> My Account -> My Subscriptions.
After selecting a subscription, you can view the details about the product, billing and shipping addresses, the frequency, start and next payment date, last run and the history.
Get Our FREE Plugin