WooCommerce Virtual POS Integration: 3D Secure, Refunds and Reconciliation

Causes of the “payment received, order pending” problem with a WooCommerce virtual POS: the 3D Secure flow, callback verification, status mapping, refunds and end-of-day reconciliation.
Technical summary
Technology
WooCommerce, EMV 3-D Secure, PCI DSS, HMAC, WP-CLI
Topic
Payment, refund and reconciliation flow in virtual POS and payment institution integrations
Level
Intermediate–advanced
Prerequisites
  • Familiarity with WooCommerce order statuses
  • Knowledge of PHP and the WordPress action/filter structure
  • Access to the payment provider’s test environment
In this article7 sections

The complaint “the card was charged but the order is still Pending payment” is the most common support ticket in WooCommerce virtual POS integrations. Activating the plugin and entering the merchant key is the easy part. The hard part is: verifying the 3D Secure return, moving the order to the right status, keeping refunds and cancellations in line with the bank record, and matching collections with accounting at the end of the day. The sequence below covers the points the e-commerce manager and the WooCommerce developer should go through before going live.

Direct bank POS or a payment institution

In corporate e-commerce projects, the first decision is whether you’ll collect payments directly through a bank’s virtual POS or through a payment institution licensed under Turkish Law No. 6493. The technical flow looks similar. The contract, integration load and daily operations differ.

Criterion Direct bank POS Payment institution
Contract Separate with each bank One contract, many banks
Installment campaigns Only that bank’s cards Depends on the institution’s agreements
Integration API specific to the bank’s infrastructure provider Usually a single, documented REST API
Card data Shared payment page or direct post Mostly a hosted form or iframe
Money transfer The bank’s value date rules The institution’s payout schedule
Reconciliation A separate report per bank One panel, one report

Companies with high turnover and bargaining power with certain banks go with a direct POS for the commission. It has a cost too: every new bank means separate testing, a separate hash algorithm and a separate reconciliation report. Three banks, three separate integrations. In the payment institution model there’s a single API integration; on the other hand, money reaches the account according to the institution’s payout schedule, and refund rules are only as flexible as the institution’s API allows.

Where card data is entered determines your PCI DSS burden. If the card number is taken entirely on a page or in an iframe hosted by the bank or the institution, the narrowest self-assessment questionnaire (SAQ A) usually applies. If card data is posted directly to the bank from a form on your page (direct post), the integrity of your payment page also comes into scope; this model involves SAQ A-EP, which has far more requirements. If card data passes through your server, the scope widens further. Confirm which questionnaire applies to you with your payment provider and the PCI Security Standards Council documents; don’t decide by guesswork.

The 3D Secure payment flow step by step

EMV 3-D Secure is the protocol in which the card-issuing bank verifies the cardholder’s identity. Current implementations use 3DS 2.x; based on device and transaction data, the bank either directs the user to SMS verification or gives a silent (frictionless) approval. On the WooCommerce side, the typical flow works like this:

  1. The customer confirms the order on the checkout page; WooCommerce opens the order with pending (Pending payment) status, and stock is reserved for the “Hold stock” period in the settings.
  2. The payment gateway class’s process_payment() method prepares a request with the order number, amount, currency, number of installments and the success and failure return URLs, and signs it with the merchant key.
  3. The customer goes to the bank’s or institution’s 3D page and completes verification.
  4. The bank can report the result through two channels: a POST to the return URL via the browser and a server-to-server notification (callback). Which channels exist depends on the provider.
  5. In some direct POS models, 3D verification alone isn’t a collection; if verification succeeds, a second API call is needed for authorization.
  6. After the result is verified, the order is moved to processing status, the transaction number is written to the order and the customer lands on the thank-you page.

The mistake we see most often in the field is skipping the fifth step. The developer sees “success” on the 3D return and treats the order as paid; since the authorization call is never made, the money isn’t collected.

Callback verification and order status mapping

