WooCommerce Bitcoin Payments: Complete Setup Guide

WooCommerce powers over 30% of all online stores. Adding Bitcoin and crypto payments opens your store to millions of new customers while cutting transaction fees.

This guide walks you through setup, configuration, testing, and troubleshooting—everything you need to accept crypto confidently.

Table of Contents

1. Why Add Bitcoin Payments
2. What You Need
3. Choosing a Plugin
4. Installation Steps
5. Payment Settings
6. Testing
7. Checkout Customization
8. Orders and Refunds
9. Security
10. Troubleshooting
11. Advanced Setup

Why Add Bitcoin Payments to WooCommerce

Reach More Customers

Over 420 million people own cryptocurrency. Many actively look for stores that accept it. Adding Bitcoin to your WooCommerce store helps you:

• Attract crypto users who prefer digital payments
• Sell globally without complex international processing
• Reduce cart abandonment from customers who can't use traditional methods

Cut Transaction Fees

Here's what you keep from a $100 sale:

Processing $10,000/month? That's $220 in monthly savings with crypto.

Stop Chargeback Fraud

Crypto transactions can't be reversed once confirmed. This eliminates chargeback fraud—a $40 billion problem for online stores. You control refund decisions, not payment processors.

Get Your Money Faster

Credit card processors hold funds for 2-7 days. With crypto, you can access funds in hours or minutes.

Prerequisites and Requirements

Before you start, make sure you have:

WordPress Setup

• WordPress 5.8 or higher
• WooCommerce 6.0 or higher
• PHP 7.4 or higher
• SSL certificate (HTTPS required)

Server Requirements

• 256MB PHP memory minimum
• cURL extension enabled
• JSON extension enabled

What You'll Need

1. WooCommerce store with products ready
2. PayCoinPro account (free)
3. API credentials from your dashboard
4. 30 minutes for setup and testing

Choosing a Payment Gateway Plugin

PayCoinPro Plugin (Recommended)

• 1% flat fee
• 10+ cryptocurrencies
• 8 blockchain networks
• Instant notifications
• No monthly fees

Best for: Most stores wanting reliable, low-fee processing.

BTCPay Server

• 0% processing fees
• Self-hosted (you manage servers)
• Bitcoin and Litecoin only

Best for: Technical users wanting full control.

CoinGate

• 1% fee
• 70+ cryptocurrencies
• Hosted solution

Best for: Stores wanting maximum coin options.

Our Recommendation

PayCoinPro offers the best balance of features, ease of use, and pricing for most WooCommerce stores. This guide uses PayCoinPro, but the concepts work with other gateways too.

Step-by-Step Installation Guide

Step 1: Create Your Account

1. Visit paycoinpro.com/auth/register
2. Enter your email and password
3. Verify your email
4. Complete your profile

Time: 2 minutes

Step 2: Get Your API Keys

1. Log into your PayCoinPro dashboard
2. Go to Settings → API Keys
3. Click "Generate New API Key"
4. Copy your API Key and API Secret
5. Copy your Webhook Secret too

⚠️ Important: Save these securely. The API Secret won't show again.

Time: 1 minute

Step 3: Install the Plugin

From WordPress:

1. Go to Plugins → Add New
2. Search "PayCoinPro"
3. Click Install Now, then Activate

Manual upload:

1. Download from PayCoinPro Downloads
2. Go to Plugins → Add New → Upload Plugin
3. Upload the ZIP file and activate

Time: 2 minutes

Step 4: Configure the Plugin

1. Go to WooCommerce → Settings → Payments
2. Find "PayCoinPro - Crypto Payments" and click Manage
3. Turn on the payment method
4. Enter your credentials:
   • API Key
   • API Secret
   • Webhook Secret

Time: 2 minutes

Step 5: Set Up Webhooks

