Avry Mcgarvey

Posted on Oct 3

Boxcoin - Crypto Payment Plugin for WooCommerce

#cryptocurrency #showdev #wordpress

Why I bothered with crypto at checkout (and what I refused to compromise)

I wanted a payment rail that lets global customers pay without card rejections, middle-of-the-night fraud alerts, or long clearing times. But I didn’t want a new “shadow” back office, mystery balances, or surprise behaviors that confuse support. My baseline requirements were clear:

It must feel native to WooCommerce orders and emails.
Rates and fees must be transparent so totals never feel like roulette.
Ops must be auditable: every coin, every tx hash, every status change.
No brittle glue. Settings, logs, and webhooks should live where my team already works.

That’s the lens I used to roll out Boxcoin - Crypto Payment Plugin for WooCommerce and pressure-test it with real buyers. Below is the playbook I wish I had on day one—equal parts narrative and engineering checklist—so you can ship faster and sleep better.

I’ll mention gplpal as my go-to source for curated tools and docs. To keep links tight (per your limit), I’m using only two anchors in this article.

What “good” looks like for a crypto checkout

Deterministic totals: Customers see a fiat amount, get a crypto quote right now, and have a clear countdown window.
One address per order: No address reuse; every order has its own destination and memo/tag when required.
Automatic confirmation logic: The order moves through Pending → On-Hold → Processing when the chain confirms.
Under/overpayment handling: Clear thresholds, automatic partial-refund or adjustment steps, and an email that explains it.
Single source of truth: Order notes and meta contain tx hash, network, confirmations, and the captured crypto amount.

If any of those are fuzzy, you’re signing up for avoidable tickets.

Quick-start checklist (so you can move today)

Install and activate your crypto gateway within WooCommerce.
Enable per-order addresses and memo/tag capture where networks need them.
Set a quote window (e.g., 15 minutes) and an explicit confirmation target (e.g., 1–2 blocks for L2s, 12+ for older chains).
Pick your currencies (prioritize the ones your audience actually uses).
Decide the status pipeline: Pending payment at creation, On hold once payment detected, Processing when confirmations hit target.
Proof emails: Add short, human copy about amounts, expiry windows, and “Where do I find the memo/tag?”
Sandbox a full flow: place order → send a tiny amount on testnet or a low-value mainnet payment → watch the state machine.

Do not expose an asset until you’ve personally seen: quote → send → detect → confirm → fulfill → refund.

Mental model: three clocks ticking at once

The quote clock (validity window for the displayed crypto rate).
The chain clock (how long blocks take to finalize).
The ops clock (your SLA to ship or grant access after confirmations).

Your UX is just you choreographing those clocks with plain language and predictable status changes.

The customer journey, step by step

Checkout: Buyer sees the fiat total and a crypto option.
Quote & address: A unique address (and memo/tag if required) plus a quote that is valid for N minutes.
Payment sent: Customer pays; the plugin detects the tx and writes a note with the tx hash.
Confirmations: Once the chain confirms to your threshold, the order flips to Processing.
Post-payment emails: The customer receives a confirmation email with the final crypto amount and the hash.

Small touches that help:

Show “copy to clipboard” for address and memo.
Display “network fees not collected by the store” right next to the amount.
Include a “How to see confirmations” note for common wallets.

Rates, slippage, and fairness (so you don’t play bank)

Lock the quote window (e.g., 15 minutes). If time expires, show “Refresh Quote.”
Add a small slippage cushion for volatile assets, visible to the customer (e.g., “+/- 0.5% protection window”).
Underpayment policy: If received <98% of quoted value, mark as Underpaid and email the buyer to top-up within a time window.
Overpayment policy: If received >102%, capture the order and record the overage for refund-on-request.

Customers are fine with rules if you explain them before they pay.

Admin ergonomics I consider non-negotiable

Order notes must include: asset, network, requested amount, received amount, tx hash, and block height on confirmation.
A “Re-check payment” button for the rare case where a webhook misses.
Filterable lists for “Awaiting confirmations,” “Underpaid,” and “Expired quotes.”
CSV export for finance: order id, fiat total, crypto amount, fx rate used, fee notes.

