Connect Drupal Commerce

The commerce_payfim module adds an off-site payment gateway plugin. At the payment step the crypto invoice is created on your server from the order total and the customer is redirected to your Payfim Gateway; the gateway's signed webhook creates the Commerce payment automatically.

Before you start, install your Payfim Gateway and add your wallets (see Install the gateway and Add wallets). Compatibility: Drupal Commerce 2.x / 3.x · Drupal 10.1 – 11 · PHP 8.1 – 8.4.

1. Install the module.

   Unzip commerce_payfim.zip into modules/custom/ (web/modules/custom/ on Composer-based sites). Go to Extend, tick Commerce Payfim (Crypto payments) in the Commerce (contrib) group and click Install. Or run drush en commerce_payfim.

2. Add the payment gateway.

   Go to Commerce → Configuration → Payment → Payment gateways (/admin/commerce/config/payment-gateways) and click Add payment gateway. Enter a Name (e.g. Crypto) and choose the plugin Payfim (crypto: Bitcoin, USDT, Ethereum, Litecoin and more).

3. Connect your Payfim Gateway.

   Keep or change the Display name (Pay with Crypto), enter the Gateway URL (e.g. https://pay.yourstore.com) and the API key (Payfim dashboard → Integrations), then click Test connection - it should answer Connected to "Your Store" (Payfim 3.0.0, license valid). Adjust the Description shown under the option at checkout, set Status to Enabled and click Save.

   Tip: The API key field stays empty after saving - leave it empty to keep the saved key. Payment updates arrive at /payment/notify/[gateway machine name]; nothing needs to be configured in the Payfim dashboard.

4. How payments are recorded.

   When the gateway confirms a payment, the module verifies the webhook signature, re-reads the invoice from the gateway, compares amount and currency with the order total and creates one Completed payment (remote ID = Payfim invoice). The order is placed automatically if the customer did not come back to the shop. With the Commerce Log module enabled, the order's activity shows coin, amount and transaction hash. Payments are listed on the order's Payments tab.

5. Underpaid and expired invoices.

   If the customer sends less than requested, an Authorization payment is created - it does not count as paid. On the order's Payments tab use Capture to accept it (you may enter the lower amount) or Void to reject it and refund from your wallet. An expired quote cancels a placed, unpaid order when its workflow has a Cancel transition; draft orders simply stay in checkout.

Troubleshooting

"We encountered an unexpected error processing your payment"

The invoice could not be created. Check Reports → Recent log messages (type commerce_payfim); usually the Gateway URL/API key is wrong or the gateway license is invalid (use Test connection). Enable Debug logging for details.

Order has no payment after paying

The gateway must reach /payment/notify/[gateway machine name] over HTTPS. The Payfim dashboard's Webhooks page shows the HTTP status; failed deliveries are retried for 24 hours. Make sure no access module or firewall blocks that path.

Pay with Crypto not offered at checkout

Check that the gateway is Enabled, its Conditions match the order, and the checkout flow contains the Payment information and Payment process panes.

Get the Drupal Commerce Crypto Payment Gateway - the download includes an illustrated PDF version of this guide.