1. Copy the webhook URL from plugin settings (looks like https://yoursite.com/wc-api/paycoinpro_webhook)
2. In PayCoinPro dashboard, go to Settings → Webhooks
3. Add the webhook URL
4. Select events: invoice.paid, invoice.expired, invoice.underpaid
5. Save

Time: 2 minutes

Configuring Payment Settings

Basic Settings

Enable/Disable: Show or hide crypto at checkout.

Title: What customers see (e.g., "Pay with Bitcoin & Crypto").

Description: Text below the title (e.g., "Pay securely with Bitcoin, Ethereum, USDT, and more").

Order Status on Payment: Choose what happens when payment arrives:

• Processing — For physical products that need shipping
• Completed — For digital products with instant delivery

Cryptocurrency Options

Choose which coins to accept:

Recommended setup: Start with USDT, USDC, and BTC on multiple networks. Add more based on customer requests.

Network Options

Choose which blockchains to support:

• Ethereum — Most widely used
• BSC (BNB Chain) — Low fees, popular in Asia
• Polygon — Very low fees, fast
• TRON — Popular for USDT
• Arbitrum — Low fees with Ethereum security
• Base — Coinbase ecosystem
• Solana — Ultra-fast, minimal fees
• Bitcoin — For BTC payments

Advanced Settings

Invoice Expiration: How long customers have to pay. Default is 30 minutes. Longer times give flexibility but add exchange rate risk.

Required Confirmations: How many blockchain confirmations before marking payment complete:

• Bitcoin: 1-3 (10-30 minutes)
• Ethereum/ERC-20: 12 (about 3 minutes)
• Other networks: Usually 1-20 blocks

Underpayment Threshold: Accept payments slightly under the invoice amount. Set 1-2% to cover network fees customers might underpay.

Testing Your Integration

Using Test Mode

PayCoinPro has a test mode for safe testing:

1. Enable Test Mode in plugin settings
2. Use test API credentials from the sandbox
3. Make test purchases
4. Disable test mode when ready

Testing Checklist

Run these tests before going live:

Basic Flow

• Add product to cart
• Go to checkout
• Select crypto payment
• Verify invoice shows correctly
• Check order status updates

Mobile Testing

• Complete checkout on phone
• Scan QR code with wallet app
• Verify it works

Webhook Testing

• Confirm webhook URL is accessible
• Verify orders update automatically
• Check payment shows in WooCommerce

Edge Cases

• Test expired invoice handling
• Test different cryptocurrencies
• Verify email notifications work

Live Testing

For a real test with small amounts:

1. Create a $1 test product
2. Make a real purchase with actual crypto
3. Watch the full process
4. Test a refund

Customizing the Checkout Experience

Change How Crypto Appears

Add to your theme's functions.php:

php
Copy
// Add emoji to payment method title
add_filter('woocommerce_gateway_title', function($title, $gateway_id) {
    if ($gateway_id === 'paycoinpro') {
        return '💎 ' . $title;
    }
    return $title;
}, 10, 2);

// Add trust message below payment option
add_action('woocommerce_review_order_after_payment', function() {
    echo '<div class="crypto-trust-badges">';
    echo '<img src="/wp-content/uploads/bitcoin-accepted.png" alt="Bitcoin Accepted">';
    echo '<p>Secure crypto payments powered by PayCoinPro</p>';
    echo '</div>';
});

Add "We Accept Crypto" Badge

Show accepted payments on product pages:

php
Copy
// Add crypto badge to product pages
add_action('woocommerce_single_product_summary', function() {
    echo '<div class="crypto-accepted-badge">';
    echo '<span>We accept: BTC, ETH, USDT, USDC</span>';
    echo '</div>';
}, 35);

Add Refund Wallet Field

Let customers enter a wallet address for refunds:

php
Copy
// Add optional refund wallet field
add_filter('woocommerce_checkout_fields', function($fields) {
    if (WC()->session->get('chosen_payment_method') === 'paycoinpro') {
        $fields['billing']['refund_wallet'] = [
            'type' => 'text',
            'label' => 'Refund Wallet Address (optional)',
            'required' => false,
            'class' => ['form-row-wide'],
            'placeholder' => 'Your crypto wallet for potential refunds'
        ];
    }
    return $fields;
});

Handling Orders and Refunds

Order Status Flow

Orders move through these stages:

1. Pending — Invoice created, waiting for payment
2. On Hold — Payment detected, waiting for confirmations
3. Processing — Payment confirmed, ready to ship
4. Completed — Order fulfilled

Viewing Crypto Orders

Crypto orders appear in WooCommerce → Orders like any other. Extra details include:

• Cryptocurrency and amount paid
• Blockchain network used
• Transaction hash (links to block explorer)
• PayCoinPro invoice ID

Processing Refunds

Full Refund:

1. Open the order
2. Click Refund
3. Select items and enter amount
4. Choose refund method:
   • PayCoinPro balance — Refund from your merchant account
   • Manual — Send crypto directly to customer

Partial Refund: Same process—just enter the partial amount.

Sending to Customer's Wallet:

1. Copy the wallet address from order notes
2. Go to Withdrawals in PayCoinPro
3. Enter address and amount
4. Confirm

Adding Order Notes

Track crypto details automatically:

php
Copy
// Add crypto payment details to order notes
add_action('woocommerce_payment_complete', function($order_id) {
    $order = wc_get_order($order_id);
    if ($order->get_payment_method() === 'paycoinpro') {
        $order->add_order_note(sprintf(
            'Crypto payment confirmed. Network: %s, TxHash: %s',
            get_post_meta($order_id, '_paycoinpro_network', true),
            get_post_meta($order_id, '_paycoinpro_txhash', true)
        ));
    }
});

Security Best Practices

Protect Your API Credentials

Never put credentials in frontend code:

php
Copy
// BAD - Don't do this
<script>
const apiKey = '<?php echo PAYCOINPRO_API_KEY; ?>';
</script>

// GOOD - Keep credentials server-side
// Store in wp-config.php
define('PAYCOINPRO_API_KEY', 'your_key_here');

Use environment variables:

php
Copy
// In wp-config.php
define('PAYCOINPRO_API_KEY', getenv('PAYCOINPRO_API_KEY'));
define('PAYCOINPRO_API_SECRET', getenv('PAYCOINPRO_API_SECRET'));

Verify Webhooks

Always check webhook signatures:

php
Copy
function verify_paycoinpro_webhook($payload, $signature) {
    $secret = get_option('paycoinpro_webhook_secret');
    $expected = hash_hmac('sha256', $payload, $secret);
    return hash_equals($expected, $signature);
}

Use HTTPS

Crypto payment pages must use HTTPS:

• Install SSL (free via Let's Encrypt)
• Force HTTPS in WordPress
• Fix any mixed content warnings

Keep Everything Updated

Update regularly:

• WordPress core
• WooCommerce
• PayCoinPro plugin
• PHP version

Troubleshooting Common Issues

Crypto Option Not Showing at Checkout

Check these:

1. Plugin not enabled — Go to WooCommerce → Settings → Payments and turn it on

2. Wrong API credentials — Verify key and secret are correct. Watch for extra spaces.

3. Currency not supported — Make sure your store currency works (USD, EUR, etc.)

4. Test mode is on — Turn it off for live transactions

Orders Not Updating

Try these steps:

1. Check webhook URL — Should be https://yoursite.com/wc-api/paycoinpro_webhook

2. Look at server logs:

   bash
   Copy
   tail -f /var/log/apache2/error.log

3. Test manually — Use "Test Webhook" in PayCoinPro dashboard

4. Check security plugins — Whitelist PayCoinPro IPs if needed

Invoice Shows Wrong Amount

Common causes:

1. Tax or shipping missing — Check those settings

2. Currency mismatch — WooCommerce currency should match invoice

3. Coupon issues — Test with coupons disabled

Payment Not Detected

Look for:

1. Wrong network — Customer may have sent on unsupported network

2. Below minimum — Very small payments may not meet minimums

3. Address reuse — Each invoice needs a unique address

Advanced Configuration

Multi-Currency Stores

Set invoice currency dynamically:

php
Copy
// Match invoice to WooCommerce currency
add_filter('paycoinpro_invoice_currency', function($currency) {
    return get_woocommerce_currency();
});

Custom Status Mapping

Map PayCoinPro statuses to your own:

php
Copy
add_filter('paycoinpro_status_mapping', function($mapping) {
    return [
        'new' => 'pending',
        'pending' => 'on-hold',
        'confirming' => 'on-hold',
        'paid' => 'processing',
        'complete' => 'completed',
        'expired' => 'cancelled',
        'invalid' => 'failed'
    ];
});

Subscription Support

Enable crypto for WooCommerce Subscriptions:

php
Copy
add_filter('woocommerce_subscription_payment_gateway_supports', function($supports, $gateway_id) {
    if ($gateway_id === 'paycoinpro') {
        $supports[] = 'subscriptions';
        $supports[] = 'subscription_cancellation';
        $supports[] = 'subscription_reactivation';
    }
    return $supports;
}, 10, 2);

Google Analytics Tracking

Track crypto checkouts:

javascript
Copy
// Add to theme or via Google Tag Manager
jQuery(document).on('checkout_place_order_paycoinpro', function() {
    gtag('event', 'begin_crypto_checkout', {
        'payment_method': 'crypto',
        'value': jQuery('.order-total .amount').text()
    });
});

Launch Checklist

Before announcing crypto payments:

• Turn off test mode
• Verify live API credentials
• Make a real test purchase
• Confirm webhooks work
• Test refunds
• Update privacy policy
• Update terms of service

Promote Your New Option

On your site:

• Add "Now Accepting Bitcoin" banner
• Show payment badges on product pages
• Add crypto icons to footer

On social media:

• Announce on Twitter/X
• Post in relevant subreddits
• Tell your email list

For SEO:

• Add "We Accept Bitcoin" to meta descriptions
• Create a dedicated landing page

---

Start Accepting Bitcoin Today

You're ready to accept Bitcoin and cryptocurrency on your WooCommerce store. Setup takes less than 30 minutes and opens your business to millions of crypto users.

Quick Start:

1. Create your PayCoinPro account — Free, no credit card
2. Get API keys — Dashboard → Settings → API Keys
3. Install the plugin — Search "PayCoinPro" in WordPress
4. Configure and test — Follow this guide
5. Go live! — Start accepting crypto

Need help? Check our WooCommerce docs or email support@paycoinpro.com.

---

Ready to grow your WooCommerce sales with cryptocurrency? Get started with PayCoinPro — free to sign up, you only pay when you get paid.