diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cfa869f8..fa669420 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,13 +1,24 @@ + + # Contributing to Checkout with Vipps for Magento If you want to contribute: Great! No issue or pull request is too small! -# Getting started +## Getting started 1. Make sure you have a GitHub account 1. See the GitHub help pages if you have questions: https://help.github.com -# Contributing +## Contributing Contributing is easy. The steps below is intended to be helpful. Please help us improve it. @@ -23,15 +34,14 @@ Contributing is easy. The steps below is intended to be helpful. Please help us 1. From your fork open a pull request in the correct branch. 1. Once the pull request is approved and merged, you can pull the changes from `master` to your local repo and delete your extra branch(es). -# Report an issue +## Report an issue -If you find a bug in a project you're using (and you don't know how to fix it), have trouble following the documentation or have a question about the project – create an issue! +If you find a bug in a project you're using (and you don't know how to fix it), have trouble following the documentation or have a question about the project – create an issue! -Creating an issue in GitHub is easy, and whatever issue you're having, you're likely not the only one, so others will -find your issue helpful too. For more information on how issues work, check out the official Github issues guide: https://guides.github.com/features/issues/ +Creating an issue in GitHub is easy, and whatever issue you're having, you're likely not the only one, so others will find your issue helpful too. For more information on how issues work, check out the official GitHub issues guide: https://guides.github.com/features/issues/ -# License +## License -The LICENSE file defines the license for the project. An open source project's license informs users what they can and can't do (e.g., use, modify, redistribute), and contributors, what they are allowing others to do. +The LICENSE file defines the license for the project. An open source project's license informs users what they can and can't do (e.g., use, modify, redistribute), and contributors, what they are allowing others to do. -The Vipps Payment Module for Magento 2 is licenced under the MIT licence: https://choosealicense.com/licenses/mit/ +The Vipps Payment Module for Magento 2 is licensed under the MIT license: https://choosealicense.com/licenses/mit/ diff --git a/DEBUG.md b/DEBUG.md deleted file mode 100644 index 15662b62..00000000 --- a/DEBUG.md +++ /dev/null @@ -1,27 +0,0 @@ -# DEBUG - -If you have experienced any issue with Vipps try to enable `Request Profiling` or `Debug` features under vipps payment configuration area: - -`Stores -> Configuration -> Sales -> Payment Methods -> Vipps` - -![Screenshot of Vipps Configuration Area](docs/images/vipps_basic.png) - -## Requests Profiling - -Requests Profiling is a page in Magento admin panel that helps you to track a communication between Vipps and Magento. -You can find the page under `System -> Vipps` - -![Screenshot of Request Profiling Grid](docs/images/request_profiling.png) - - -On the page you can see the list of all requests for all orders that Magento sends to Vipps. -By clicking on a link `Show` in an `Action` column of grid you can find appropriate response from Vipps. - -Using built-in Magento grid filter you could easily find all requests per order that you are interested in. - - -## Debugging Log Files -Logs which are related to vipps payment module are located under two files `{project_root}/var/log/vipps_exception.log` or `{project_root}/var/log/vipps_debug.log`. - - - diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md deleted file mode 100644 index 6db7957c..00000000 --- a/DOCUMENTATION.md +++ /dev/null @@ -1,149 +0,0 @@ -# Prerequisites - -1. Magento 2 installed ([Magento 2.2.x](https://devdocs.magento.com/guides/v2.2/release-notes/bk-release-notes.html), [Magento 2.3.x](https://devdocs.magento.com/guides/v2.3/release-notes/bk-release-notes.html), [Magento 2.4.x](https://devdocs.magento.com/guides/v2.4/release-notes/bk-release-notes.html)) -1. SSL must be installed on your site and active on your Checkout pages. -1. You must have a Vipps merchant account. See [Vipps på Nett](https://www.vipps.no/bedrift/vipps-pa-nett) -1. As with _all_ Magento extensions, it is highly recommended to backup your site before installation and to install and test on a staging environment prior to production deployments. - -# Installation - -## Installation via Composer - -1. Navigate to your [Magento root directory](https://devdocs.magento.com/guides/v2.4/extension-dev-guide/build/module-file-structure.html). -1. Enter command: `composer require vipps/module-payment` -1. Enter command: `php bin/magento module:enable Vipps_Payment` -1. Enter command: `php bin/magento setup:upgrade` -1. Put your Magento in production mode if it’s required. - -## Installation via Marketplace - -Here are steps required to install Payments extension via Component Manager. - -1. Make a purchase for the Vipps extension on [Magento Marketplace](https://marketplace.magento.com/vipps-module-payment.html). -1. From your Magento Admin access System -> Web Setup Wizard page. -1. Enter Marketplace authentication keys. Please read about authentication keys generation. -1. Navigate to Component Manager page. -1. On the Component Manager page click the `Sync button to update your new purchased extensions. -6. Click Install in the Action column for Realex Payments component. -7. Follow Web Setup Wizard instructions. - -# Configuration -The Vipps Payment module can be easily configured to meet business expectations of your web store. This section will show you how to configure the extension via `Magento Admin Panel`. - -1. From Magento Admin navigate to `Store` -> `Configuration` -> `Sales` -> `Payment Methods` section. -1. On the Payments Methods page the Vipps Payments method should be listed together with other installed payment methods in a system. -1. By clicking the `Configure` button, all configuration module settings will be shown. -1. Once you have finished with the configuration simply click `Close` and `Save` button for your convenience. -1. [Clear Magento Cache.](https://devdocs.magento.com/guides/v2.4/config-guide/cli/config-cli-subcommands-cache.html) - -## Add a separate connection for Vipps resources -These settings are required to prevent profiles loss when Magento reverts invoice/refund transactions. - -* Duplicate 'default' connection in app/etc/env.php and name it 'vipps'. It should look like: -``` - 'vipps' => array ( - 'host' => 'your_DB_host', - 'dbname' => 'your_DB_name', - 'username' => 'your_user', - 'password' => 'your_password', - 'model' => 'mysql4', - 'engine' => 'innodb', - 'initStatements' => 'SET NAMES utf8;', - 'active' => '1', - ), -``` -* Add also the following configuration to 'resource' array in the same file: -``` - 'vipps' => array ( - 'connection' => 'vipps', - ), -``` - -## Enable debug mode / requests profiling - -If you have experienced any issue with Vipps try to enable `Request Profiling` and `Debug` features under vipps payment configuration area: - -`Stores -> Configuration -> Sales -> Payment Methods -> Vipps` - -After that, all information related to vipps payment module will be stored into two files `{project_root}/var/log/vipps_exception.log` or `{project_root}/var/log/vipps_debug.log`. - -Requests Profiling is a page in Magento admin panel that helps you to track a communication between Vipps and Magento. -You can find the page under `System -> Vipps` - -![Screenshot of Request Profiling Grid](docs/images/request_profiling.png) - -On the page you can see the list of all requests for all orders that Magento sends to Vipps. -By clicking on a link `Show` in an `Action` column of grid you can find appropriate response from Vipps. - -Using built-in Magento grid filter you could find all requests per order that you are interested in. - -# Settings - -Vipps Payments configuration is divided by sections. It helps to quickly find and manage settings of each module feature: - -1. Basic Vipps Settings. -1. Express Checkout Settings. -1. Additional Settings. - -![Screenshot of Vipps Settings](docs/images/vipps_method.png) - -Please ensure you check all configuration settings prior to using Vipps Payment. Pay attention to the Vipps Basic Settings section, namely `Saleunit Serial Number`, `Client ID`, `Client Secret`, `Subscription Key`. - -For information about how to find the above values, see the [Vipps Developer Portal documentation](https://vippsas.github.io/vipps-developer-docs). - -## Basic Vipps Settings - -![Screenshot of Basic Vipps Settings](docs/images/vipps_basic.png) - -**Environment** - Vipps API mode. Can be *production/develop*. -**Payment Action** - *Authorize*(process authorization transaction; funds are blocked on customer account, but not withdrawn) or *Capture* (withdraw previously authorized amount). -**Order Status** - default order status before redirecting back to Magento. Can be *Pending* or *Payment Review*. -**Debug** - log all actions with Vipps Payment module into `{project_root}/var/log/vipps_debug.log` file *(not recommended in production mode)*. -**Request/Response Profiling** - log all requests/responses to Vipps API into `vipps_profiling` table. - -## Express Checkout Settings - -![Screenshot of Express Vipps Settings](docs/images/express_vipps_settings.png) - -## Additional Settings - -![Screenshot of Vipps Additional Settings](docs/images/vipps_additional_settings.png) - - -**Process type** - whether cancel quote automatically or not. -**Enable Partial Void** - allow cancellation for captured(not refunded) transaction (mostly used to cancel order item). - -# Quote Monitoring - -Quote it is a cart contents in Magento. Theoretically the quote is an offer and if the user accepts it (by checking out) it converts to order. - -When payment has been initiated (customer redirected to Vipps) Magento creates a new record on `Vipps Quote Monitoring` page and starts tracking an Vipps order. -To do that Magento has a cron job that runs by schedule/each 10 min. - -You can find this page under `System -> Vipps` menu section. Under `Store -> Sales -> Payment Methods -> Vipps -> Cancellation` you can find appropriate configuration settings. - -# Order handling -Please refer to Magento official documentation to learn more about [order processing](https://docs.magento.com/user-guide/sales/order-processing.html) - -## How do I capture an order? -When Payment Action is set to Authorize and Capture invoice is created automatically in Magento. In such a case, the Invoice button does not appear, and the order is ready to ship. -For more details about capturing order refer to [Creating an Invoice documentation](https://docs.magento.com/user-guide/sales/invoice-create.html). - -## How do I partially capture an order? -Visit invoice page of your order by click `Invoice` button on order page. In the `Items to Invoice` section, update the `Qty to Invoice` column to include only specific items on the invoice. -Then, click `Update Qty’s` and submit Invoice. - -## How do I cancel an order? -In Magento an order can be canceled in case when all invoices and shipments has been returned. When Vipps Payment transaction has not been captured. -Otherwise, refund should be finished first. Vipps Payment module supports offline partial cancellation. It is used to cancel separate order items. - -## How do I refund an order? -For orders refunding Magento propose [Credit Memo](https://docs.magento.com/user-guide/sales/credit-memos.html) functionality. -Credit Memo allows to make a refund for captured transaction. - -## How do I partially refund an order? -It can be done by specifying `Items to Refund` on `Credit Memo` page and updating `Qty to Refund` field. - -# Additional info - -Please contact by [support](https://github.com/vippsas/vipps-magento/wiki) diff --git a/INSTALL.md b/INSTALL.md deleted file mode 100644 index 225c2fb8..00000000 --- a/INSTALL.md +++ /dev/null @@ -1,106 +0,0 @@ -# Vipps Payment Module for Magento 2: Installation - -# Prerequisites - -1. Magento 2 installed ([Magento 2.2.x](https://devdocs.magento.com/guides/v2.2/release-notes/bk-release-notes.html), [Magento 2.3.x](https://devdocs.magento.com/guides/v2.3/release-notes/bk-release-notes.html), [Magento 2.4.x](https://devdocs.magento.com/guides/v2.4/release-notes/bk-release-notes.html)) -1. SSL must be installed on your site and active on your Checkout pages. -1. You must have a Vipps merchant account. See [Vipps på Nett](https://www.vipps.no/bedrift/vipps-pa-nett) -1. As with _all_ Magento extensions, it is highly recommended to backup your site before installation and to install and test on a staging environment prior to production deployments. - -# Installation via Composer - -1. Navigate to your [Magento root directory](https://devdocs.magento.com/guides/v2.4/extension-dev-guide/build/module-file-structure.html). -1. Enter command: `composer require vipps/module-payment` -1. Enter command: `php bin/magento module:enable Vipps_Payment` -1. Enter command: `php bin/magento setup:upgrade` -1. Put your Magento in production mode if it’s required. - -# Configuration - -The Vipps Payment module can be easily configured to meet business expectations of your web store. This section will show you how to configure the extension via `Magento Admin Panel`. - - -1. From Magento Admin navigate to `Store` -> `Configuration` -> `Sales` -> `Payment Methods` section. -1. On the Payments Methods page the Vipps Payments method should be listed together with other installed payment methods in a system. -1. By clicking the `Configure` button, all configuration module settings will be shown. -1. Once you have finished with the configuration simply click `Close` and `Save` button for your convenience. -1. [Clear Magento Cache.](https://devdocs.magento.com/guides/v2.4/config-guide/cli/config-cli-subcommands-cache.html) - -## Add a separate connection for Vipps resources -These settings are required to prevent profiles loss when Magento reverts invoice/refund transactions. - -* Duplicate 'default' connection in app/etc/env.php and name it 'vipps'. It should look like: -``` - 'vipps' => array ( - 'host' => 'your_DB_host', - 'dbname' => 'your_DB_name', - 'username' => 'your_user', - 'password' => 'your_password', - 'model' => 'mysql4', - 'engine' => 'innodb', - 'initStatements' => 'SET NAMES utf8;', - 'active' => '1', - ), -``` -* Add also the following configuration to 'resource' array in the same file: -``` - 'vipps' => array ( - 'connection' => 'vipps', - ), -``` - -# Settings - -Vipps Payments configuration is divided by sections. It helps to quickly find and manage settings of each module feature: - -1. Basic Vipps Settings. -1. Express Checkout Settings. -1. Additional Settings. - -![Screenshot of Vipps Settings](docs/images/vipps_method.png) - -Please ensure you check all configuration settings prior to using Vipps Payment. Pay attention to the Vipps Basic Settings section, namely `Saleunit Serial Number`, `Client ID`, `Client Secret`, `Subscription Key`. - -For information about how to find the above values, see the [Vipps Developer Portal documentation](https://vippsas.github.io/vipps-developer-docs). - -# Basic Vipps Settings - -![Screenshot of Basic Vipps Settings](docs/images/vipps_basic.png) - -**Environment** - Vipps API mode. Can be *production/develop*. -**Payment Action** - *Authorize*(process authorization transaction; funds are blocked on customer account, but not withdrawn) or *Capture* (withdraw previously authorized amount). -**Order Status** - default order status before redirecting back to Magento. Can be *Pending* or *Payment Review*. -**Debug** - log all actions with Vipps Payment module into `{project_root}/var/log/vipps_debug.log` file *(not recommended in production mode)*. -**Request/Response Profiling** - log all requests/responses to Vipps API into `vipps_profiling` table. - -# Express Checkout Settings - -![Screenshot of Express Vipps Settings](docs/images/express_vipps_settings.png) - -# Addtional Settings - -![Screenshot of Vipps Additional Settings](docs/images/vipps_additional_settings.png) - - -**Process type** - whether cancel quote automatically or not. -**Enable Partial Void** - allow cancellation for captured(not refunded) transaction (mostly used to cancel order item). - - -# Quote Monitoring - -Quote it is a cart contents in Magento. Theoretically the quote is an offer and if the user accepts it (by checking out) it converts to order. - -When payment was initiated (customer was redirected to Vipps) Magento creates a new record on `Vipps Quote Monitoring` page and starts tracking an Vipps order. -To do that Magento has a cron job that runs by schedule/each 10 min. - -You can find this page under `System -> Vipps` menu section. Under `Store -> Sales -> Payment Methods -> Vipps -> Cancellation` you can find appropriate configuration settings. - -# Support - -Magento is an open source ecommerce solution: https://magento.com - -Magento Inc is an Adobe company: https://magento.com/about - -For Magento support, see Magento Help Center: https://support.magento.com/hc/en-us - -Vipps has a dedicated team ready to help: magento@vipps.no diff --git a/README.md b/README.md index 65c5197e..e2c6bd03 100644 --- a/README.md +++ b/README.md @@ -1,60 +1,43 @@ - + # Vipps Payment Module for Magento 2 +![Support and development by Vaimo ](./docs/images/vaimo.svg#gh-light-mode-only)![Support and development by Vaimo](./docs/images/vaimo_dark.svg#gh-dark-mode-only) -## Magento - -Magento is an open-source e-commerce platform written in PHP: https://magento.com. -For Magento support, please see the Magento Help Center: https://support.magento.com/hc/en-us. -Magento Inc is an Adobe company: https://magento.com/about. - -## About Vipps Payment for Magento 2 - -Vipps Payment offers a familiar and convenient buying experience that can help your customers spend more time shopping and less time checking out. - -Vipps Payment is used by large and small companies. From years of shopping safely with Vipps, customers trust their personal information will remain secure. Businesses have the reassurance of our advanced fraud protection and payment protection policy. - -For more information about Vipps Payment and Magento 2, please visit [Vipps Payment for Magento](https://vipps.no/produkter-og-tjenester/bedrift/ta-betalt-paa-nett/ta-betalt-paa-nett/magento/) site. - - -### Prerequisites -* Magento 2.2.x, Mageton 2.3.x, Magento 2.4.x - * [Magento 2 System Requirements](http://devdocs.magento.com/magento-system-requirements.html) -* SSL is installed on your site and active on the Checkout page -* Supported protocols HTTP1/HTTP1.1 - * Magento relies on the [Zend Framework](https://framework.zend.com), which does not support HTTP/2. - * HTTP/1.1 must therefore be "forced", typically by using [CPanel](https://documentation.cpanel.net/display/EA4/Apache+Module%3A+HTTP2) or similar. -* A verified Vipps Payment merchant account - [sign up here](https://vippsbedrift.no/signup/vippspanett/) - -### Installation and Configuration - -Please follow the instructions in [INSTALL.md](INSTALL.md) - -### Documentation - -Please see our [Documentation](https://github.com/vippsas/vipps-magento/wiki/Documentation) - -### FAQ - -Please see our [FAQ section](https://github.com/vippsas/vipps-magento/wiki/FAQ) +![Vipps](./docs/images/vipps.png) *Available for Vipps.* -### Customization +![MobilePay](./docs/images/mp.png) *Available for MobilePay in Finland and Denmark in Q1 2024.* -Please see our [Customization section](https://github.com/vippsas/vipps-magento/wiki/Customization) +*This plugin is built and maintained by [Vaimo](https://www.vaimo.com/) and is hosted on [GitHub](https://github.com/vippsas/vipps-magento).* + +💥 Please use the plugin pages on [https://developer.vippsmobilepay.com](https://developer.vippsmobilepay.com/docs/plugins-ext/magento/). 💥 + +Vipps offers a familiar and convenient buying experience that can help your customers spend more time shopping and less time checking out. -### Vipps Login module for Magento +Vipps is used by large and small companies. From years of shopping safely with Vipps, customers trust their personal information will remain secure. Businesses have the reassurance of our advanced fraud protection and payment protection policy. -Please see: https://github.com/vippsas/vipps-login-magento +Information about ordering the plugin is available at [Vipps for Magento](https://vipps.no/produkter-og-tjenester/bedrift/ta-betalt-paa-nett/ta-betalt-paa-nett/magento/). -### Vipps Payment module for Magento 1 +The *Vipps Payment Module for Magento 2* plugin is available for download at . -Please see: https://github.com/vippsas/vipps-magento-v1 +## Documentation -### Vipps contact information +The [Vipps Payment Module for Magento 2: User Guide](./docs/documentation.md) contains: -Please follow this [instruction](https://github.com/vippsas/vipps-developers/blob/master/contact.md) to contact us. +* [Installation](./docs/documentation.md#installation) +* [Configuration](./docs/documentation.md#configuration) +* [Debugging](./docs/documentation.md#enable-debug-mode--requests-profiling) +* [Customization](./docs/documentation.md#customization) -For plugin related issues please submit an issue on GitHub [for Magento 2](https://github.com/vippsas/vipps-magento) or contact integration@vipps.no. +See also the [Frequently asked questions](./docs/FAQ.md) page. diff --git a/docs/FAQ.md b/docs/FAQ.md new file mode 100644 index 00000000..1107e481 --- /dev/null +++ b/docs/FAQ.md @@ -0,0 +1,95 @@ + + +# Frequently asked questions + +## How do I capture an order? + +When *Payment Action* is set to *Authorize* and *Capture*, the invoice is created automatically in Magento. In such a case, the *Invoice* button does not appear, and the order is ready to ship. +For more details about capturing orders, refer to [Creating an Invoice documentation](https://docs.magento.com/user-guide/sales/invoice-create.html). + +## How do I partially capture an order? + +Visit the invoice page of your order by clicking the *Invoice* button on the order page. In the *Items to Invoice* section, update the *Qty to Invoice* column to include only specific items on the invoice. +Then, click *Update Qty’s* and submit *Invoice*. + +## How do I cancel an order? + +In Magento, an order can be canceled in the case where all invoices and shipments have been returned and the Vipps Payment transaction has not been captured. +Otherwise, the refund should be finished first. The Vipps Payment module supports offline partial cancellation. It is used to cancel separate order items. + +## How do I refund an order? + +For orders refunding Magento propose [Credit Memo](https://docs.magento.com/user-guide/sales/credit-memos.html) functionality. +Credit Memo allows you to make a refund for captured transaction. + +## How do I partially refund an order? + +You can partially refund an order by specifying *Items to Refund* on the *Credit Memo* page and updating the *Qty to Refund* field. + +## How can I get help with Vipps for Magento? + +Vipps for Magento is developed by [Vaimo](https://www.vaimo.com), and the same developers who made +the plugin also help with improvements, maintenance and developer assistance. + +If you are having a problem, please make sure that you are using the latest version: + + +The best way to report a problem (or ask a question) is to use GitHub's built-in "issue" functionality: +[Issues](https://github.com/vippsas/vipps-magento/issues). + +### How can I get help with Vipps (unrelated to Magento)? + +See: [How to contact Vipps](https://developer.vippsmobilepay.com/docs/contact/). + +## Why does it take so long after purchase before orders are created in Magento? + +Vipps depends on a proper cron job configuration for background processing of orders. +Failure to set it up properly means Vipps will not function as expected. + +## Why are some orders missing in Magento? + +This scenario is possible for express payment flow. Unlike of regular payment, order is not created before redirecting to +Vipps Landing page. If the transaction was successfully initiated by client, a new record +with a quote ID and reserved order ID will be created in DB table `vipps_quote`. This can be helpful to find a status of a transaction. + +## How do I enable Vipps Payment for Klarna Checkout + +To enable Vipps Payment method for Klarna Checkout, it should be chosen in the list of external payment methods in the appropriate Klarna Checkout settings section. + +![Screenshot of Klarna Checkout settings](images/klarna_checkout.png) + +### Why am I seeing a strange page with url printed? + +Right after pressing *Place Order*, the client may see the page with message +`{"url":"https:\/\/apitest.vipps.no\/dwo-api-application\/v1\/****"}` + +**Solution:** Update your Vipps module to the latest version. + +## How to enable debug mode / requests profiling + +If you have experienced any issue with Vipps try to enable *Request Profiling* and *Debug* features under the Vipps payment configuration area: + +*Stores -> Configuration -> Sales -> Payment Methods -> Vipps* + +![Screenshot of Vipps Configuration Area](images/vipps_basic_v2.png) + +After that, all information related to Vipps payment module will be stored into two files `{project_root}/var/log/vipps_exception.log` or `{project_root}/var/log/vipps_debug.log`. + +Requests Profiling is a page in Magento admin panel that helps you to track a communication between Vipps and Magento. +You can find the page under `System -> Vipps` + +![Screenshot of Request Profiling Grid](images/request_profiling.png) + +On the page, you can see the list of all requests for all orders that Magento sends to Vipps. +By clicking *Show* in an *Action* column of grid you can find appropriate response from Vipps. + +Using built-in Magento grid filter you could find all requests per order that you are interested in. + diff --git a/docs/documentation.md b/docs/documentation.md new file mode 100644 index 00000000..27425852 --- /dev/null +++ b/docs/documentation.md @@ -0,0 +1,238 @@ + + +# User Guide + +## Prerequisites + +* Magento 2 installed ([Magento 2.2.x](https://devdocs.magento.com/guides/v2.2/release-notes/bk-release-notes.html), [Magento 2.3.x](https://devdocs.magento.com/guides/v2.3/release-notes/bk-release-notes.html), [Magento 2.4.x](https://devdocs.magento.com/guides/v2.4/release-notes/bk-release-notes.html)) + * [Magento 2 System Requirements](https://experienceleague.adobe.com/docs/commerce-operations/installation-guide/system-requirements.html) +* SSL must be installed on your site and active on your Checkout pages. +* You must have a Vipps merchant account. [Sign up here](https://vippsbedrift.no/signup/vippspanett/). +* As with *all* Magento extensions, it is highly recommended backing up your site before installation and to install and test on a staging environment prior to production deployments. +* Supported protocols HTTP1/HTTP1.1 + * Magento relies on the [Zend Framework](https://framework.zend.com), which does not support HTTP/2. + * HTTP/1.1 must therefore be "forced", typically by using [CPanel](https://documentation.cpanel.net/display/EA4/Apache+Module%3A+HTTP2) or similar. + +## Installation + +### Installation via Composer + +1. Navigate to your [Magento root directory](https://devdocs.magento.com/guides/v2.4/extension-dev-guide/build/module-file-structure.html). +1. Enter command: `composer require vipps/module-payment` +1. Enter command: `php bin/magento module:enable Vipps_Payment` +1. Enter command: `php bin/magento setup:upgrade` +1. Put your Magento in production mode, if required. + +### Installation via Marketplace + +Here are steps required to install Payments extension via Component Manager. + +1. Make a purchase for the Vipps extension on [Magento Marketplace](https://marketplace.magento.com/vipps-module-payment.html). +1. From your Magento Admin, access *System* > *Web Setup Wizard* page. +1. Enter Marketplace authentication keys. Please read about authentication keys generation. +1. Navigate to *Component Manager* page. +1. On the *Component Manager* page, click the *Sync* button to update your new purchased extensions. +1. Click *Install* in the *Action* column for Realex Payments component. +1. Follow *Web Setup* Wizard instructions. + +## Configuration + +The Vipps Payment module can be easily configured to meet business expectations of your web store. This section will show you how to configure the extension via the *Magento Admin Panel*. + +1. From Magento *Admin*, navigate to *Store* > *Configuration* > *Sales* > *Payment Methods* section. +1. On the *Payments Methods* page, the *Vipps Payments* method should be listed together with other installed payment methods in a system. +1. By clicking the *Configure* button, all configuration module settings will be shown. +1. Once you have finished the configuration, click *Close* and *Save* button. +1. [Clear Magento Cache](https://devdocs.magento.com/guides/v2.4/config-guide/cli/config-cli-subcommands-cache.html). + + +### Add a separate connection for Vipps resources + +These settings are required to prevent the loss of profiles when Magento reverts invoice or refund transactions. + +* Duplicate the `default_connection` in `app/etc/env.php` and name it 'vipps'. It should look like: + +```php +'vipps' => [ + 'host' => 'your_DB_host', + 'dbname' => 'your_DB_name', + 'username' => 'your_user', + 'password' => 'your_password', + 'model' => 'mysql4', + 'engine' => 'innodb', + 'initStatements' => 'SET NAMES utf8;', + 'active' => '1', +], +``` + +* Then, add the following configuration to the `resource` array in the same file: + +```php +'vipps' => [ + 'connection' => 'vipps', +], +``` + +## Settings + +The Vipps Payments configuration is divided by sections. It helps to quickly find and manage settings of each module feature: + +* [Basic Settings](#basic-settings) +* [Checkout settings](#checkout-settings) +* [Express Checkout Settings](#express-checkout-settings) +* [Cancellation Settings](#cancellation-settings) + +Ensure that you check all configuration settings before using Vipps Payment. Pay special attention to the [Basic Settings](#basic-settings) section. + +### Basic Settings + +Basic Settings include: + +* *Environment* - Vipps API mode, which can be *Production* or *Develop*. +* *Payment Action* - *Authorize* (process authorization transaction; funds are blocked on customer account, but not withdrawn) or *Capture* (withdraw previously authorized amount). +* *Debug* - Log all actions with Vipps Payment module into `{project_root}/var/log/vipps_debug.log` file *(not recommended in production mode)*. +* *Order Status* - Default order status before redirecting back to Magento. Can be *Pending* or *Payment Review*. +* *Request/Response Profiling* - Log all requests/responses to Vipps API into `vipps_profiling` table. +* *Merchant Serial Number* - ID number for the sales unit. +* *Client ID* - Client ID for the sales unit (the "username"). +* *Client Secret* - Client secret for the merchant (the "password"). +* *Subscription Key* - Subscription key for the API product. + +See [API keys](https://developer.vippsmobilepay.com/docs/common-topics/api-keys/) for information about how to find the values for *Merchant Serial Number*, *Client ID*, *Client Secret*, and *Subscription Key*. + +![Screenshot of Basic Vipps Settings](images/vipps_basic_v2.png) + +### Checkout Settings + +Vipps payment will be unavailable when disallowed shipping methods are selected on checkout. These methods are also unavailable on the Express Checkout page. + +![Screenshot of Checkout Settings](images/checkout_settings.png) + +### Express Checkout Settings + +![Screenshot of Express Vipps Settings](images/express_vipps_settings.png) + +### Cancellation Settings + +The Cancellation Settings include: + + - *Cart Persistence* - If set to *Yes* and client cancels an order on Vipps side, the cart will still contain the recently added products. + - *Number of Attempts* - The number of failed order placement attempts allowed before the order will be canceled. + - *Storage Period* - The number of days to store the quote information. Use `0` to keep all records. + - *Inactivity Time* - (Developers only) The number of minutes that customer is idle before the Vipps order will be canceled in Magento. + - *Processing Type* - Deprecated setting that will be removed in future releases. (Should be set to "Automatic"). + +![Screenshot of Checkout Settings](images/cancellation_settings.png) + + +## Order processing + +Please refer to the Magento official documentation to learn more about [order processing](https://docs.magento.com/user-guide/sales/order-processing.html) and [order management](https://docs.magento.com/m2/ce/user_guide/sales/order-management.html). + +### Quote Processing Flow + +The quote is an offer. The user accepts the offer when checking out, and it is converted to an order. + +When the payment has been initiated (customer redirected to Vipps), Magento creates a new record on the *Quote Monitoring* page and starts tracking a Vipps order. +To do that, Magento has a cron job that runs by schedule/each 10 minutes. + +You can find this page under the *System* > *Vipps* menu. For the cancellation configuration settings, see *Store* > *Sales* > *Payment Methods* > *Vipps* > *Cancellation*. + +1. When a payment is initiated, a new record is created on the Vipps *Quote Monitoring* page with status `New`. + - For a "Regular Payment", the order is immediately placed on the Magento side with status *new*, *pending*, or *payment review*, depending on the configuration. + +1. Magento regularly (by cron) polls Vipps for orders to process. +1. When an order is accepted on Vipps side, Magento tries to place the order and marks a record as `Placed` + - For a "Regular Payment", the Magento order is moved to status `Processing`. + +1. When an order is cancelled on the Vipps side, Magento marks such record as `Cancelled`. + - The order is canceled on the Magento side, if it was previously placed. + +1. If an order has not been accepted on the Vipps side within some period of time, it marked as expired. Magento subsequently marks the order as `Expired`. + - The order is canceled on the Magento side, if it was previously placed. + +1. If an order has not been yet been accepted on the Vipps side and has not yet expired, Magento marks it as `Processing`. An appropriate message is added on *Record details* page. +1. If an order has been accepted on the Vipps side, but an error has occurred during order placement on Magento side, such record marks as `Processing`. An appropriate message is added on record details page. +1. Magento will attempt to process a record three times. After it fails three times, the record is marked as `Place Failed`. +1. It is possible to specify that Magento must cancel a Vipps order automatically when an appropriate Magento quote has failed, so that client's money released. See *Store* > *Sales* > *Payment Methods* > *Vipps* > *Cancellation*. +1. If it is specified that Magento must cancel all failed quotes, then Magento fetches all records marked as `Place Failed`, cancels them, and marks them as `Cancelled`. + +Here is a diagram of the process: + +![Screenshot of Quote Processing Flow](images/quote-monitoring-flow.png) + + +## Quote Monitoring Tool + +From version 1.2.1, we released *Quote Monitoring*. + +Quote Monitoring simplifies detection of failed order placement and identifies the root causes of failures. + +The monitoring tool is located under *System* > *Vipps Payment* > *Quote Monitoring*. +This page displays all orders that were attempted to be placed. +Each record in the list provides detailed information about order creation flow: current status, list of attempts, each attempt results. + +Monitoring quote statuses include: + +* *New* - Payment is initiated on the Vipps side. +* *Processing* - Magento has started processing for initiated payment. +* *Placed* - The order has been placed. +* *Expired* - The customer has not approved payment for some time. +* *Placement Failed* - All attempts were unsuccessful. +* *Canceled* - The payment has been canceled. + Cancellation can be initiated by the customer in Vipps or manually/automatically by *Magento for Quotes* in *Placement Failed* status. +* *Cancel Failed* - The payment could not be canceled. Record in this status and require admin/developer interaction. + +## Enable debug mode / requests profiling + +If you have experienced any issue with Vipps, try to enable *Request Profiling* and *Debug* features in the Vipps payment configuration area: *Stores* > *Configuration* > *Sales* > *Payment Methods* > *Vipps*. + +![Screenshot of Vipps Configuration Area](images/vipps_basic.png) + +After that, all information related to the Vipps payment module will be stored into two files: + +* `{project_root}/var/log/vipps_exception.log` +* `{project_root}/var/log/vipps_debug.log` + +*Requests Profiling* is a page in the Magento *Admin panel* that helps you to track a communication between Vipps and Magento. +You can find the page under *System* > *Vipps*. + +![Screenshot of Request Profiling Grid](images/request_profiling.png) + +On the page, you can see the list of all requests for all orders that Magento sends to Vipps. +By clicking on *Show* in the *Action* column of the grid, you can find the appropriate response from Vipps. + +By using the built-in Magento grid filter, you can find all requests per order that you are interested in. + +## Tax Calculation for Express Checkout + +When enabling the Express checkout payment in the configuration area, you may see a notification at the top of admin panel saying: +![Express Checkout notice](images/express-checkout-notice.png) + +This means that you should change Tax Calculation Settings to be based on **Shipping Origin**: +![Tax Calculation Settings](images/tax-origin-settings.png) + +Otherwise, an issue with calculating delivery cost might occur. + +## Customization + +The Magento platform provides various ways to create custom flows that are difficult and unnecessary to describe in one page. Here we provide a guide and references that can help you to understand the general idea of where to start. + +For example, to customize the *Order Success* page, you can: + +* Use an existing 3rd party module or by doing the customization yourself. Visit [Magento Marketplace](https://marketplace.magento.com/) to see which 3rd party solutions are available. + +* Do the customization yourself. Refer to [Magento Frontend Developer Guide](https://devdocs.magento.com/guides/v2.4/frontend-dev-guide/bk-frontend-dev-guide.html). + + The following code is related to the *Order Success* page: + + - Template: `magento/module-checkout/view/frontend/templates/success.phtml` + - Layout: `magento/module-checkout/view/frontend/layout/checkout_onepage_success.xml` diff --git a/docs/images/cancellation_settings.png b/docs/images/cancellation_settings.png new file mode 100644 index 00000000..4ec6fd57 Binary files /dev/null and b/docs/images/cancellation_settings.png differ diff --git a/docs/images/checkout_settings.png b/docs/images/checkout_settings.png new file mode 100644 index 00000000..2891b537 Binary files /dev/null and b/docs/images/checkout_settings.png differ diff --git a/docs/images/klarna_checkout.png b/docs/images/klarna_checkout.png new file mode 100644 index 00000000..7ef86b34 Binary files /dev/null and b/docs/images/klarna_checkout.png differ diff --git a/docs/images/mp.png b/docs/images/mp.png new file mode 100644 index 00000000..749161b3 Binary files /dev/null and b/docs/images/mp.png differ diff --git a/docs/images/vaimo.svg b/docs/images/vaimo.svg new file mode 100644 index 00000000..eeb9bb6d --- /dev/null +++ b/docs/images/vaimo.svg @@ -0,0 +1,64 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/images/vaimo_dark.svg b/docs/images/vaimo_dark.svg new file mode 100644 index 00000000..e4cb8ba3 --- /dev/null +++ b/docs/images/vaimo_dark.svg @@ -0,0 +1,64 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/images/vipps.png b/docs/images/vipps.png new file mode 100644 index 00000000..c97ee051 Binary files /dev/null and b/docs/images/vipps.png differ diff --git a/docs/images/vipps_basic_v2.png b/docs/images/vipps_basic_v2.png new file mode 100644 index 00000000..8e662cf7 Binary files /dev/null and b/docs/images/vipps_basic_v2.png differ