_images/webgriffe-professional-certified.jpg

MonetaWeb 2.0 payment method for Magento 2

This is the documentation for the MonetaWeb 2.0 module for Magento 2, which integrates Magento 2 with the aforementioned payment gateway. This module allows one to accept both “standard” credit card payments and also payments using the “MyBank” system.

Installation

The installation procedure could be “wizard” or “manual”. If the module has been purchased on the Magento Marketplace, both installation procedures are available. Instead, if the module has been purchased on the Webgriffe Store, only the “manual” procedure is available.

Wizard installation (only Magento Marketplace)

If you purchesed the module on Magento Marketplace, you have two possibilities:

  • Installation via Magento Component Manager

    If not already done, enter your Magento Marketplace credentials under System -> Web Setup Wizard -> System Configuration and follow the instructions.

    When you’re done you can access into the Component Manager at System > Web Setup Wizard > Component Manager, you should see the newly puchased extension under the New Purchases section, choose then Install to install the extension. More information are available at http://devdocs.magento.com/guides/v2.1/comp-mgr/module-man/compman-main-pg.html.

  • Command line installation with Composer

    First of all ensure that the repo.magento.com repository has been added to the composer.json file and the associated authentication keys have been configured. More information on how to get the authentication keys and how to set them are available at http://devdocs.magento.com/guides/v2.0/install-gde/prereq/connect-auth.html and at https://getcomposer.org/doc/articles/http-basic-authentication.md.

    So the auth.json file should be like this:

    {
        "http-basic": {
            "repo.magento.com": {
                "username": "<MAGENTO_MARKETPLACE_PUBLIC_KEY>",
                "password": "<MAGENTO_MARKETPLACE_PRIVATE_KEY>"
            }
        }
    }
    

    Now is it possible to execute the following command

    composer require webgriffe/module-monetaweb2
    

    In case of errors such as “unable to find webgriffe/module-monetaweb2”, please make sure that the authentication keys are correct, that the file is in the correct folder and that, more generally, the file is being used by Composer.

    And then run Magento setup upgrade script:

    $ php bin/magento setup:upgrade
    

    Clear the cache:

    $ php bin/magento cache:clean
    

    And recompile the dependency injection data:

    $ php bin/magento setup:di:compile
    

Manual installation (Magento Marketplace and Webgriffe Store)

Once you downloaded the module’s ZIP file from Magento Marketplace or Webgriffe Store, follow these steps:

  • Create an artifacts folder inside your Magento’s root folder.

    $ mkdir artifacts
    
  • Deny public access to this folder by properly configuring your webserver (for example, if you use Apache, put an .htaccess file with the content Deny from all).

    $ echo "Deny from all" > artifacts/.htaccess
    
  • Copy the module’s ZIP file inside the artifacts folder (do not extract the contents of the zip file, just move the whole archive there)

  • Add the artifacts folder as Composer repository

    $ composer config repo.artifacts "artifact" "artifacts/"
    
  • Add the module to your Magento’s dependencies using Composer

    $ composer require webgriffe/module-monetaweb2
    

    If you receive an error saying that the module can’t be found, open your composer.json file, locate the repositories section and edit the file to make sure that artifacts is the first item in that section. Save the file and try again with the composer require webgriffe/module-monetaweb2 command.

  • Launch the Magento’s setup:upgrade script

    $ php bin/magento setup:upgrade
    
  • Clear the cache:

$ php bin/magento cache:clean
  • Rrecompile the dependency injection data:
$ php bin/magento setup:di:compile

Configuration

