Table of contents

Welcome to the developer notes for RBWC Payment Gateway - or its public name tornevalls-resurs-bank-payment-gateway-for-woocommerce. A WooCommerce for WordPress platform. This page describes how the plugin is built and how you can use it.

IMPORTANT NOTE: First time running should be on a dedicated test environment

If you are entirely new to this plugin, I'd suggest you to run it in a dedicated test environment that is supposedly equals to a production environment when you install the plugin AFTER testing. Primary newly detected errors should be discovered in TEST rather than production. If something fails in production it also means that YOU are the one that potentially looses traffic to your site. This responsibility is yours and this handling is for your safety only!

Multisite/WordPress Networks

The plugin do support WordPress networks (aka multisite), however it does not support running one webservice account over many sites at once. The main rule that Resurs Bank works with is that one webservice account only works for one site. Running multiple sites do require multiple webservice accounts! Read more about this at WPMU - WordPress Network and the plugin limitations.

About Resurs Bank Payment Gateway for WooCommerce

The Resurs Bank payment provider gateway is a plugin-extensions that cooperates with WooCommerce in WordPress environments. It allows you to integrate and shop with Resurs Bank as a payment provider. The diagram below shows you how the process usually looks.

REQUIREMENTS AND SECURITY CONSIDERATIONS

How this plugin is intended to work with PHP-versions

Take a look at Code of Conduct and Migrations#PHPVersions for an extended explanation about how PHP is used.

Current Requirements

PHP: Take a look here to keep up with support. As of aug 2021, both WooCommerce and WordPress is about to jump into 7.4 and higher. Also, read here for information about lower versions of PHP. This plugin is written for 7.0 and higher - and the policy is following WooCommerce lowest requirement.
Required: WooCommerce: v3.5.0 or higher!
Required: SoapClient with xml drivers and extensions.
Required: SSL - HTTPS must be fully enabled. This is a callback security measure, which is required from Resurs Bank.
Curl is highly recommended but not necessary. We suggest that you do not trust only PHP streams on this one as you may loose important features if you run explicitly with streams.
PHP streams? Yes, you still need them since SoapClient is actually using it.
WordPress: Preferably at least v5.5. It has supported, and probably will, older releases but it is highly recommended to go for the latest version as soon as possible if you're not already there. See here for more information.

Join the resursbank-woocommerce email-list to get information about the plugin faster!

Frequently Asked Questions

Can I handle payments from both Resurs merchant admin and WooCommerce

You could but it is recommended that you only use one interface:

If you do after shop handling from WooCommerce, stay with this. The plugin will synchronize the payment at Resurs Bank.
If you want to do all after shop handling from Resurs Bank, be aware that there is no guarantee for everything to be synched properly. As we currently only trust callbacks, you can not edit the order in details if you do this from Resurs Bank. This has to be handled from WooCommerce and therefore, you get no guarantee for a properly synchronized order. "What happens in payment admin, stays in payment admin" so to speak.
Error rendering macro 'jira' : null
covers the question about enabling/disabling the order management parts, and due to how the above parts are built there are no real reason for why this feature should be disabled at any point.

Order handling

I try to change my order from a status to completed, but it fails

The primary way we choose to handle orders and statuses is all based on Resurs Bank statuses. Normally, when you change a status from "In progress" to "Completed", the finalization process is running during the status update in WooCommerce. However, when orders are frozen at Resurs Bank, this is not allowed. For example, a frozen order at Resurs may be caused by things that happened during the payment process that requires manual checks on it. Also, the order may have detected suspected fraud. If a frozen order was allowed to unfreeze, this could also lead to unexpected results for the order. One important thing is to prevent the order to be delivered (and set as complete) if there is any doubts within the order.

This is also reflected in the status handling. If the order is frozen, Resurs intentions is to not push it out to a completion state. This is also why you can't change such orders to completed, if this occurs.

Well, I want to change status for it anyway, since the order is really complete at our (the merchant) side is completed

PHP 8.x

WooCommerce requirements are currently on a PHP 7.x requirements, which means we can not really go all the way up to 8.x just yet. Especially since current instances may fail run on bleeding edge code. However, we're working on solving this.

Do the plugin handle any e-mail sending?

The simple answer

No.

The longer answer

WooCommerce is handling all the logics behind the e-mail sending. What's really handling the e-mail flow is the status changes. When something happens in the plugin that triggers the order status to change, WooCommerce is handling the rest. If WooCommerce is configured to send e-mail (which can be seen in the Email-section of the admin panel), it will also send an e-mail. Order statuses can however be partially mapped differently (see below).

Order status mapping

Some payment methods causes the plugin to instantly finalize the order. By default, this will put the order in "completed" which for some merchants also means that is is delivered. This is more common among travel companies and merchants that sells digital products, besides payment methods like Vipps and Swish. To prevent payment methods like Vipps and Swish to put an order into completed, you should take a look in the advanced sections under "Order Status Mapping". This can change the way statuses, and thereby e-mail, are handled.

Do I need a scheduled job/cron for the plugin to work?

No. But you can enable the wp-cron if you want to. The plugin is using WC_Queue, a WooCommerce Worker Queue to handle callbacks and the very common race condition issues that occurs due to asynchronous requests from Resurs. Normally, when you have traffic to your site, this queue are very much handled automatically. However, if your site has low traffic rate, order status changes may be delayed based on how WC_Queue works. This is currently not confirmed, but a cronjob, that keeps your site active could solve the problem with those delays.

Browser not supported