Adding Pay by Bank to WooCommerce: setup, sandbox testing, and the webhook setting people miss

#woocommerce #openbanking #php #fintech

A merchant installs a gateway plugin, takes one test payment, goes live, and a few weeks later notices some orders sitting on "Pending payment". The plugin usually isn't the problem. What gets missed is the case where the customer pays but their browser never makes it back to the shop.

This is how I'd add Pay by Bank to a UK WooCommerce store. Setup takes about ten minutes. The webhook section is where the time actually goes.

Is it right for your store?

Pay by Bank sends the customer to their banking app to approve, then back to you. Compared with Apple Pay that's an extra hop, and on a £12 impulse buy it can cost you a sale. Fena's write-up on this suggests the fee difference starts to matter above roughly £100 and more so above £250 (source). That fits what we see: bigger baskets, trade buyers, categories that suffer chargebacks, and mostly UK customers.

I wouldn't replace cards. Offer both at checkout and let people choose. Bank payments cost about half of what cards do, and there's no chargeback route because the customer approved the payment inside their own bank's app.

Setup

You need an Atoa Business account that has finished onboarding and KYB.

In the Atoa Business app go to Settings → API Access and generate a Sandbox key. Add your shop's homepage as the redirect URL.
In WordPress, install the plugin from Plugins → Add New (search "Atoa Pay", slug atoa-pay). It needs WordPress 6.0+ and PHP 8.0+.
Go to WooCommerce → Settings → Payments, click Manage next to "Atoa – Pay by Bank App", paste the key, choose your Store Location, turn on Sandbox Mode, enable the method and save.

Both block and classic checkout work. Card, Apple Pay and Google Pay can be switched on separately under the same account.

Testing

At the bank picker, choose Atoa Test Bank. You then get a screen where you pick the result yourself:

COMPLETED: payment succeeded, the order should move to processing.
FAILED: the customer goes back to checkout to try again.
PENDING: the bank hasn't confirmed yet.

Run all three. PENDING is the closest thing to a customer closing the tab halfway through, so it tells you the most.

The webhook setting people miss

The plugin registers its webhook URL for you and re-syncs it each time you save settings. It also checks payment status 5 minutes, 30 minutes, 1 hour, 4 hours and 24 hours after checkout, in case a webhook never arrives.

The problem I'd watch for: if you enable V2 webhook signing in the Atoa Dashboard (Settings → Webhooks), the signing secret has to be pasted into the plugin's Webhook Signing Key field. If it isn't, the docs say plugin webhooks will fail signature verification, and orders stay in Pending until one of those status checks catches up.

V2 signs the raw request body with HMAC-SHA256 and sends the result in an X-Atoa-Signature header. If you have your own endpoint (fulfilment, ERP sync), this is the check in PHP:

<?php
$secret = getenv('ATOA_WEBHOOK_SIGNING_SECRET');
$raw    = file_get_contents('php://input');            // raw body, not decoded
$header = $_SERVER['HTTP_X_ATOA_SIGNATURE'] ?? '';
$given  = preg_replace('/^v1=/', '', $header);         // strip the v1= prefix
$expect = hash_hmac('sha256', $raw, $secret);

if (!hash_equals($expect, $given)) {                   // timing-safe compare
    http_response_code(401);
    exit;
}

$event = json_decode($raw, true);
// handle PAYMENTS_STATUS / REFUND_STATUS idempotently, then:
http_response_code(200);                               // anything but 200 counts as a failure

Hash the raw body, because re-encoded JSON won't produce the same bytes. Use hash_equals for the comparison. And make the handler safe to run twice: Atoa retries with exponential back-off for up to 24 hours on any non-200 response, so duplicates will happen.

Going live

Swap in a Production key, turn off Sandbox Mode, and make one real £1 payment from your own bank account. Check the order status changes, then work through the go-live checklist.

The sandbox guide and API reference are at docs.paywithatoa.co.uk, and the plugin is on WordPress.org.

If you've had orders stick in odd states on your own store, I'd like to hear what caused it.

DEV Community