Developer runbook to accept crypto on Drupal Commerce. Composer and drush install steps, API keys, webhook verification, testnet checks, security, plus a...
Yes, you can accept crypto on Drupal Commerce by installing a supported payment gateway module through Composer, then linking it to a processor or self-hosted gateway like BTCPay Server. The reliable path is: install the module, generate API keys, register a webhook URL with signature verification, and test the whole loop on testnet before you touch mainnet. Skip the webhook step and you’ll get paid orders that never update, which is the single most common failure developers run into.
TL;DR:
- Most crypto gateway modules for Drupal Commerce require Drupal 9 or 10, PHP 8.1 or higher, and a properly configured HTTPS endpoint for webhooks.
- Testing in sandbox or testnet mode is essential before switching to mainnet, with webhook verification and idempotency being critical to reliable order updates.
- Properly securing API keys and webhook secrets, along with signature validation, is vital to prevent order processing failures and security issues.
- Webhook delivery issues often stem from unreachable URLs, signature mismatches, or reference ID mismatches, which can be fixed by checking logs and configuration.
- Cryptopayr supports quick onboarding with no KYC, offers multiple integration options, and facilitates marketplace payouts, all without extra verification delays.
Before you run a single Composer command, confirm your stack can actually support the module you want. Most current crypto gateway modules target Drupal 9 or 10 with Commerce 2.x, and they expect PHP 8.1 or higher along with a working Composer setup.
Skipping the HTTPS requirement is the fastest way to waste an afternoon. Processors will not deliver webhook events to localhost, no matter how correctly the module is configured.
Once your environment checks out, the install itself is short. Following the standard Drupal Commerce installation docs keeps you aligned with the Composer patterns the Commerce maintainers actually test against.
composer require drupal/[module-name] from your project root, substituting the specific gateway module (for example, drupal/commerce_btcpay).composer update cautiously if the module pulls in new dependencies, and check for conflicts before committing the lockfile./update.php or running drush updb.drush en [module-name] -y, or toggle it on through the Extend UI at /admin/modules.drush cr and confirm the module now appears under enabled modules.Pro Tip: Read the module’s project page on Drupal.org before you install anything. Version-specific notes there (patch requirements, known conflicts with certain Commerce point releases) save you from debugging a problem someone already documented.
If the gateway plugin doesn’t show up after enabling, it’s almost always a cache issue or a missing dependency Composer silently skipped. Rerun composer why-not against the module name to see what’s blocking it.
Gateway configuration lives at /admin/commerce/config/payment-gateways, and this is where the module actually becomes functional rather than just installed.
Securing credentials and getting the webhook listener URL right are consistently the two steps that determine whether reconciliation works at all, according to the CoinsPaid module documentation. Get either one wrong and orders will process on the processor’s side while your store never finds out.
Redirect flows and API flows behave differently inside Commerce. A redirect (off-site) gateway sends the buyer to a hosted checkout page, creates an authorization transaction, then waits for the webhook to flip the order to “completed.” An API-based flow keeps the buyer on your site and updates payment state more directly through SDK calls. Modules like Coinsnap use the token-based off-site pattern, requiring a Trade ID and Token entered directly into the gateway config form.
Never point a fresh integration at mainnet. Every serious processor offers a sandbox or testnet mode, and that’s where your first ten checkouts belong.
Pro Tip: Store recently processed webhook event IDs in Drupal’s key/value storage with a short expiry. It’s a simple guard against duplicate deliveries turning one payment into two completed orders.
On-chain Bitcoin payments confirm slowly, sometimes minutes, sometimes longer depending on network congestion. Plan your order states around that delay, or consider a Lightning-enabled or instant-settlement processor if checkout speed matters to your buyers.
A crypto gateway that works in testing can still be a liability in production if credentials or webhook handling are loose.
Unmaintained payment modules are a production risk specifically because processors update their APIs faster than a stalled module can keep pace with.
Unpaid orders almost always trace back to one of three causes, and all three are fast to check.
Cryptopayr approaches this the same way most solid crypto gateway modules do, minus the parts that usually slow merchants down. It supports over 110 cryptocurrencies including Bitcoin and Ethereum, and onboarding skips the KYC paperwork that turns a same-day integration into a multi-week wait.
The pattern you choose depends on how much you want buyers to notice they are paying with crypto at all.
That’s backwards. The install command is the easy part; getting a webhook to fire correctly, verify its signature, and not double process on retry is where real integrations break.
The conventional advice treats testnet testing as optional or something you do once before launch. Treat it instead as a permanent staging habit. Processors change their webhook payloads, add new signature schemes, and deprecate endpoints more often than Drupal module maintainers can patch for. A module that worked perfectly in March can silently start failing signature checks in June if nobody re-tested it.
If you take one thing from this guide, make it idempotency. Not the module choice, not the gateway brand. A duplicate webhook delivery that creates a second completed order is a customer service disaster that looks like a security breach. Store event IDs, check them before processing, and you’ve solved the failure mode that actually costs merchants money and trust.
— Dustin
Most Drupal Commerce crypto modules connect you to a processor, but that processor still puts you through a verification queue before you can accept a single payment. Some crypto payment gateways offer no-KYC onboarding, instant approval, and tiered transaction fees designed to suit varying merchant volumes.
Whether you want a hosted checkout for a fast launch or an API integration that keeps buyers on your Drupal Commerce site, the setup follows the same webhook and API key pattern covered above. Store owners running marketplaces can also route payouts and commission splits directly through the mass payouts tools instead of building that logic into a custom module. Head to Cryptopayr to generate your API keys and get your webhook URL configured today.
Most current crypto gateway modules target Drupal 9 or 10 running Commerce 2.x, with PHP 8.1 or higher required. Always check the specific module’s project page for exact version constraints before installing.
Yes. You need an active account with your chosen processor, or a running instance of a self-hosted gateway like BTCPay Server, so you can generate the API keys and webhook secrets the module requires.
Use a tunneling tool like ngrok to expose your local server with a public HTTPS URL, then register that URL as your webhook endpoint in the processor’s sandbox dashboard.
Check the webhook delivery log in your processor dashboard first. Unpaid orders usually trace back to an unreachable webhook URL, a mismatched signature secret, or a reference ID mapping error.
No. Cryptopayr offers no-KYC onboarding with instant approval, letting merchants configure a hosted checkout or API integration without a lengthy verification process.
Open a free CryptoPayr account and take your first crypto payment the same day.
Get started for free
Set up Optimism payments for your store: settle in USDC, use reserved lanes or a relayer fee model, test on testnet, and go live the same day with 0.1% fees.
Finance teams: decide when to use crypto checkout or invoices. Clear rules for consumer sales vs B2B billing, reconciliation tradeoffs, and CryptoPayr...
Accept TRON payments as a merchant: pick wallet, gateway, or hybrid; use plugins or hosted links; set confirmations, webhooks, and treasury rules.