Resursbank Checkout module for Magento 2.
A one-step checkout module from Resurs Bank.
cd ~/path/to/your/magento/installation
composer require resursbank/checkout
Go into your admin panel, and navigate to Stores -> Configuration -> Resurs Bank -> Checkout.
You need to specify your Username
and Password
under the API Settings
.
Specify the Unit Measure
under API Settings
(it can be anything you like).
Select the appropriate Envrionment
under API Settings
(Test
or Production
depending on
your intent).
In General Settings
, press the Fetch payment methods
button.
In Callback Settings
, press the Update callbacks
button.
If you have minified JavaScript/CSS please be sure to reload it after installing the module to ensure the checkout page will function and appear properly.
If you are using any cache/performance services such as memcache or Zend_OPcach, please read the related chapters in the Debug section to ensure that no cache interferes with your installation.
This will install the packages resursbank/checkout
and resursbank/ecomphp
.
NOTE: You need the SOAP extension for your version of PHP (for example php5-soap or php7.0-soap).
The extension is used by resursbank/ecomphp
to communicate with Resurs Bank when handling existing
payments.
NOTE: Don’t forget to exclude index.php
from your base URL, otherwise there may be issues
during the checkout process.
This is how the frontend checkout page will look with the module enabled. When the userwants to go to checkout, they are redirected to this page. The shopping cart page can beskipped if specified in the configuration.
As you can see, the page is divided into three parts. At the top is our cart with controls to add/remove/edit individual items; in the middle you can choose shipping methods and apply a discount code; and at the bottom you fill out your address information and select a paymentmethod.
NOTE: As you change the information on this page, the module will update and prevent the user from interacting with certain things, which can be either the entire page or a specific component as it’s updating. Read on to learn more.
As you change either the quantity of an item or remove an item from the cart, the module will update the grand total, shipping methods and any applied discount. This will temporarily disable interaction with items, shipping methods and the discount code element.
NOTE: If you change the quantity to 0 (zero) the item will be removed from the cart.
As you change shipping methods the module will update the grand total. This will temporarily disable interaction with shipping methods.
When you apply a discount code, the module will temporarily disable the discount code block. When completed, it will display the outcome below the input field: either a red text saying it failed, or a green one saying what amount is withdrawn from the grand total.
NOTE: The outcome is displayed temporarily when failing, but is permanent when successful.
NOTE: If you encounter any problems with the iframe, first check that you exclude index.php
from your base URL.
The iframe communicates with the website through the window.postMessage()
API. It enables safe
cross-origin communication between websites when properly used. We use it to send and receive
messages from the Resurs Bank iframe that are about events and changes made to the information
within the iframe. Do note that if you're going to use this API to extend or modify any existing
functionality, you MUST know how to use it properly! Therefore,here are some useful warnings and
advice:
WARNING: Please be aware that improper use of this API can leave holes in your security that attackers can exploit and do things like cross-site scripting attacks!
It is HIGHLY recommended that you thoroughly read the MDN article and get a good understanding of the window.postMessage() API before using it: https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage.
The module uses AJAX to update the quote object in the client session when you:
During these AJAX calls, the module will update any affected parts as a result of the change, temporarily disabling them and/or the whole page until the update is done.
The order is placed when the client clicks their confirmation button to complete their purchase. If this process would for any reason fail, the user's shopping cart will be rebuilt and as much information as possible will be automatically filled out again to minimize the number of steps required to try placing the order again. Remaining required information needs to be provided by the user manually.
NOTE: The order confirmation email won't be sent after the order has been created (more on this in the section about callbacks).
Settings for the module are located under Stores -> Configuration -> Resurs Bank -> Checkout.
You need to specify your Username
and Password
under the API
settings for the module to
function at all. Also, the Unit Measure
setting under API
MUST have a value or API calls
won't work.
The Environment
setting will define what servers you use for your outgoing API calls. Test
should be used in test/development environments, while Production
should only be used on your
production environment (live website).
This button contacts the Resurs Bank API and fetches all available payment methods. It also creates
the necessary files for these to work in Magento. You can find the generated model files in
app/code/local/Resursbank/Checkout/Model/Payment/Fetched/
NOTE: If (for any reason) any of the generated models should be missing the checkout will still
function properly, but the payment method will fall back to resursbank_default
and simply state
"Resurs Bank" on your order view. This can also affect statistics regarding how often specific
payment methods are used. You can reinstate missing payment method models by fetching them again
from the configuration.
In the callback settings, to begin with, there is only a button to register callbacks. When clicking it, the callback URLs will register at Resurs Bank. These URLs are based on the base URL for your website.
These URLs are used by Resurs Bank to contact your website and notify it of various events in relation to payments. For example, the module prevents order confirmation emails from being sent when orders are created. They will instead be sent when Resurs Bank has registered payment of the order. This process can take seconds to hours, depending on the user's preconditions.
Some callbacks will modify the order status. These are callbacks from methods which mark the payment as confirmed or being under suspicion of fraud. Which callbacks that trigger these events depend on the selected method of payment. You can configure what order status will be used for these events from the configuration as illustrated by the image above.
NOTE: Since the callback URLs are based on your base URL, you should be careful when registering
them from a test/development environment so they do not accidentally overwrite the URLs used by your
production environment! You should never use the value Production
for the Environment
setting in
a test/development environment to avoid such issues.
The salt-key is used to ensure that incoming calls actually come from Resurs Bank.
The path to the directory where the salt-key is stored can be configured from Callback settings
-> Salt storage. By default this file is created as var/.resursbank_key
. You may wish to change
the path if the file containing the key would be insecure due to permissions of that directory in
combination with your host configuration, or if it gets deleted as part of your deploy routine.
The salt-key is generated when you register your callbacks, and submitted as part of the callback
URLs to Resurs Bank. When incoming calls to the store are made by Resurs Bank, the callback handler
(Model/Callback.php) will evaluate the provided digest
against the content of your local salt-key
file to confirm that the calls do not originate from any other source.
If you wish to regenerate your salt-key, or if your salt-key for any reason would be deleted by for example an automated process, you can simply register your callbacks again from the configuration to have it automatically regenerated.
Automatic callback registration will occur under very specific conditions. It will happen when the configuration is saved, if the following requirements are met:
username
.password
.Environment
setting must be set to Production
.When this feature is enabled you can charge, cancel and refund payments directly from the Magento administration panel.
Payments are automatically charged when you create an invoice for your order.
On a pending order, press the button in the image above. This will take you to another page.
At the bottom is the submit button. Press it, and an invoice will be created. At the same time the payment will be charged by Resurs Bank.
Payments are automatically cancelled along with the order.
After you click the cancel button, a confirmation window will show up. Just click "OK" and the cancellation process should start.
Payments are automatically refunded when credit memos are issued.
On a completed order, press the button in the image above. This will take you to another page.
At the bottom is the refund button. Press it, and a credit memo will be created and the payment refunded.
Please note that you can choose to refund specific parts of an order. For more complex cases of partial refunds, for example for orders including percentage based discounts, it may be preferable to handle it directly from Resurs Bank’s administration panel to ensure the numbers are what you intend.
You can view the order history by clicking on the tab Comments History
. Callbacks made by
Resurs Bank, as well After-shop related actions, will append entries to this section.
Logs are activated along with the normal system logs in Magento. We log every outgoing and incoming call the module makes/receives. For that reason it’s very important that logs are disabled on your production environment (unless required for debug/test purposes), otherwise they will grow very rapidly.
There are 4 kinds of log files where content from various operations will be stored:
resursbank_general.log
(for anything without a specified context).resursbank_api.log
(for outgoing API calls to Resurs Bank).resursbank_cache.log
(anything cache related).resursbank_callback.log
(for incoming calls from Resurs Bank).There is a fairly common issue which can occur when the compiler is enabled where PHP will complain
a constructor receives an instance of a Context class where ObjectManager was expected. This issue
is usually remedied by deleting the directories var/cache
, var/generation
and var/di
after
which you simply refresh the cache from your administration panel.
If you are running the memcached service, and have the PHP extension for memcache installed, you will need to flush it after installing the module before it will work. The same applies if you should ever run into any problems where the module is not loading/behaving correctly.
Normally you can flush memcache by executing the following commands (please note that the below is subject to change depending on your server configuration and you should not issue any such commands unless you know what you are doing. Resurs Bank is not responsible for any damage caused by improper use of your memcached service).
telnet localhost 11211
flush_all
quit
If you have enabled the Zend_OPcache PHP extension you will need to reload/restart PHP after installing the module. If you should experience any issue with the module not loading properly at any point please make sure to refresh Zend_OPcache by reloading/restarting PHP before further investigation.
While Redis has not been reported causing any issues we recommend you flush it after installing the extension, or if you should experience any issues, before you investigate any further. You can normally flush Redis by executing the following commands (please note that the below is subject to change depending on your server configuration and you should not issue any such commands unless you know what you are doing. Resurs Bank is not responsible for any damage caused by improper use of your redis/redis-cli service).
redis-cli flushall
If you are running Varnish and you experience problems we currently recommend you configure Varnish to avoid the checkout page. To test whether Varnish is the cause of the problem you are experiencing you can temporarily disable the service to check if the issue disappears. If you need to re-configure Varnish to avoid the checkout page we refer you to your developer/system administrator.
If callbacks are not working please confirm that you have no firewall in place blocking incoming
calls from Resurs Bank. If there is no firewall blocking the incoming calls please verify that the
content of the salt file (default location var/.resursbank_key
) matches the SALT registered at Resurs Bank.
NOTE: After updating from an earlier version of the module you will need to sync payment methods, and register callbacks, manually from the administration panel because of the changes described above.