Resurs Bank - Magento 2 module - Checkout

Description

A one-step checkout module from Resurs Bank.

---

Prerequisites

• Magento 2
• SOAP for your version of PHP (for example php5-soap or php7.0-soap).

---

Installing

1. Navigate to your magento installation directory:

cd ~/path/to/your/magento/installation

2. Then, inside your magento installation directory, execure the following command:

composer require resursbank/checkout

3. Go into your admin panel, and navigate to Stores -> Configuration -> Resurs Bank -> Checkout.

4. You need to specify your Username and Password under the API Settings.

5. Specify the Unit Measure under API Settings (it can be anything you like).

6. Select the appropriate Envrionment under API Settings (Test or Production depending on your intent).

7. In General Settings, press the Fetch payment methods button.

8. In Callback Settings, press the Update callbacks button.

9. 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.

10. 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.

---

Frontend

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.

Cart

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.

Shipping methods

As you change shipping methods the module will update the grand total. This will temporarily disable interaction with shipping methods.

Discount code

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.

The iframe

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.

Data syncing

The module uses AJAX to update the quote object in the client session when you:

• Change the quantity of an item.
• Remove an item from the cart.
• Apply a discount code.
• Select shipping method.
• Enter billing/shipping information.
• Select payment method.

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.

Order placement

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).

---

Admin

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).

Payment methods

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.

Callback settings

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.

Salt-key

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 registration

Automatic callback registration will occur under very specific conditions. It will happen when the configuration is saved, if the following requirements are met:

1. You must have provided an API username.
2. You must have provided an API password.
3. Your Environment setting must be set to Production.
4. No callback URLs are currently registered, or your local salt-key file is missing.

---

Orders

After-shop settings

When this feature is enabled you can charge, cancel and refund payments directly from the Magento administration panel.

Charging a payment

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.

Canceling a payment

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.

Refunding a payment

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.

Order history

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

How to activate

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.

Type of logs

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).

---

Debug

Compiler issues

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.

Memcache

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

Zend_OPcache

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.

Redis

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

Varnish

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.

Callbacks

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.

---

Changelog

4.3.2

• Prepared implementation of test callback.
• Structural reformation of code handling data coming from the API, including payment methods and their annuity configuration.
• The part payment widget and the cron to cancel unpaid orders have been updated to function with the reformation described above.
• Part payment price is now displayed on checkout page.
• Part payment annuity min / max values are no longer configurable from the administration panel.
• Synced payment methods are now listed on the configuration page.
• The button to sync payment methods and the new list displaying all synced methods have been moved into a new separate section on the configuration page.
• Changed payment method naming convention to resursbank_[method]_[username]_[environment]
• Module version numbers (composer, database schedule and database data) are now displayed in the administration panel and outgoing API calls.

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.

4.3.3

• Added resursbank_callback_received flag column to sales_order table. This is an extra insurance for the automatic annulment procedure. To ensure only orders without payment are annulled, since the getPayment() check sometimes will result in a faulty 500 (meaning the payment is missing).

4.3.4

• Fixed minor problem in advanced configuration reader.

4.3.5

• Fixed race condition between iframe and checkout JS. When the JS on the checkout page loaded slower than the iframe communication from the iframe was not received.

4.3.8

• Fixed race condition which occurs within the iframe, which sometimes causes the websocket to fail communicating with the iframe.
• Fixed minor bug with discounts not updating when items are removed from the shopping cart.
• Removed spinners from checkout page.

4.3.9

• Fixed callback handling for Swish payments.

5.0.0

• Added support for Simplified Flow.

---

Contact