Test Payment Gateway

Overview

Test Payment Gateway for WooCommerce adds a configurable WooCommerce payment method that lets approved users simulate common payment processor outcomes during checkout. It supports both the classic WooCommerce checkout and WooCommerce Blocks checkout.

This plugin is intended for testing checkout behavior, order status handling, customer messaging, and store workflows without using a live payment gateway.

Requirements

• WordPress 6.5 or newer
• WooCommerce 10.0 or newer
• PHP 7.4 or newer

What The Plugin Does

When the gateway is enabled, approved users can choose a simulated payment outcome at checkout. The plugin then updates the order based on the selected response.

Included simulated responses:

• Success
• Processor Declined
• Card Declined
• Suspected Fraud
• 3D Secure Required
• Pending Review
• Authorization Only

Installation

1. Upload the plugin folder to your /wp-content/plugins/ directory, or install it using your preferred deployment workflow.
2. Activate Test Payment Gateway for WooCommerce in Plugins.
3. Make sure WooCommerce is installed and active.

Setup

1. In the WordPress admin, go to WooCommerce > Settings > Payments.
2. Find Test Payment Gateway in the payment methods list.
3. Enable the payment method and select Manage.
4. Configure the gateway settings described below.
5. Save your changes.

Gateway Settings

The plugin includes the following settings:

Enable/Disable

Turns the test gateway on or off.

Title

The payment method title shown to customers during checkout.

Description

The payment method description shown below the title during checkout.

Default Simulated Response

Sets the response that is preselected when the customer first chooses the gateway.

Allowed Frontend Roles

Controls which signed-in WordPress user roles can see and use the gateway on the storefront.

Important behavior:

• Only logged-in users with an allowed role can use the gateway.
• Logged-out visitors cannot use the gateway.
• If no valid roles are saved, the plugin falls back to administrator.

This is useful when you want the gateway to be available only to store admins, QA users, or other internal test accounts.

Debug Logging

When enabled, the plugin writes simulated payment activity to the WooCommerce log with the source test-payment-gateway.

You can review logs in WooCommerce > Status > Logs.

Using The Gateway

1. Sign in with a user account that has one of the allowed roles.
2. Add products to the cart.
3. Go to checkout.
4. Select Test Payment Gateway.
5. Choose the simulated gateway response from the dropdown field.
6. Place the order.

The plugin will then process the order according to the selected response.

Simulated Response Behavior

Success

• Completes the payment
• Sends the customer to the order received page
• Adds an order note indicating that a successful payment was simulated

Processor Declined

• Marks the order as Failed
• Displays an error notice to the customer
• Adds an order note indicating that a processor decline was simulated

Card Declined

• Marks the order as Failed
• Displays an error notice to the customer
• Adds an order note indicating that a card decline was simulated

Suspected Fraud

• Marks the order as Failed
• Displays an error notice to the customer
• Adds an order note indicating that suspected fraud was simulated

3D Secure Required

• Marks the order as Failed
• Displays an error notice to the customer
• Adds an order note indicating that a 3D Secure challenge was simulated

Pending Review

• Places the order On hold
• Empties the cart
• Sends the customer to the order received page
• Adds an order note indicating that manual review was simulated

Authorization Only

• Places the order On hold
• Empties the cart
• Sends the customer to the order received page
• Stores a generated transaction ID on the order
• Adds an order note indicating that authorization without capture was simulated

Order Data Added By The Plugin

For each order processed through the gateway, the plugin stores metadata recording the selected simulated response:

• _mbtpg_response_key
• _mbtpg_response_label

This can help with testing, debugging, reporting, or custom admin workflows.

Classic Checkout And Block Checkout Support

The plugin supports:

• Classic WooCommerce checkout
• WooCommerce Blocks checkout
• High-Performance Order Storage (custom order tables)

On block checkout, the same simulated response selector is shown to eligible users.

Troubleshooting

The gateway does not appear at checkout

Check the following:

