DEV Community

Cover image for How to Set Up a WooCommerce Pay by Bank Plugin and Test Every Payment Outcome in Sandbox
Jafar on Payments
Jafar on Payments

Posted on Edited on

How to Set Up a WooCommerce Pay by Bank Plugin and Test Every Payment Outcome in Sandbox

The client wants Pay by Bank on their WooCommerce shop by Friday. You install the plugin, paste a key, place one test order, and it works. Then the first real customer closes their bank app halfway through, and the order sits on "Pending payment" while everyone wonders whether the money arrived.

If you build or look after WooCommerce stores for UK businesses, this post is for you. You'll get the full setup (keys, redirect URL and webhook signing), a sandbox test plan that covers every payment outcome, and two small snippets that make testing much easier.

What Pay by Bank means at a WooCommerce checkout

Pay by Bank lets a customer pay straight from their bank account. At checkout they pick their bank, get sent to their bank's app, and approve the payment there with Face ID, a fingerprint or a passcode. The money then moves from their account to the merchant's over Faster Payments, the UK's 24/7 bank transfer system.

It's built on open banking, the regulated system that lets a payment provider ask a bank to make a payment with the account holder's permission. Usage is growing fast: there were 351 million open banking payments in the UK in 2025, up 57% on 2024 (Open Banking Limited).

For a developer, the important difference from a card form is that the result arrives asynchronously, which means later and separately from the page the customer is on. The customer leaves your site, approves in their bank's app, and comes back (or doesn't). Your store finds out what happened from a redirect, a webhook or a status check. A webhook is a message the payment provider's server sends to yours when something changes, such as a payment completing.

What you need before you start

  • A staging copy of the store. Never test a new gateway on the live site.
  • A sandbox API key. A sandbox is a test version of the payment service where no real money moves. You'll get a separate production key later.
  • A redirect URL. This is the page the customer lands on after approving in their bank's app. Most plugins accept the store's homepage.
  • A webhook signing secret, if your provider signs webhooks. The plugin uses it to check that each webhook really came from the provider.
  • To know which checkout the store uses. Since WooCommerce 8.3 (November 2023), new stores get the block-based Cart and Checkout by default, and a payment gateway that hasn't been built for blocks may not appear as a payment option at all (WooCommerce Developer Blog, November 2023).

How to set up the plugin

If you're choosing a WooCommerce Pay by Bank plugin, check that it supports both the Classic and the Block checkout before you install it. Then work through these steps on staging.

  1. In the payment provider's dashboard, create a sandbox API key and paste your store's homepage URL into the redirect URL field.
  2. Install the plugin from the WordPress plugin directory and activate it.
  3. Go to WooCommerce, then Settings, then Payments. Open the new gateway, click Manage, paste the sandbox key, turn on sandbox or test mode, and save.
  4. If webhook signing is switched on in the provider's dashboard, paste the signing secret into the plugin's webhook signing field. Without it, the plugin can't verify incoming webhooks and payment updates will fail.
  5. Open the checkout in a private browser window and check the Pay by Bank option shows on both the Classic and the Block checkout if the store uses either.

Field names differ between plugins, so keep the provider's WooCommerce setup guide open while you work through the steps.

How to Test Every Payment Outcome in a Sandbox

Most Pay by Bank sandboxes provide a test bank that lets you simulate different payment outcomes without transferring real money. Select the test bank at checkout, choose the outcome you want to test, and check how your store responds.

Make sure you test each of the following scenarios:

  • Completed: The order should move to Processing (or Completed for virtual products), stock levels should decrease, and the customer should receive a confirmation email.
  • Failed: The customer should return to checkout with a clear error message and the option to try again. The order must remain unpaid.
  • Pending payment: If the bank hasn't confirmed the payment, the order should remain unpaid. Its status should update automatically once the webhook or payment status confirmation arrives.
  • Abandoned: Close the bank's payment page without completing the transaction. The order should eventually expire or be cancelled rather than remain in Pending payment indefinitely.
  • Duplicate webhook: Send the same webhook twice and check that the order records only one payment, not two.
  • Refunds: Issue full and partial refunds from the WooCommerce order if supported, otherwise from the provider's dashboard. Check each refund appears in the order and its notes.

