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!
Leave a Reply