The module configuration can be found in Stores -> Configuration -> Sales -> Payment Methods. The configuration is split in three sections: Setefi MonetaWeb 2.0 Payment Gateway (for generic payment settings that are common to all Setefi payment methods), Setefi MonetaWeb 2.0 Payment Gateway - Credit card payment (for settings specific to the credit card payment method) and Setefi MonetaWeb 2.0 Payment Gateway - MyBank payment (for settings specific to the MyBank payment method). These are the available configuration options (spread across the three sections mentioned above):

  • Enabled: allows one to enable or disable the payment method. This is specific for the credit card or Mybank payment method, so that it is possible to leave just one or the other enabled if so desired. Please note, however, that if a user starts a Mybank payment, then he/she will be presented with the option to switch back to the credit card payment when on the payment page provided by the bank. This behaviour can be tested by using the module in “test” mode and starting a Mybank payment. If this is not desired, please contact the Setefi technical support.

  • Title: allows one to indicate the name of the payment method that will be shown during the checkout process.

  • Test Mode Enabled: enables and disables test mode. This mode is useful to test the payment flow before going live with the module, as when this mode is enabled the module will use the test environment provided by Setefi. In this environment every transaction is fake and there is no real money transfer involved. When test mode is enabled, the following fields will be used:

    • Test Gateway URL URL that the module sends the initial request to in order to start the payment procedure when test mode is enabled. This value should always be https://test.monetaonline.it/monetaweb/payment/2/xml
    • Test Terminal ID: This identifies the test merchant in MonetaWeb 2.0’s systems. This should always be 99999999.
    • Test Terminal Password: A password used to check that test transactions are authentic. This should always be 99999999.

    On the other hand, when test mode is not enabled, the module will use MonetaWeb 2.0’s production environment where transactions are real. In production mode the following values will be used:

    • Gateway URL: URL that the module sends the initial request to in order to start the payment procedure when test mode is disabled. This value should always be https://www.monetaonline.it/monetaweb/payment/2/xml
    • Terminal ID: This identifies the merchant in MonetaWeb 2.0’s systems. This data is provided by Setefi when the contract is signed.
    • Terminal Password: A password provided by Setefi and used to check that transactions are authentic.
  • Action: This field allows one to indicate which action to execute when a customer places an order:

    • Authorize and Capture: this value immediately executes the payment transaction, immediately transferring the fulds from the customer’s credit card to the merchant’s account.
    • Authorize Only: this action only “authorizes” the fund transfer, but does not actually execute the transfer. In essence the funds are locked on the customer’s card, but not transferred. This transfer must be done manually at a later time, either by generating an invoice in Magento selecting the “Capture online” action or from the MonetaWeb 2.0 backoffice. The gateway supports the possibility of capturing an amount that is lower than what was authorized, but the capture cannot be multiple for a single authorization. Therefore if one tries to generate more than one invoice for a single order, only the first one will capture its funds.
  • Debug: this enables debug mode, used to store additional information during the module’s operation. It’s especially useful to enable this mode in case of technical problems to better understand what isn’t working.

  • Language: this field allows to indicate which language MonetaWeb 2.0 pages use.

  • Currency: this field allows one to indicate the currency that the payment should be made into. Notice that the module does not attempt any conversion of the payment amount provided by Magento, therefore the value of this configuration field MUST match the currency that is set in each Magento website.

  • Cancel Order on Failure: this field allows to cancel the order if the payment fails or is canceled (both in case of technical issues and if the user intentionally cancels the payment).

  • Payment From Applicable Countries and Payment From Specific Countries: these are used to specify whether the MonetaWeb 2.0 payment method will be available for every country in the world or only from selected countries.

  • Minimum Order Total and Maximum Order Total: used to indicate whether the MonetaWeb 2.0 payment method must be available only for orders having a total amount smaller and/or grater than some specified values.

  • Sort Order: This sets a number that will be used to sort the payment methods in the checkout. This is an ascending order sort, so that a payment method with a lower value in this field will be shown above another method with a higher value.

Test mode

Test mode is useful to check the payment flow before going live, as the module will use Setefi’s test environment. In this environment all transactions are fake and there is no transfer of real money. The payment flow includes a server to server call by Setefi to the merchant’s server in order to communicate the transaction outcome. This means that in order to use the MonetaWeb 2.0 module (both in test and production mode), the server that the module is installed on must be reachable through a public URL without any kind of authentication. As a minimum the monetaweb2/notify/index URL must be publicly accessible.

