Magento 2 Crypto Payment Extension

Written for the people who maintain Magento stores

If you run Magento stores for clients, you judge a payment extension by what it does to the codebase, the order pipeline and your support queue - not by its marketing. So here is the short version for developers and agencies:

• A standard module, Payfim_CryptoPayment, installed in app/code or through Composer as payfim/module-crypto-payment (an artifact package is included).
• Built on Magento's payment gateway facade (Magento\Payment\Model\Method\Adapter) rather than the older AbstractMethod base class.
• The checkout renderer extends Magento's own Magento_Checkout/js/view/payment/default component.
• Plain PHP 7.4-compatible code, so it runs on any PHP version your Magento 2.4.x release supports.
• Uninstall removes only the payment/payfim/* configuration and never touches orders.

The source is readable and unencrypted, so it can go through your usual code review before it reaches a client project.

Payments are processed by the merchant's own Payfim Gateway and land in the merchant's own wallets. There is no processor account to set up for the client and no per-order fee.

How the order lifecycle works

1. After Place Order, the payment method's initialize command sets the order to Pending Payment and holds back the new-order email.
2. The customer is redirected to payfim/checkout/redirect, which creates the crypto invoice server-side from grand_total and the order currency, then sends them to the Payfim checkout.
3. When the payment is confirmed, the gateway posts a signed webhook to /payfim/webhook/index/. The controller verifies the HMAC-SHA256 signature (five-minute window), takes a per-order lock, reloads the order and re-reads the invoice from the gateway.
4. For a paid invoice it calls registerCaptureNotification(): Magento creates a paid invoice and a capture transaction whose ID is the blockchain transaction hash, and the order moves to Processing.
5. The order confirmation and invoice emails go out once, at this point - customers are not told "order received" for an order that was never paid.

Duplicate deliveries are harmless: the per-order lock serializes them, the extension tracks what it already applied, and Magento's unique transaction ID would reject a second capture anyway.

Underpayments, expiry and abandoned checkouts

The When a Customer Underpays setting gives the merchant three choices, and none of them invoices the order automatically:

• Set order to Payment Review (default). The order view offers Accept Payment and Deny Payment. Accepting moves the order to Processing without an invoice; the merchant then creates one with Capture Offline, because Magento cannot know the fiat value of a short payment. Denying cancels the order, and any refund is sent from the merchant's wallet.
• Put order On Hold. If the customer later pays the full amount, the order is released and captured.
• Keep Pending Payment and add a comment only.

An expired crypto quote cancels the Pending Payment order. If the customer clicks cancel on the checkout, their cart is restored while the order stays pending, so a payment that still arrives is recorded. Keep Magento's Pending Payment Order Lifetime (minutes) under Stores → Configuration → Sales → Sales → Orders Cron Settings longer than your Payfim quote lifetime, which is 30 minutes by default.

Configuration, security and logging

Settings live in Stores → Settings → Configuration → Sales → Payment Methods under Other Payment Methods, and follow Magento's configuration scopes, so values can differ per website.

• The API key is stored with Magento's encrypted backend model, shown as ****** after saving and marked as a sensitive setting.
• A Test connection button checks the gateway (and license) using the unsaved values, or the saved key if the field is masked. The admin controller is form-key protected and behind the Magento_Payment::payment ACL.
• The webhook controller implements Magento's CSRF-aware interface for POST requests from the gateway. Make sure a full-page cache or WAF does not block POSTs to /payfim/webhook/index/.
• Country restrictions, minimum and maximum order totals and sort order are available as usual.
• Debug Logging writes to var/log/payfim.log. The API key is never logged.

The order view's payment block shows the Payfim invoice, status, coin, amount received and transaction hash, so store staff can answer "has this order been paid?" without logging in to the gateway. Every webhook is signed with HMAC-SHA256 and re-checked with the gateway before the order changes; the security page describes the model in more detail.

Deployment notes for agencies

The Payfim Gateway is a separate PHP application, not part of the Magento codebase. That separation is useful on client projects:

• Host it outside the Magento cluster. The gateway runs on ordinary hosting with PHP 7.4 - 8.4, MySQL or MariaDB, cURL and HTTPS, so it can live on a small separate server or even shared hosting under pay.clientstore.com. Magento deploys and cache flushes never affect it.
• The merchant owns the wallets. Set up receiving addresses in the merchant's own wallets. Payfim never needs private keys or seed phrases, so your agency never handles them either.
• Cron every minute on the gateway server keeps confirmation times short.
• Licensing. The license is a one-time purchase per domain with 12 months of updates; renewing updates costs $9 per year per module. A white-label add-on removes "Powered by Payfim" from the checkout, and we offer an installation service if you would rather not deploy the gateway yourself. See pricing.

Requirements

How to install the Magento 2 crypto payment extension

1. Install the Payfim gateway. Deploy the gateway on the merchant's hosting (for example pay.yourstore.com) and add the merchant's wallet addresses - see installing the Payfim gateway.
2. Add the module. Unzip Payfim_CryptoPayment.zip in the Magento root to create app/code/Payfim/CryptoPayment/, or add the included artifact and run composer require payfim/module-crypto-payment.
3. Enable it. Run bin/magento module:enable Payfim_CryptoPayment, bin/magento setup:upgrade and bin/magento cache:flush. In production mode also run setup:di:compile and setup:static-content:deploy -f.
4. Connect. Open Stores → Settings → Configuration → Sales → Payment Methods, expand Payfim - Crypto Payments, set Enabled to Yes, enter the Gateway URL and API key, click Test connection and Save Config.
5. Test. Place a small order with Pay with Crypto, pay it, and check that it reaches Processing with an invoice in Sales → Operations → Orders. Full notes in the Magento 2 docs.