Custom Payment Gateway Integration for WooCommerce

A client comes with a task to connect a regional bank not listed in the available plugins. Standard WooCommerce cannot handle non‑standard APIs. The result: forked third‑party modules, data loss, non‑working refunds. We solve this once and for all—we write a custom gateway for your stack, with full control over the code.

Recently we integrated a gateway for Latvia's Citadele bank: writing the gateway class took three days, plus one day for webhook debugging. After release, the customer received not only a working plugin but also complete operational documentation. Security is a critical concern: old plugins do not verify webhook signatures, opening the door to fake callbacks. We implement verification via hash_equals and strict validation of incoming requests.

What Standard Plugins Lack

• Outdated versions – many popular gateway plugins haven't been updated in years, use deprecated classes like WC_API, and are incompatible with PHP 8.2+.
• No webhook support – half of payment issues are solved by proper callback handling, but ready plugins either lack it or implement it poorly.
• Partial refunds – if you need to return part of an order (partial capture), most plugins simply don't call process_refund.
• Difficult customization – adding your own logic (e.g., a payment label in the admin panel) to a third‑party plugin without breaking on update is a major challenge.

Architecture of a Custom Gateway

The base class extends WC_Payment_Gateway. The entire payment flow—from redirect to the payment page to webhook processing—is encapsulated in three files:

wp-content/plugins/mypay-gateway/
├── mypay-gateway.php          # Entry point, registration
├── includes/
│   ├── class-wc-gateway-mypay.php
│   └── class-mypay-api-client.php
└── assets/
    └── js/checkout.js

The gateway class is registered via woocommerce_payment_gateways. In the constructor we define supports—mandatory ['products', 'refunds'], optional ['subscriptions']. Here is a minimal form field set:

$this->form_fields = [
    'enabled'    => ['title' => 'Enable', 'type' => 'checkbox', 'default' => 'yes'],
    'title'      => ['title' => 'Title', 'type' => 'text', 'default' => 'Credit Card'],
    'api_key'    => ['title' => 'API Key', 'type' => 'password'],
    'secret_key' => ['title' => 'Secret Key', 'type' => 'password'],
    'testmode'   => ['title' => 'Test Mode', 'type' => 'checkbox', 'default' => 'no'],
];

Comparison of Popular Payment Gateways

The table is approximate—fees change. The key takeaway: if you need high reliability and refunds, go with Stripe. On a budget, LiqPay or Fondy work, but they lack ready plugins.

Typical Integration Mistakes

• Incorrect webhook signature verification – we use hash_equals to protect against timing attacks.
• Missing pending status handling – an order may sit in "Pending" forever if the callback is not processed.
• Ignoring partial refunds – the client cannot return part of the goods, requiring rework.
• Hardcoded webhook URL – changing the domain breaks everything; we use home_url('/wc-api/mypay_callback').

How We Ensure Webhook Security

To protect against fake callbacks, we verify signatures using hash_equals and HMAC. We additionally filter provider IP addresses and log all incoming requests. WordPress Coding Standards recommend nonce and capability checks, but for webhooks that is insufficient—cryptographic signing is required. Example verification:

function verify_webhook_signature($payload, $signature, $secret) {
    $expected = hash_hmac('sha256', $payload, $secret);
    return hash_equals($expected, $signature);
}

Testing We Perform

• PHPUnit unit tests for the API client: verify correct request serialization, error handling, timeouts.
• Integration tests in the provider sandbox with Ngrok: emulate full payment cycle, webhooks, partial refunds.
• Manual testing in the admin panel: test the refund button, logs, order statuses.

All tests run in CI before deployment.

Development Process

1. Analysis – review the provider's REST API, gather requirements (single‑stage payment, subscriptions, refunds).
2. Design – draw an order state diagram, agree on webhook schema.
3. Implementation – write the gateway class, API client, webhook handler. Typically 2–4 days for basic integration.
4. Testing – unit tests, manual testing in sandbox with Ngrok.
5. Deployment and documentation – deploy to production, train the admin, deliver a README with sample requests.

What's Included

• Full source code of the plugin in your repository (GitLab/GitHub).
• Documentation for installation, configuration, and operation (README with sample requests).
• Administrator training on plugin usage (gateway settings, log viewing, refunds).
• Warranty support for 14 days after delivery, including free revisions for the current gateway.

Timeline and Pricing

Basic integration of one gateway takes 2 to 5 business days. Pricing is calculated individually—depending on the provider API complexity and additional features required (subscriptions, multi‑currency). We estimate your project within one business day. Get a consultation for integrating your gateway—contact us by email or through the website form. Order integration, and we will prepare a proposal.

Example Cost Savings

By building a custom gateway instead of using an outdated plugin, our clients save up to $2,000 annually in maintenance and support fees. For instance, one e‑commerce store reduced payment processing errors by 80% after switching to our solution, translating to $5,000 monthly savings in lost revenue. Our gateway processes payments 3 times faster than the standard plugin, reducing checkout abandonment by 15%.

Guarantees

• Code complies with WordPress Coding Standards.
• Full backward compatibility with WooCommerce 8+.
• All methods are protected against direct calls—we use wp_die with correct response codes.
• Our solutions have been battle‑tested on 20+ projects, including large e‑commerce stores with monthly turnovers exceeding $10,000.

Contact us to discuss your project—we will prepare a proposal and timeline.

Payment System Integration: YooKassa, Stripe, PayPal, Apple Pay, Google Pay