• The plugin is active.
• WooCommerce is active.
• The gateway is enabled in WooCommerce > Settings > Payments.
• You are signed in.
• Your user role is included in Allowed Frontend Roles.

The gateway appears in the editor but not on the storefront

The plugin is intentionally restricted on the storefront to approved roles only.

Logging is not showing anything

Check that:

• Debug Logging is enabled in the gateway settings.
• You are looking at the WooCommerce log source test-payment-gateway.

Uninstall Behavior

When the plugin is uninstalled, it removes:

• The saved gateway settings
• The stored order metadata keys _mbtpg_response_key and _mbtpg_response_label

Developers

The plugin includes several extension points for developers who need to customize behavior.

Filters

mbtpg_gateway_form_fields

Filters the WooCommerce admin settings fields for the gateway.

Parameters:

• $form_fields (array) The gateway form fields
• $gateway (MBTPG_Gateway) The gateway instance

Example use:

• Add a custom admin setting that lets your team enable or disable an additional internal testing mode.

Code example:

add_filter( 'mbtpg_gateway_form_fields', function( $form_fields, $gateway ) {
    $form_fields['internal_mode'] = array(
        'title'       => __( 'Internal Mode', 'your-text-domain' ),
        'type'        => 'checkbox',
        'label'       => __( 'Enable internal-only test behavior', 'your-text-domain' ),
        'default'     => 'no',
        'description' => __( 'Example custom setting added through mbtpg_gateway_form_fields.', 'your-text-domain' ),
    );

    return $form_fields;
}, 10, 2 );

mbtpg_validate_response_selection

Filters whether the selected simulated response is considered valid during checkout.

Parameters:

• $is_valid (bool) Current validation result
• $response_key (string) Selected response key
• $gateway (MBTPG_Gateway) The gateway instance

Example use:

• Prevent a specific simulated response from being used on high-value orders or for certain product types.

Code example:

add_filter( 'mbtpg_validate_response_selection', function( $is_valid, $response_key, $gateway ) {
    if ( 'suspected_fraud' === $response_key && WC()->cart ) {
        $total = (float) WC()->cart->get_total( 'edit' );

        if ( $total > 500 ) {
            wc_add_notice(
                __( 'The suspected fraud response is disabled for orders above $500 in this test setup.', 'your-text-domain' ),
                'error'
            );

            return false;
        }
    }

    return $is_valid;
}, 10, 3 );

mbtpg_requested_response

Filters the requested response value before it is validated and processed.

Parameters:

• $response (string) Requested response key
• $gateway (MBTPG_Gateway) The gateway instance

Example use:

• Automatically switch the selected response based on a query parameter, test environment flag, or the current user account.

Code example:

add_filter( 'mbtpg_requested_response', function( $response, $gateway ) {
    if ( isset( $_GET['force_mbtpg_response'] ) ) {
        return sanitize_key( wp_unslash( $_GET['force_mbtpg_response'] ) );
    }

    if ( current_user_can( 'manage_woocommerce' ) ) {
        return 'pending_review';
    }

    return $response;
}, 10, 2 );

mbtpg_response_definitions

Filters the available simulated response definitions.

Parameters:

• $responses (array) Response definitions
• $gateway (MBTPG_Gateway) The gateway instance

Example use:

• Add a custom simulated outcome such as Gateway Timeout or change the customer-facing message for an existing response.

Code example:

add_filter( 'mbtpg_response_definitions', function( $responses, $gateway ) {
    $responses['gateway_timeout'] = array(
        'label'         => __( 'Gateway Timeout', 'your-text-domain' ),
        'customer_note' => __( 'The test gateway timed out before the transaction completed.', 'your-text-domain' ),
        'order_note'    => __( 'A gateway timeout was simulated.', 'your-text-domain' ),
        'type'          => 'failure',
        'failure_code'  => 'gateway_timeout',
    );

    $responses['processor_declined']['customer_note'] = __(
        'The processor declined this test transaction. Please choose another option.',
        'your-text-domain'
    );

    return $responses;
}, 10, 2 );

