How to Integrate a Custom Payment Gateway into WooCommerce

Learn How to Integrate a Custom Payment Gateway into WooCommerce (Step-by-Step Guide)

WooCommerce is a powerful and flexible eCommerce platform, and one of its most useful features is its ability to integrate with virtually any payment gateway—even custom ones. If you’re working with a custom payment provider that exposes an API, this guide will show you exactly how to connect it to your WooCommerce store securely and effectively.

---

Why Integrate a Custom Payment Gateway?

There are several reasons you might want to integrate a custom payment gateway:

• Your business operates in a region where mainstream gateways are unavailable.
• You want to offer localized payment options (e.g., wallets, bank transfers).
• You’re working with a niche provider that offers better rates or features.

---

Prerequisites

Before diving in, make sure you have:

• WordPress and WooCommerce installed.
• Access to your custom payment gateway’s API documentation.
• API credentials (key/secret or token).
• Familiarity with PHP and WordPress plugin development.

---

Step 1: Create a Custom WooCommerce Gateway Plugin

You’ll start by building a simple plugin that WooCommerce can recognize.

Plugin Folder Structure

Create a new folder in /wp-content/plugins/ called custom-gateway, and inside it, a file named custom-gateway.php.

Boilerplate Code

<?php
/*
Plugin Name: Custom Payment Gateway
Description: WooCommerce integration for Custom Payment Gateway
*/

add_action('plugins_loaded', 'custom_gateway_init');

function custom_gateway_init() {
    if (!class_exists('WC_Payment_Gateway')) return;

    class WC_Gateway_Custom extends WC_Payment_Gateway {

        public function __construct() {
            $this->id = 'custom_gateway';
            $this->method_title = 'Custom Gateway';
            $this->method_description = 'Handles payments via a custom API';
            $this->has_fields = true;

            $this->init_form_fields();
            $this->init_settings();

            $this->title       = $this->get_option('title');
            $this->description = $this->get_option('description');

            add_action('woocommerce_update_options_payment_gateways_' . $this->id, [$this, 'process_admin_options']);
        }

        public function init_form_fields() {
            $this->form_fields = [
                'enabled' => [
                    'title'   => 'Enable/Disable',
                    'type'    => 'checkbox',
                    'label'   => 'Enable Custom Gateway',
                    'default' => 'yes'
                ],
                'title' => [
                    'title'       => 'Title',
                    'type'        => 'text',
                    'default'     => 'Custom Payment',
                ],
                'api_key' => [
                    'title'       => 'API Key',
                    'type'        => 'text',
                ],
                'api_secret' => [
                    'title'       => 'API Secret',
                    'type'        => 'password',
                ],
            ];
        }

        public function process_payment($order_id) {
            $order = wc_get_order($order_id);
            $payload = [
                'amount' => $order->get_total(),
                'currency' => get_woocommerce_currency(),
                'order_id' => $order->get_id(),
                'customer' => [
                    'name' => $order->get_billing_first_name(),
                    'email' => $order->get_billing_email(),
                ]
            ];

            $response = wp_remote_post('https://api.customgateway.com/v1/pay', [
                'method'    => 'POST',
                'headers'   => [
                    'Authorization' => 'Bearer ' . $this->get_option('api_key'),
                    'Content-Type'  => 'application/json'
                ],
                'body' => json_encode($payload),
                'timeout' => 60,
            ]);

            if (is_wp_error($response)) {
                wc_add_notice('Payment error: ' . $response->get_error_message(), 'error');
                return ['result' => 'fail'];
            }

            $body = json_decode(wp_remote_retrieve_body($response), true);

            if ($body['status'] === 'success') {
                $order->payment_complete($body['transaction_id']);
                return [
                    'result'   => 'success',
                    'redirect' => $this->get_return_url($order)
                ];
            } else {
                wc_add_notice('Payment failed: ' . $body['message'], 'error');
                return ['result' => 'fail'];
            }
        }
    }

    function add_custom_gateway_class($methods) {
        $methods[] = 'WC_Gateway_Custom';
        return $methods;
    }

    add_filter('woocommerce_payment_gateways', 'add_custom_gateway_class');
}

Activate the plugin in the WordPress admin, and you’ll see the new payment option appear in WooCommerce settings.

---

Step 2: Handle Payment Notifications (Webhooks)

If your gateway provides webhooks for payment confirmation, use this approach:

add_action('init', function () {
    add_rewrite_rule('^custom-gateway-webhook/?$', 'index.php?custom_gateway_webhook=1', 'top');
});

add_filter('query_vars', function($vars) {
    $vars[] = 'custom_gateway_webhook';
    return $vars;
});

add_action('template_redirect', function() {
    if (get_query_var('custom_gateway_webhook') == 1) {
        $payload = json_decode(file_get_contents('php://input'), true);
        $order = wc_get_order($payload['order_id']);
        if ($payload['status'] === 'paid') {
            $order->payment_complete($payload['transaction_id']);
        } elseif ($payload['status'] === 'failed') {
            $order->update_status('failed');
        }
        http_response_code(200);
        exit;
    }
});

Don’t forget to flush rewrite rules by visiting Settings > Permalinks once.

---

Integration Flow Diagram

Customer
   ↓
WooCommerce Checkout
   ↓
Custom Gateway Plugin
   ↓
Custom Payment Gateway API
   ↓
→ API Response (Success/Fail)
→ Webhook (Optional Confirmation)
   ↓
WooCommerce Updates Order Status

---

Security Best Practices

• Use HTTPS for all API and webhook communication.
• Never expose secret keys on the frontend.
• Log and handle all failures gracefully.
• Verify webhook signatures if available.

---

Final Thoughts

Integrating a custom payment gateway into WooCommerce isn’t just possible—it’s surprisingly straightforward once you understand the moving parts. With a bit of PHP knowledge and API documentation in hand, you can offer customers more flexibility and control over how they pay.

If you’d like help building this out for a specific API or want to expand features like tokenization or refunds, let me know!