Setting up WooCommerce checkout fields without breaking your payment gateway

Setting up WooCommerce checkout fields without breaking your payment gateway is a task that many store operators tackle without a clear safety net, and the consequences can be costly. In this article we will break down the exact steps you need to follow, show a realistic hypothetical example with numbers, and give you a checklist to keep your checkout stable while you add the data you need.

The hidden risk of custom checkout fields

When you add, remove, or rename a field on the checkout page you are directly touching the data payload that is sent to the payment processor. Most gateways expect a specific set of parameters – usually the order total, currency, billing address, and a few optional fields. If the payload is altered in an unexpected way the gateway can reject the transaction, return a generic error, or even mark the transaction as fraudulent.

According to the Baymard Institute, the average cart abandonment rate sits around 70 percent, and a faulty checkout is a leading cause. Even a single broken field can add a few extra seconds of friction that push a shopper into abandonment. The cost of a broken gateway is therefore measured not only in lost sales but also in wasted ad spend that was driving traffic to a non‑functional checkout.

In a typical mid‑size store that processes 500 orders per month with an average order value of R5 000, a 2 percent drop in conversion due to a checkout error translates to a loss of roughly R50 000 per month. This illustrates why a disciplined approach to field changes is essential.

Planning your field changes

Before you touch any code, map out exactly why you need the new field and how it will be used downstream. Follow these three planning steps:

1. Define the business purpose

• Is the field required for compliance (e.g., tax number)?
• Is it needed for fulfillment (e.g., delivery instructions)?
• Is it for marketing segmentation (e.g., preferred contact method)?

Only fields that have a clear purpose should be added. Unnecessary fields increase the chance of validation errors and can confuse the gateway.

2. Choose the correct field type

• Text – simple strings, limited to 255 characters.
• Select – predefined options, reduces typing errors.
• Checkbox – boolean values, useful for opt‑ins.

Each type maps to a different data format in the API request. For example, a checkbox is sent as “true” or “false”, while a text field is sent as a string. Align the type with what the gateway expects.

3. Document the data flow

Create a short diagram or table that shows:

• Field name in WooCommerce (e.g., billing_tax_number)
• Data type (string, integer, boolean)
• Where it is stored (order meta, customer meta)
• Whether it is passed to the gateway (yes/no)

This documentation becomes the reference point during testing and future updates.

Step‑by‑step: adding a custom field safely

The following method uses a small plugin file rather than editing core files. This keeps changes upgrade‑proof and easier to roll back.

Step 1: Create a custom plugin

In wp-content/plugins create a folder called wc‑custom‑checkout and inside it a file named wc‑custom‑checkout.php. Paste the header below:

<?php
/*
Plugin Name: WooCommerce Custom Checkout Fields
Description: Adds a tax number field without affecting payment gateway payload.
Version: 1.0
Author: Your Name
*/

Activate the plugin from the WordPress admin.

Step 2: Add the field to the checkout form

Hook into woocommerce_checkout_fields to inject the field. The code below adds a required text field called “Tax Number”.

add_filter( 'woocommerce_checkout_fields', 'add_tax_number_field' );
function add_tax_number_field( $fields ) {
    $fields['billing']['billing_tax_number'] = array(
        'type'        => 'text',
        'label'       => __( 'Tax Number', 'woocommerce' ),
        'placeholder' => __( 'Enter your tax number', 'woocommerce' ),
        'required'    => true,
        'class'       => array( 'form-row-wide' ),
        'clear'       => true,
        'priority'    => 25,
    );
    return $fields;
}

Note the priority value – it determines where the field appears relative to existing fields.

Step 3: Save the field to order meta

Use the woocommerce_checkout_update_order_meta hook:

add_action( 'woocommerce_checkout_update_order_meta', 'save_tax_number_field' );
function save_tax_number_field( $order_id ) {
    if ( ! empty( $_POST['billing_tax_number'] ) ) {
        update_post_meta( $order_id, '_billing_tax_number', sanitize_text_field( $_POST['billing_tax_number'] ) );
    }
}

This stores the value safely and makes it available for later reporting.