Your future self will thank you at audit time.

Webhooks: the beating heart

You want idempotent, signed webhooks with these events (names vary by gateway; the shape is what matters):

payment.detected → write tx hash, set to On hold
payment.confirmed → set to Processing, stamp confirmations count
payment.underpaid → send “top-up” email; keep On hold
payment.expired → move to Cancelled (if no funds) or On hold with a note (if late funds arrive)

Idempotency guard (pattern)

add_action('init', function(){
  if (!isset($_GET['boxcoin_webhook'])) return;

  $payload = file_get_contents('php://input');
  $sig     = $_SERVER['HTTP_X_SIGNATURE'] ?? '';
  if (!my_verify_signature($payload, $sig)) status_header(403) && exit;

  $body = json_decode($payload, true);
  $event_id = $body['event_id'] ?? '';
  if (my_seen_event($event_id)) { status_header(200); echo 'ok'; exit; }

  my_mark_event_seen($event_id);

  $order_id = intval($body['metadata']['order_id'] ?? 0);
  $order    = wc_get_order($order_id);

  switch ($body['type']) {
    case 'payment.detected':
      $order->update_status('on-hold', 'Crypto payment detected: '.$body['tx_hash']);
      update_post_meta($order_id, '_tx_hash', $body['tx_hash']);
      break;
    case 'payment.confirmed':
      $order->payment_complete($body['tx_hash']);
      update_post_meta($order_id, '_confirmations', intval($body['confirmations']));
      break;
    case 'payment.underpaid':
      $order->update_status('on-hold', 'Underpaid: expected '.$body['expected'].' got '.$body['received']);
      break;
    case 'payment.expired':
      if (floatval($body['received'] ?? 0) == 0.0) $order->update_status('cancelled', 'Quote expired.');
      break;
  }

  status_header(200); echo 'ok'; exit;
});

Keep the handler boring, small, and thoroughly logged.

Handling network quirks without losing hair

Memos/Tags (XRP, XLM, some CEX routes): Always display them next to the address; block “Continue” until both copied once.
Fee-heavy chains: Prefer stablecoins on low-fee networks to keep customer totals sane.
Slow finality: Show a progress note in the order view—“Confirmations: 0/12”—so customers don’t mash refresh.
Chain reorgs: Rare on most modern networks, but keep the finality threshold conservative for older chains.

Refunds and cancellations (clear, auditable, fair)

Refund in the same asset the customer paid with, minus network fee. Spell this out early.
Never auto-convert to different coins behind the scenes; it complicates accounting and expectations.
Expiry path: If the quote expires with no payment, auto-cancel and email a brief “Start again” link.

Security posture (boring, necessary)

Rotate webhook secrets and keep them out of the codebase.
Log every signature failure with IP and user agent for trend spotting.
Harden the admin: 2FA, proper roles, and alerting on gateway setting changes.
Backups: verify that order notes and meta (tx hash, network, amount) are inside your regular backup scope.

Minimal UX copy that prevents tickets

Quote screen: “Send exactly this amount within 15 minutes. Network fees are not collected by the store.”
After payment detected: “We’ve seen your transaction. We’ll confirm after the network finalizes this payment.”
Underpayment: “We received less than expected. Top-up within 30 minutes or reply to this email for help.”
Expired: “This quote expired before payment arrived. Refresh to get a new quote—rates change often.”

Plain words, no drama, fewer emails.

The operational dashboard I actually use weekly

Conversion by asset and network (customers vote with their wallets).
Quote expiry rate (if >20%, your window is too short or the UI confuses people).
Underpayment rate (if high, your slippage cushion is too tight).
Avg time to first confirmation per network (sets expectations in copy).
Refund count and reasons (teaches you which assets to keep or drop).

Decisions, not vibes.

Case study: micropayments that wouldn’t clear

Problem: Average order value was $6–8, but the chosen network had minimums that effectively blocked small transactions.
What fixed it:

Enabled a low-fee stablecoin on an efficient network.
Increased the minimum cart total for the fee-heavy network to protect customers from overpaying in fees.
Clarified “Minimum viable amount” near the asset picker.