This snippet logs every order status change while you test, so you can see exactly what happened and in what order. The log appears under WooCommerce, then Status, then Logs.

// Log every order status change while testing in sandbox.
// Remove this before the store goes live.
add_action( 'woocommerce_order_status_changed', function ( $order_id, $from, $to, $order ) {
    $logger = wc_get_logger();
    $logger->info(
        'Order ' . $order_id . ': ' . $from . ' to ' . $to . ' (gateway: ' . $order->get_payment_method() . ')',
        array( 'source' => 'bank-payment-testing' )
    );
}, 10, 4 );
Enter fullscreen mode Exit fullscreen mode

If you write your own webhook handler, or want to understand what the plugin's signing field does, this is the basic check. It works out what the signature should be from the raw request body and your secret, then compares it with the one in the header.

function verify_webhook_signature( $raw_body, $signature_header, $secret ) {
    if ( ! is_string( $secret ) || strpos( $secret, 'whsec_' ) !== 0 ) {
        return false;
    }

    // Remove whsec_ and decode the secret before using it as the signing key.
    $key = base64_decode( substr( $secret, 6 ), true );
    if ( $key === false || $key === '' ) {
        return false;
    }

    // The header contains v1= followed by the signature in hex.
    if ( ! preg_match( '/\Av1=([0-9a-f]{64})\z/', $signature_header, $matches ) ) {
        return false;
    }

    $expected = hash_hmac( 'sha256', $raw_body, $key );
    // hash_equals compares in constant time, so attackers can't guess the signature bit by bit
    return hash_equals( $expected, $matches[1] );
}

$raw_body = file_get_contents( 'php://input' );
// Replace this placeholder with the documented header's PHP server key:
// prefix HTTP_, uppercase the header name and replace hyphens with underscores.
$signature_header_key = 'REPLACE_WITH_DOCUMENTED_SIGNATURE_SERVER_KEY';
$signature = isset( $_SERVER[$signature_header_key] ) ? $_SERVER[$signature_header_key] : '';

if ( ! verify_webhook_signature( $raw_body, $signature, getenv( 'WEBHOOK_SECRET' ) ) ) {
    http_response_code( 401 );
    exit;
}
Enter fullscreen mode Exit fullscreen mode

This matches the linked provider's newer signing scheme; other providers differ, so check their docs.

Mistakes to avoid

  • Marking orders paid on the redirect alone. Customers close tabs and lose signal. Confirm the payment from the webhook or a status check, not from the fact that the customer came back.
  • Parsing the webhook before checking the signature. Decoding and re-encoding JSON can change the bytes, and then a genuine signature won't match. Verify the raw body first.
  • Not handling duplicates. Webhooks are usually delivered at least once, so the same event can arrive twice (Standard Webhooks specification). Make the handler idempotent, which means running it twice has the same effect as running it once.
  • Mixing sandbox and production keys. A sandbox key in production mode, or the other way round, will fail authentication. Switch both the key and the mode together.
  • Only testing the Classic checkout. If the store moves to the Block checkout later, a gateway that isn't block-compatible can quietly disappear from checkout.

Checklist before going live

  • The Pay by Bank option shows on the checkout the store actually uses
  • Completed, failed, pending and abandoned payment statuses all tested in sandbox
  • A duplicate webhook doesn't update the order twice
  • Webhook signatures are checked on the raw body
  • Full and partial refunds tested from the WooCommerce order if supported, otherwise the provider's dashboard, and checked in the order and its notes
  • The testing logger snippet removed
  • Production key in, sandbox mode off, and one small live payment made and refunded

Conclusion

A Pay by Bank checkout is only as reliable as the way it handles payments that don't go to plan. Test every outcome in the sandbox, verify every webhook, and never trust the redirect on its own. Run through the checklist on staging before you switch the store to production.

Top comments (0)