Step 4: Ensure the field does not break the gateway payload

Most gateways ignore unknown fields, but some strict APIs reject extra parameters. To be safe, filter the data that is sent to the gateway. For Stripe, you can use the woocommerce_stripe_request_body filter:

add_filter( 'woocommerce_stripe_request_body', 'strip_extra_fields_from_stripe', 10, 2 );
function strip_extra_fields_from_stripe( $request_body, $order ) {
    // Remove our custom field if it exists
    if ( isset( $request_body['billing_tax_number'] ) ) {
        unset( $request_body['billing_tax_number'] );
    }
    return $request_body;
}

Replace woocommerce_stripe_request_body with the appropriate filter for your gateway (e.g., woocommerce_paypal_args for PayPal). This step guarantees that the custom field stays in WooCommerce but never reaches the payment processor.

Step 5: Add validation and error messages

Even though the field is required, you should also validate its format. For a tax number that must be 10 digits, add:

add_action( 'woocommerce_checkout_process', 'validate_tax_number' );
function validate_tax_number() {
    if ( isset( $_POST['billing_tax_number'] ) && ! preg_match( '/^d{10}$/', $_POST['billing_tax_number'] ) ) {
        wc_add_notice( __( 'Tax Number must be exactly 10 digits.', 'woocommerce' ), 'error' );
    }
}

This prevents malformed data from being saved and reduces the chance of downstream errors.

Testing the payment gateway after changes

Testing is the only way to be confident that the checkout still works. Follow a three‑phase testing plan.

1. Unit testing with dummy orders

• Enable WooCommerce’s built‑in “Sandbox” mode for your gateway.
• Place 5 test orders using the new field, varying the input (valid, invalid, empty).
• Confirm that each order creates a payment intent and that the order status moves from “Pending” to “Processing”.

2. End‑to‑end testing with a real card

Switch the gateway to live mode but use a low‑value card (e.g., R1 000). Complete a purchase and verify:

• The transaction appears in the gateway dashboard.
• The order in WooCommerce shows the correct total and status.
• The custom field value is stored and displayed in the order edit screen.

3. Regression testing of existing fields

Run a quick audit of all standard fields (name, address, email) to ensure they still behave as expected. Use the run a free scan of your store to catch hidden JavaScript errors that may surface only after the new field is added.

Common pitfalls and how to avoid them

Even experienced operators stumble over a few recurring issues. Recognising them early saves time.

Pitfall 1: Overriding core templates

Copying checkout/form-checkout.php into your theme and editing it directly can bypass WooCommerce’s hooks, meaning your custom field never gets saved. Instead, always use filters and actions as shown above.

Pitfall 2: Forgetting to clear caches

Object caching plugins or server‑side caches can serve an outdated version of the checkout page. After deploying the plugin, purge all caches and test in an incognito window.

Pitfall 3: Not handling multi‑currency

If you sell in multiple currencies, ensure any validation logic does not assume a single currency format. For example, a tax number field should not be tied to a currency symbol.

Pitfall 4: Ignoring mobile experience

Fields that work on desktop may be hidden or mis‑aligned on small screens. Use the browser’s responsive mode to verify layout, and add CSS rules if needed.

Pitfall 5: Assuming the gateway will ignore unknown fields

While many gateways are tolerant, some strict PCI‑compliant implementations reject any extra parameters. Always filter the request payload as demonstrated in Step 4.

Quick checklist for safe field implementation

• Document the purpose and data type of every new field.
• Add the field via woocommerce_checkout_fields, not by editing templates.
• Store the field in order meta with proper sanitisation.
• Filter the gateway request to remove the custom field.
• Validate input format and display clear error messages.
• Run sandbox tests, live low‑value tests, and regression checks.
• Purge caches and verify mobile layout.
• Monitor order logs for any gateway error codes after launch.

By following this method you can expand the data you collect at checkout while keeping the payment gateway stable. The extra information can improve fulfillment, compliance, and customer segmentation without sacrificing conversion.

Further reading: Baymard Institute’s checkout and cart abandonment research.