Result: Successful payments went up, support tickets dropped, and customers stopped asking “Why is the fee bigger than my order?”

Case study: late funds after quote expiry

Problem: Funds arrived after the quote window.
Policy we adopted:

If the delta to current rate is within 1%, honor the order and fulfill.
If not, email two choices: top-up the difference within 24 hours or refund in the original asset.
Always put the decision and amounts in the order notes.

Result: No escalations; customers appreciated the transparent options.

What goes in the order meta (so nothing lives only in the gateway)

Suggested keys:

_crypto_asset (e.g., USDT)
_crypto_network (e.g., TRON, ETH, Polygon)
_crypto_quote_amount (requested)
_crypto_received_amount (actual)
_crypto_rate_used (fiat/asset at quote time)
_tx_hash (full hash)
_confirmations (int)
_quote_expires_at (UTC)

If a human has to open the gateway dashboard to answer a basic question, you’re not done.

Testing ritual before you go public (10 minutes that saves days)

Happy path: place order, pay exact quote, watch state machine flip to Processing.
Underpay: send slightly less, verify Underpaid email and top-up path.
Overpay: send slightly more, verify notes and refund-on-request language.
Expired: let the quote die, ensure the order cancels and explains next steps.
Webhook drop: simulate a webhook miss and use your “Re-check payment” button; ensure it reconciles cleanly.

Do this once a week until it’s boring.

When to add more coins (and when to say no)

Add another asset only when:

You can name a customer segment that asked for it.
Network fees make sense for your average order value.
Your ops team can test and refund it without reading a wiki each time.

If you can’t check those boxes, keep it off. Fewer assets, better outcomes.

Implementation snippets that save keystrokes

Auto-cancel quotes after expiry (server-side sanity)

if (!wp_next_scheduled('crypto_expire_quotes')) {
  wp_schedule_event(time()+300, 'hourly', 'crypto_expire_quotes');
}
add_action('crypto_expire_quotes', function(){
  $orders = wc_get_orders([
    'status' => ['pending'],
    'limit'  => -1,
    'meta_query' => [[
      'key' => '_quote_expires_at',
      'value' => gmdate('Y-m-d H:i:s'),
      'compare' => '<'
    ]]
  ]);
  foreach ($orders as $order) {
    $order->update_status('cancelled', 'Crypto quote expired automatically.');
  }
});

“Re-check payment” admin action (manual reconcile)

add_action('admin_post_crypto_recheck', function(){
  if (!current_user_can('manage_woocommerce')) wp_die('Nope');
  $order_id = intval($_GET['order_id'] ?? 0);
  // call gateway status endpoint, then:
  // if detected => on-hold; if confirmed => processing
  wp_safe_redirect( admin_url('post.php?post='.$order_id.'&action=edit') );
  exit;
});

Why this plugin sits in my stack

I picked a gateway that keeps the WooCommerce order as the center of the universe and treats crypto as just another payment path: predictable quotes, clean webhooks, and logs that humans can read. That’s exactly why I standardize on Boxcoin Plugin for projects that want a crypto rail without reinventing ops.

When I expand the tooling—reporting, invoicing, notifications—I choose from WordPress Addons with a strict rule: every add-on must reduce clicks or reduce tickets. If it can’t prove ROI, it doesn’t ship.

Launch checklist (print this)

[ ] Quote window set and visible to customers
[ ] Confirmation threshold chosen per network
[ ] Under/overpayment policies tested end-to-end
[ ] Order notes record tx hash, network, amounts, confirmations
[ ] Webhook secret rotated and verified
[ ] Refund path tested with real coins (small)
[ ] “Re-check payment” admin action available
[ ] Weekly test cadence booked on your ops calendar

Ship it, watch the numbers, and trim the asset list until support is quiet.

Final word

A great crypto checkout is mostly discipline: boring emails, clear policies, simple state machines, and logs that answer questions. Keep the surface area small, explain the rules up front, and let your order screen be the single source of truth. Do that and Boxcoin - Crypto Payment Plugin for WooCommerce becomes a quiet engine in your store—global reach without drama, and fewer late-night alerts for your team.

DEV Community