Data arriving at the return URL passes through the customer’s browser. It isn’t trustworthy. At least these checks are made on every notification:

  • Signature/hash verification: The hash is recalculated with the fields defined by the provider and the merchant key, and checked with a constant-time comparison (hash_equals).
  • Amount and currency: The amount in the notification must equal the order’s get_total() value. If an installment surcharge applies, the difference must be reflected in an order line.
  • Order match: The reference sent to the provider must match the reference in the notification, and the order must be in a status awaiting payment.
  • Repeats (idempotency): If the same transaction number arrives a second time, the order isn’t processed again; only a note is added.
  • Query API if possible: If the provider offers a transaction query service, the result is queried once more on the server side.

In WooCommerce, a server-to-server notification is handled with the woocommerce_api_{name} action; the URL has the form /?wc-api=name. The skeleton below shows the flow; hash fields and result codes are filled in according to the provider’s documentation.

add_action( 'woocommerce_api_example_pos', function () {
    $data  = wp_unslash( $_POST );
    $order = wc_get_order( absint( $data['order_ref'] ?? 0 ) );
    if ( ! $order ) { status_header( 404 ); exit; }

    $expected = base64_encode( hash_hmac( 'sha256', $data['order_ref'] . $data['amount'] . $data['status'], STORE_KEY, true ) );
    if ( ! hash_equals( $expected, (string) ( $data['hash'] ?? '' ) ) ) {
        $order->add_order_note( 'Payment notification with invalid signature rejected.' );
        status_header( 400 ); exit;
    }
    if ( $order->is_paid() ) { echo 'OK'; exit; }   // repeated notification

    if ( wc_format_decimal( $data['amount'], 2 ) !== wc_format_decimal( $order->get_total(), 2 ) ) {
        $order->update_status( 'on-hold', 'Amount mismatch, manual check required.' );
        exit;
    }
    if ( 'success' === $data['status'] ) {
        $order->payment_complete( sanitize_text_field( $data['transaction_id'] ) );
    } else {
        $order->update_status( 'failed', 'Bank result: ' . sanitize_text_field( $data['error_code'] ?? '' ) );
    }
    echo 'OK'; exit;
} );

payment_complete() moves the order to completed only if it consists entirely of products that are both virtual and downloadable, and to processing otherwise; it records the transaction number and triggers the stock reduction. Always access order data through WC_Order methods. Old code that reads post meta directly returns empty or stale values in a store with high-performance order storage (HPOS) enabled; it doesn’t throw an error, it silently works wrong.

We recommend mapping provider results to WooCommerce statuses like this:

Provider result WooCommerce status Note
Authorization approved processing via payment_complete()
3D verification failed failed The customer can try again
Amount or signature mismatch on-hold Manual review
Result unknown / timeout pending Re-check with the query API
Refunded (full) refunded Bank refund number in the note

Refund, cancellation and partial refund scenarios

On the bank side there are two separate transactions. A cancellation is made before the transaction enters end-of-day settlement and removes the authorization completely; it often never appears on the card statement. A refund is for a settled transaction, can be full or partial, and the amount reaches the cardholder within the bank’s own timeframe. Some providers combine the two in a single endpoint and decide by date themselves; others require separate calls. Don’t assume without reading the documentation.

When refunds is added to the gateway’s supports array and the process_refund( $order_id, $amount, $reason ) method is written, the refund button on the order screen calls the provider API. Things to check:

  • For partial refunds on installment transactions, check the provider’s rule; some infrastructures restrict partial refunds on installment sales.
  • If the API call fails, the method must return a WP_Error. Otherwise WooCommerce records the refund as done, while the money never reaches the customer.
  • The “manual refund” option only changes the order record; it doesn’t call the bank. Refunds made from the bank panel must be entered into WooCommerce separately.
  • Write the refund amount and the bank refund reference in the order note; that’s the first place to look in reconciliation.

End-of-day reconciliation