Conversion dropped by 12% immediately after the redesign. The team pushed a new SPA checkout on Vue 3, forgetting to handle fallback scenarios. Sentry logged a flurry of errors: Payment method not available, 3DS2 challenge flow failed, webhook signature verification failed. Users abandoned carts at the payment method selection stage. Inspection revealed Stripe Elements wasn't receiving the correct clientSecret after redirect, and the webhook endpoint responded with 500 due to lack of idempotency. After replacing the checkout form with a custom integration storing event IDs in Redis, errors disappeared and conversion recovered within two days. The goal isn't just to "connect an SDK"—payment processing requires synchronization with bank requirements, SCA in Europe, and Federal Law 54-FZ in Russia. Our experience: 7 years of integrations for 50+ projects, from e-commerce stores to SaaS platforms with million-dollar turnovers.

What's Included in Turnkey Work

• Audit of current payment flow and requirements (currencies, fiscalization, subscriptions).
• Provider selection based on geography and business model.
• Backend integration (Laravel/Node.js/Go) with webhook handling, idempotency, and retries.
• Frontend widget (Stripe Elements / YooKassa SDK) with Apple Pay and Google Pay support.
• Testing all scenarios: success, decline, 3DS, refunds, correction receipts.
• Monitoring of first transactions and documentation.

We will evaluate your project within 1 day—contact us via chat for a consultation.

Provider Comparison: Which to Choose

Stripe wins on flexibility: 135+ currencies vs. YooKassa's single currency. But for Russia with 54-FZ and SBP, YooKassa is 3x faster to integrate—no external OFD needed. For subscriptions, Stripe Billing is a ready-made engine with trials and email notifications in 2 clicks.

How to Choose the Right Provider?

Three key points. Where do your clients live? Only Russia → YooKassa; globally → Stripe. Do you need 54-FZ fiscalization? Yes → YooKassa; otherwise Stripe + cloud OFD. Do you plan subscriptions? Yes → Stripe Billing as the benchmark; YooKassa requires custom logic with auto-payments. Saving on commissions by choosing the right provider can amount to up to 1.5% of turnover. For a project with 2 million RUB per month, that's 360,000 RUB per year.

Where the Real Difficulties Lie

Setting up a test mode takes an hour. Properly handling all scenarios takes weeks.

Webhook reliability. A webhook may not arrive—server unavailable, timeout, network issues. The provider retries with exponential backoff (Stripe up to 3 days). The handler must be idempotent: if payment.succeeded arrives twice with the same payment_id, the order is updated only once. This is implemented by storing event IDs in Redis with a TTL.

3DS2 and redirect flow. When paying with a card with 3DS2, the user goes to the bank's page and then returns via return_url. During this time, the session may expire or the cart may be cleared. The status is verified not by query parameters but by a direct API request to the provider upon return.

Partial refunds and receipts. A client returns part of the goods—this requires a correction receipt (Federal Tax Service) and a partial refund in YooKassa. Stripe natively supports partial_refund. In both cases, synchronizing statuses between the payment system, database, and warehouse is a separate task.

Currency limitations. YooKassa only handles rubles. If a client from Russia pays in euros via Stripe, conversion goes through their bank, and you don't control the exchange rate.

Why Do Webhooks Require Idempotency?

A webhook may be delivered twice due to network timeouts or provider retries. Without idempotency, the second call would duplicate the order or cause erroneous charges. The solution is to store a unique event ID (e.g., Stripe event id + timestamp) in Redis with a 24-hour TTL and check before processing. If the ID already exists, return 200 without executing business logic. Typical webhook integration mistakes: not verifying the HMAC signature (anyone could send a fake payment.succeeded), not using a queue (the handler blocks the response—provider considers it a failure and resends), not storing event ID (duplicates desynchronize statuses).

How We Build the Integration

Architecture. We never store card data—only tokens from the provider. Flow: Order in DB → Payment Intent → redirect/widget → webhook confirms → update status. The source of truth is the status in the payment system.

For Laravel we use stripe/stripe-php or yookassa-sdk. Webhook—a separate controller with VerifyCsrfToken exception, signature verification first line, Queue job for business logic.

For Next.js/React—@stripe/stripe-js + @stripe/react-stripe-js. PaymentElement includes Apple/Google Pay automatically. Example:

const stripe = await stripePromise;
const { error } = await stripe.confirmPayment({
  elements,
  confirmParams: { return_url: 'https://example.com/order/thank-you' },
});

Testing. Stripe CLI: stripe listen --forward-to localhost:8000/webhook. Test cards for all scenarios (3DS, decline, insufficient funds). Cypress checkout flow test in CI—mandatory stability guarantee.

We debugged Stripe Billing integration for a SaaS with 50,000 subscribers. The issue was handling invoice.payment_succeeded: the frontend updated the subscription immediately after redirect, but the webhook could be delayed by 10 seconds, and the status would be overwritten to incomplete. Solution—add polling API to check invoice status before showing the success page. This reduced erroneous cancellations by 18%.

Process and Timeline

Audit → provider selection → backend → frontend → tests → deploy → monitoring.

Pricing is custom. Order integration and your checkout won't crash on the next update.

Links:

• PCI DSS — Payment Card Industry Data Security Standard
• 3-D Secure — authentication protocol
• Webhook — callback mechanism

We guarantee: 7 years of experience, 50+ successful integrations. Contact us for an audit of your checkout—we will evaluate your project and choose the optimal provider.