_images/webgriffe-professional-certified.jpg

Key Client/CartaSì Payment for Magento2

This is the documentation of the Key Client/CartaSì Payment module for Magento2 which integrates the platform with QuiPago payment gateway.

Installation

As for other Magento2 module installation is done through Composer.

Configuration

General configuration is located in Stores -> Configuration -> Sales -> Payment Methods -> Portale di Pagamento QuiPago. Here are the following settings available:

  • Title: allows to specify the name of the payment method which will be shown to the customer during the checkout

  • Enabled: allows to enable/disable the payment method

  • Test Mode Enabled: allows to enable the test mode. This mode is useful to test an end-to-end payment before putting it into production environment. With test mode enable the payment module will interface with QuiPago test environment; in this enviroment all transactions are fake and there is no actual funds transfers. When the test mode is enabled will be used the following parameters:

    • Payment Page URL (test): it’s the URL of the QuiPago’s payment page in test environment. Unless unexpected changes in the specifications this value shuold be set to https://coll-ecommerce.keyclient.it/ecomm/ecomm/DispatcherServlet
    • Merchant Alias (test): is the merchant’s identification code by QuiPago to use in the test environment. Unless unexpected changes in the specifications this value shuold be set to payment_3444153
    • MAC Calculation Secret Key (test): it’s the secret key for MAC calculation to be used in test environment. Unless unexpected changes in the specifications this value shuold be set to TLGHTOWIZXQPTIZRALWKG

    Instead, when the test mode is not enabled the module will interface with the production environment of QuiPago where funds are really transfered. In this case will be used the following parameters:

    • Payment Page URL (production): it’s the URL of the QuiPago’s payment page in production environment. Unless unexpected changes in the specifications this value shuold be set to https://ecommerce.keyclient.it/ecomm/ecomm/DispatcherServlet
    • Merchant Alias (production): is the merchant’s identification code by QuiPago to use in the production environment. This value is comunicated by QuiPago to the merchant upon contract activation.
    • MAC Calculation Secret Key (production): it’s the secret key for MAC calculation to be used in test environment. This value is comunicated by QuiPago to the merchant upon contract activation.
  • Payment Page Language: allows to choose in which language the payment page should be shown

  • Payment Action: allows to choose if payments done with this payment methods should be considered as only authorized or authorized and captured. This option should be set accordingly with authorization/capture mode of QuiPago gateway chosen during contract activation.

  • Encryption Method (for MAC code): allows to choose which encryption algorithm should be used for MAC calculation. With recent contract activations it’s always used the SHA1 method but some old contracts require the MD5 method. If in doubt refer to QuiPago technical support.

  • Debug: allows to enable the debug mode which logs more informations duiring module operation. It’s useful to enable this mode in case of technical issues to better understand what is going wrong.

  • Payment From Applicable Countries e Payment From Specific Countries: allows to specify from which countries this payment method is allowed

  • Minimum Order Total e Maximum Order Total: allows to specify a minimun and/or maximum total for which this payment method is allowed

  • Sort Order: allows to set a sort order number used to determine in which order the payment method will show in the checkout page

Test Mode

Test mode is useful to test an end-to-end payment before putting it into production environment. With test mode enable the payment module will interface with QuiPago test environment; in this enviroment all transactions are fake and there is no actual funds transfers. When the test mode is enabled the payment module will always send a total amount of 1,00 EUR. Use a real credit card data to simulate an unauthorized transacion. Instead, to simulate an authorized tansaction, these data have to be used:

  • Card number: 4000000000000002
  • Expiration: any date in the future
  • CVV2: any 3 digit number
  • Owner: any first and last name

Usage and payment result handling

When a customer completes a checkout using the QuiPago payment method, it will be redirected on an external payment page. In that moment Magento sets the order state to Pending Payment. Then, after that the customer completes the payment filling credit card data, QuiPago sends a server-to-server message to communicate the transaction result. The payment module receives this notification and handles, automatically, the order payment. In caso of an unauthorized transaction the order remains in the Pending Payment state. Instead, in case of an authorized transaction, the order is set, automatically, to the Processing state. In this case, the payment module perfoms further operations which depends on the Payment Action set:

  • In case of Authorize Only, is created an Authorization Transaction tied to the order which tells to Magento that the amount is authorized. But for Magento the order is not paid yet and in fact there is Invoice tied to the order.
  • Instead, in case of Authorize and Capture, is created a Capture Transaction tied to the order and the Invoice is automatically created. In this way, for Magento, the order is completely paid.

Internationalization

The QuiPago payment module is developed with a native user interface in english language. The module also comes with the italian translation (it_IT). It is possibile to translate the interface in other languages using the Magento’s native translation system. For further information refers to Magento’s official documentation.