Reconciliation verifies that three sources say the same thing: WooCommerce orders, the provider’s transaction report and the amount credited to the bank account. A job running daily matches the previous day’s records by transaction number and lists the differences. Types of difference to look for:

  • Transactions successful at the provider but pending, failed or cancelled in WooCommerce (an order where money was taken but that won’t be shipped).
  • Orders that appear paid in WooCommerce but aren’t in the provider report.
  • Amount differences: installment surcharge, partial refund, amount after coupon.
  • Refunds made from the panel but not entered on the order.
  • Consistency of commission and value date information with the accounting record.

The WooCommerce-side listing is taken with WP-CLI; for example, the command wp wc shop_order list --status=processing --after=2026-11-09T00:00:00 --fields=id,total,transaction_id --user=1 gives the list to compare with the provider report (the field names and parameters are the same as the WooCommerce REST API’s orders endpoint). Store the results in a table, and have a notification go to the person responsible when a difference appears. If nobody looks, reconciliation hasn’t been done. The general design of these checks is explained in detail in the integration monitoring and reconciliation guide.

Common payment errors and their fixes

Payment was received but the order stayed in “Pending payment”

The first places to look are the web server and WAF logs. Typical causes: the server-to-server notification being blocked by the WAF, a Cloudflare rule or an IP restriction; the notification URL being page-cached; the customer closing the browser after 3D and the system relying only on the browser return. The fix: keep the notification URL out of caching and bot protection, allow the provider’s outbound IPs, and run a scheduled job that periodically checks pending orders with the query API. How to set up cache exclusions is in the WooCommerce cache errors article.

The customer’s session and cart are lost on the bank return

The return from the bank page is a POST request coming from another domain. SameSite=Lax cookies aren’t sent with this request, so the WooCommerce session isn’t visible. The return handler should rely on the order number and the order key (order_key), not the session; when processing is done, the user should be redirected to the thank-you page with a GET.

A paid order was cancelled automatically

When the “Hold stock (minutes)” period expires, unpaid orders are cancelled. If the customer waits a long time on the 3D page, the bank approval arrives for a cancelled order. The callback handler should recognize this case; instead of reopening the order on its own, it should move it to on-hold and have the stock checked, or start the refund process.

The same order was charged twice

A double click on the pay button or a retry with the back button can produce two requests with the same order reference. Give each attempt a separate transaction reference, don’t create a new payment request for a paid order, and report multiple successful transactions linked to the same order separately in reconciliation.

Before going live, try these scenarios one by one in the test environment: success, failure, timeout, partial refund and repeated notification. A scenario that hasn’t been tried blows up in production. For the store’s overall setup and choice of provider, see the WooCommerce e-commerce solutions page; the post-order logistics flow is the subject of the WooCommerce shipping integration guide.

Frequently asked questions

Should a ready-made plugin or custom development be used for a virtual POS?

If the provider’s official or widely used plugin provides callback verification, refund support and HPOS compatibility, use it first. Custom development makes sense when you need installment routing across several banks, ERP-specific reference fields or a refund model the plugin doesn’t support.

Is it possible to take payments without 3D Secure?

Some providers allow transactions without 3D Secure under certain risk rules, but in that case most of the chargeback and fraud risk stays with the merchant. In a corporate store, 3D Secure should be the default, and exceptions should be defined in writing with the provider.

What’s the difference between a cancellation and a refund?

A cancellation is made before the transaction enters end-of-day settlement and removes the authorization completely. A refund is made for a settled transaction, can be full or partial, and the amount reaches the cardholder within the bank’s own timeframe. The provider’s API rules determine which one applies.

How often should reconciliation be done?

Every day. The previous day’s WooCommerce orders are matched with the provider’s report by transaction number, differences are listed and reported to the person responsible. The check of the amount credited to the account and the commission is done separately according to the provider’s transfer schedule.

Support

Contact us for support or a discovery session on this topic.

Contact form
[email protected]

Eretek Web

We build and maintain corporate websites, WordPress and CMS platforms, intranet and SharePoint portals, document management, and form and approval workflows, and keep them secure and up to date.

Knowledge Center

Other articles