It is possible to use these credit cards to make the needed tests in the test environment. In the test environment any other credit card will produce a negative outcome.

Type Number Expiration CVV 3D Secure Verification 3D Secure password
VISA 4471490099993805 01/2022 771 ENROLLED valid
VISA 4349940199996900 01/2022 994 ENROLLED valid
VISA 4163640001916707 01/2019 659 NOT ENROLLED  
VISA 4163640001927142 01/2019 369 NOT ENROLLED  
MASTERCARD 5167950099913810 01/2022 151 ENROLLED valid
MASTERCARD 5398320199997454 01/2020 728 ENROLLED valid
MASTERCARD 5167950099913828 01/2022 921 ENROLLED valid
MASTERCARD 5246949906176152 01/2019 266 NOT ENROLLED  
AMEX 375200000000003 12/2018 5861 NOT SUPPORTED  
DINERS 36961903000009 11/2018 553 NOT SUPPORTED  

In case it becomes necessary to do some tests and these cards are no longer valid due to their expiration date, please refer to the MonetaWeb technical documentation, which can be downloaded from the “documentation” section in the MonetaWeb backoffice. In the appendix A there should be a table with the up-to-date list of test credit cards.

It is also possible to test Mybank payments using test mode. To do so select the appropriate option to initiate a Mybank payment when in the Magento checkout and then, when on the bank payment page, choose one of the following banks from the list:

  • Fakebank_AUTHORISED Simulates a transaction that was correctly authorized
  • Fakebank_ERROR: Simulates an error
  • Fakebank_AUTHORISINGPARTYABORTED Simulates a payment that was aborted by the payer
  • Fakebank_PENDING Simulates a transaction that is still in progress
  • Fakebank_TIMEOUT Simulates a transaction that was not completed before the timeout expired (by default 15 minutes)

Using any other bank from the list while in test mode will not work. After selecting one of these test banks, follow the on screen instructions and in the end you will be redirected to the Magento site.

Usage and payment outcome handling

When a customer completes the checkout of an order and chooses the MonetaWeb 2.0 payment method, he/she is redirected to the MonetaWeb 2.0 payment page. At this time Magento sets the order state as Pending Payemnt. After the customer has completed the payment by entering the credit card data, the Setefi server contacts the notification URL that the module provides in order to communicate the outcome of the transaction. If the transaction is succesful, then the order is marked as paid, it passes in the Processing state and the customer is redirected to the checkout/onepage/success URL. In case of errors, on the other hand, the order remains in the previous state and the customer is redirected to the checkout/onepage/failure URL.

In case of a positive outcome, additional operations are performed depending on what Action is set in the module configuration:

  • In case of Authorize and Capture then a Transaction is created for the order, and this transaction is of Capture type. Also an Invoice is automatically generated. This way, for Magento, the order is completely paid.
  • In case of Authorize Only on the other hand, a Transaction of type Authorization is created for the order, indicating that the payment amount was authorized. For Magento, however, the order is not yet paid and indeed there is no Invoice for the order.

If, on the other hand, the payment outcome reports an error, then the order remains in whatever state it was before the payment attempt, unless the option Cancel Order on Failure (see Configuration section) is enabled, in which case the order will be moved in Canceled status. Both in case of a positive and negative outcome, the data returned by Setefi is saved in a comment to the Magento order, so that it’s easily possible to check the cause of any error.

As mentioned earlier, if a user starts a Mybank payment, it’s then possible for the user to change his/her mind and switch to a standard credit card payment. Should this happen, the module will initially use the Mybank payment method for the order. When the server-to-server notification (sent by Setefi to the Magento website) is received, if this notification indicates that the payemnt method was changed, then the module will update the order with the new payment method and add a special comment to indicate what happened.

Internationalization

The MonetaWeb 2.0 payment module is developed with a native user interface in English (en_US). The module also includes the italian language translation (it_IT). It is possible to translate the interface in new languages using the Magento 2 translation system. For further information about this system please refer to the official Magento 2 documentation.