mbtpg_process_payment_result

Filters the final result returned by process_payment().

Parameters:

• $result (array) Payment result array
• $order (WC_Order) The WooCommerce order
• $response_key (string) Selected response key
• $response (array) Response definition
• $gateway (MBTPG_Gateway) The gateway instance

Example use:

• Change the redirect destination after a successful simulated payment or attach extra data for a custom checkout flow.

Code example:

add_filter( 'mbtpg_process_payment_result', function( $result, $order, $response_key, $response, $gateway ) {
    if ( 'success' === $result['result'] && 'authorization_only' === $response_key ) {
        $result['redirect'] = add_query_arg(
            array(
                'mbtpg_review' => '1',
                'order_id'     => $order->get_id(),
            ),
            wc_get_endpoint_url( 'view-order', $order->get_id(), wc_get_page_permalink( 'myaccount' ) )
        );
    }

    return $result;
}, 10, 5 );

mbtpg_current_user_can_use_gateway

Filters whether the current user can access the gateway on the storefront.

Parameters:

• $can_use (bool) Whether the user can access the gateway
• $user (WP_User) Current user object
• $allowed_roles (string[]) Allowed role slugs

Example use:

• Allow access only for users on a staging site, users with a specific email domain, or members of a custom QA workflow.

Code example:

add_filter( 'mbtpg_current_user_can_use_gateway', function( $can_use, $user, $allowed_roles ) {
    if ( ! $user || empty( $user->user_email ) ) {
        return false;
    }

    if ( str_ends_with( strtolower( $user->user_email ), '@example.com' ) ) {
        return true;
    }

    return $can_use;
}, 10, 3 );

mbtpg_allowed_roles

Filters the final list of allowed frontend roles.

Parameters:

• $allowed_roles (string[]) Allowed role slugs

Example use:

• Add a custom role created by another plugin so that internal testers can access the gateway without changing the saved settings manually.

Code example:

add_filter( 'mbtpg_allowed_roles', function( $allowed_roles ) {
    $allowed_roles[] = 'qa_tester';

    return array_values( array_unique( $allowed_roles ) );
} );

Actions

mbtpg_before_process_payment

Runs before the selected simulated response is applied to the order.

Parameters:

• $order (WC_Order) The WooCommerce order
• $response_key (string) Selected response key
• $response (array) Response definition
• $gateway (MBTPG_Gateway) The gateway instance

Example use:

• Record extra order metadata, trigger custom logging, or notify an internal monitoring tool before the simulated result is applied.

Code example:

add_action( 'mbtpg_before_process_payment', function( $order, $response_key, $response, $gateway ) {
    $order->update_meta_data( '_qa_requested_response', $response_key );
    $order->update_meta_data( '_qa_requested_at', current_time( 'mysql', true ) );
    $order->save_meta_data();
}, 10, 4 );

mbtpg_after_process_payment

Runs after the simulated response is applied to the order.

Parameters:

• $order (WC_Order) The WooCommerce order
• $response_key (string) Selected response key
• $response (array) Response definition
• $result (array) Payment result array
• $gateway (MBTPG_Gateway) The gateway instance

Example use:

• Trigger follow-up automation such as sending a Slack alert, syncing order data to a QA dashboard, or starting a custom review workflow after processing.

Code example:

add_action( 'mbtpg_after_process_payment', function( $order, $response_key, $response, $result, $gateway ) {
    if ( 'failure' === $result['result'] ) {
        $order->add_order_note(
            sprintf(
                /* translators: %s: simulated response key */
                __( 'QA automation would run here for failed response: %s', 'your-text-domain' ),
                $response_key
            )
        );
    }
}, 10, 5 );

Support Notes

This plugin is designed for test and internal QA scenarios. It should only be made available to trusted users who understand that it simulates payment outcomes and does not process real transactions.