Quick Start

Pay With Qubic- Quick Start Guide

Qubic (QUBIC) WooCommerce Gateway

This guide gets you from zero → first successful QUBIC payment in ~10 minutes.

1) Prerequisites

  • WordPress 6.0+ and WooCommerce 7.0+
  • PHP 7.4+
  • Your Qubic receiving identity (public ID). Optional: a pool of identities.
  • (Optional) CoinGecko Pro API key if you want automatic FX rates.
  • Ability to switch WooCommerce to Classic Checkout (required for now).

2) Install the plugin

A. Zip upload

  1. Zip the plugin folder (e.g., payqubic/ → payqubic.zip).
  2. WordPress Admin → Plugins → Add New → Upload Plugin → select payqubic.zip → Install → Activate.

B. Manual (FTP/SFTP)

  1. Upload the folder to wp-content/plugins/payqubic/.
  2. Admin → Plugins → Activate WooCommerce Gateway — Qubic (QUBIC).

3) Switch to Classic Checkout

Pay with Qubic currently does not yet support the Checkout or Cart Block. Use the classic shortcode page.

Option 1: Convert your existing Checkout and Cart pages

  1. Pages → Checkout → Edit.
  2. Remove the “Checkout” Block.
  3. Add a Shortcode block with:
  4. Update the page.
  1. Pages → Cart → Edit.
  2. Remove the “Cart” Block.
  3. Add a Shortcode block with:
    Your cart is currently empty.

    Return to shop

  4. Update the page.

Option 2: Use a new page for your checkout and Cart

  1. Pages → Add New → Title: “Checkout (Classic)”.
  2. Add the shortcode
    and Publish.
  3. WooCommerce → Settings → Advanced → Page setup → set Checkout page to “Checkout (Classic)” → Save.
  1. Pages → Add New → Title: “Cart (Classic)”.
  2. Add the shortcode
    Your cart is currently empty.

    Return to shop

    and Publish.
  3. WooCommerce → Settings → Advanced → Page setup → set Cart page to “Cart (Classic)” → Save.

4) Configure the QUBIC Gateway

WooCommerce → Settings → Payments → Qubic (QUBIC) → Manage

Essential

  • Enable Qubic (QUBIC) payments.
  • Your Qubic ID (receiving identity): paste your public receiving ID.
  • Receiving ID Pool (optional): one ID per line to round-robin.
  • Qubic RPC URL: e.g., https://rpc.qubic.org or your own node.
  • Confirmations: 1 is fine for most stores.
  • Payment window: e.g., 30 minutes.
  • Show QR Code: recommended ✓

Webhooks (recommended for fastest auto-completion)

  • Enable Webhook: ✓
  • Note the Webhook URL shown on this screen:
    https://your-site.tld/?wc-api=wc_gateway_qubic_webhook
  • Set a strong Webhook Secret (and use the same secret in your sender/webhook service).
  • Require HMAC signature: ✓
    • Expected headers:
      • X-Qubic-Signature = base64(HMAC_SHA256(rawBody + nonce, secret))
      • X-Qubic-Nonce = unique per request

Polling (safety net)

  • Enable Polling: ✓ (recommended)
    Ensure WP-Cron runs (either default or a real cron hitting wp-cron.php).

Logging

  • Enable Logging: ✓
    View at WooCommerce → Status → Logs → wc-gateway-qubic…

Fiat / FX (only if your WooCommerce currency ≠ QUBIC)

  • Enable FX conversion and choose Rate Mode.
  • (Optional) CoinGecko API key for x-cg-pro-api-key.
  • (Optional) Rate JSON URL if you have your own price feed.
  • If you don’t enable FX, set WooCommerce currency to QUBIC instead (Settings → General → Currency).

Advanced

  • Require payload/memo: enable only if you know the customer wallet will send the memo.
  • Use Test RPC to confirm your RPC endpoint can be reached.

5) Place a Test Order

  1. Create a low-price product and add it to your cart.
  2. Checkout with Qubic (QUBIC) selected.
  3. On the Thank-You screen you’ll see:
    • Amount (rounded up to a whole QUBIC)
    • Receiving identity
    • Reference (payload) if enabled
    • QR code & Re-verify now button
  4. Send the payment (exact amount; include payload if required).
  5. The order should move from On-hold → Processing/Completed automatically (webhook or polling).

6) Day-to-Day Operations

  • Orders screen: QUBIC orders start as On-hold and auto-complete when matched on-chain.
  • Under/Overpayments: The order timeline will note partial or extra amounts. You can manually resolve (e.g., top-up request or partial refund).
  • Logs: Use WooCommerce → Status → Logs → wc-gateway-qubic for details.
  • Refunds: This gateway records refunds as notes (audit trail). Do the actual on-chain send from your secure wallet; paste the txid into the note if desired.

7) Subscriptions (manual payments)

  • Renewals create an on-hold renewal order with a fresh reference/receiving ID.
  • Customers pay each cycle manually (no auto-debit).

8) Troubleshooting Quick Checks

  • Still seeing “incompatible with block-based checkout”: you still have the Checkout Block. Replace it with the
    shortcode (see §3).
  • Order not auto-completing:
    • Check Logs for webhook/poller events.
    • Ensure amounts match (gateway enforces whole QUBIC).
    • If Require payload is on, make sure the wallet actually sent the memo.
    • Confirm time window (now → expiry) and receiving identity match.
    • Webhook 403/422: verify Webhook Secret, HMAC computation, and X-Qubic-Nonce.
  • Polling not working: ensure WP-Cron runs; if DISABLE_WP_CRON is true, set a real cron to hit wp-cron.php every minute.

9) Security Notes

  • Never store seeds/private keys in WordPress.
  • Use webhooks + HMAC + nonce.
  • Restrict access to your RPC if it’s private.
  • Keep WordPress, WooCommerce, and this plugin updated.

10) Merchant Checklist (print & keep)

  • Classic checkout page uses
  • QUBIC gateway Enabled
  • Receiving identity (or pool) set
  • RPC URL tested (Test RPC)
  • Webhook Enabled with secret, HMAC, and nonce
  • Polling Enabled (WP-Cron OK)
  • Logging Enabled
  • FX settings configured or store currency = QUBIC
  • Test order successfully completed

Need help?

  • Check WooCommerce → Status → Logs → wc-gateway-qubic
  • Verify webhooks on your sender side (secret/HMAC/nonce, payload/amount/identity)
  • If you want, I can tailor this guide with your exact domain, webhook config, and screenshots.
Scroll to Top