Приём криптовалюты в Magento 2

Модуль CryptoLike добавляет криптовалюту в оформление заказа Magento 2 и создаёт счёт (invoice) Magento только после подтверждения платежа в блокчейне. Покупатели платят в Bitcoin, USDT, Ethereum, Litecoin, TRON или USDC, а команда работает с привычными состояниями заказа, включая Accept и Deny для платежей, по которым нужно решение.

#Требования

Модуль CryptoLike_Payment работает на Magento 2.4.6 и новее с PHP от 8.1 до 8.4 и оформлением заказа Luma. Он построен на Magento Payment Gateway и проверен на реальных классах Magento 2.4, по стандарту кода Magento 2 и в живом прогоне на Mage-OS 3.5 — дистрибутиве Magento Open Source. PHP SDK CryptoLike уже внутри модуля: других пакетов и ключа Marketplace не нужно.

#Что умеет модуль

При «Оформить заказ» модуль создаёт платёж CryptoLike и переводит заказ в pending_payment. Дальше заказ двигают подписанные вебхуки: подтверждённый платёж — это processing и счёт Magento (оплата фиксируется офлайн, ID транзакции — ID платежа CryptoLike), а деньги, по которым нужен человек, уходят в payment_review.

• Переадресация или встроенная страница. После оформления покупатель уходит на страницу оплаты CryptoLike или платит на странице статуса заказа.
• Accept / Deny для проверки. Поздний платёж, недоплата после срока и отмена сетью показывают кнопки Magento Accept Payment и Deny Payment.
• Зашифрованные секреты. API-секрет и секрет вебхука хранятся с ключом шифрования Magento и не попадают в config:show и app:config:dump.
• Один платёж на заказ. Двойной клик, перезагрузка или «Создать новый платёж» возвращают тот же открытый платёж.
• Выбор монеты на странице оплаты. Покупатель выбирает монету там; поле Монеты на странице оплаты может сузить список, а «ничего не выбрано» значит все монеты, доступные для инвойсов в вашем аккаунте.
• Задача cron cryptolike_reconcile перечитывает открытые платежи раз в 15 минут.

#1. Установите модуль

Через Composer (рекомендуется): положите Composer-архив с этой страницы в папку на сервере, например /var/www/packages, и выполните в корне Magento:

composer config repositories.cryptolike artifact /var/www/packages
composer require cryptolike/module-payment:1.0.0
bin/magento module:enable CryptoLike_Payment
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

Без Composer распакуйте архив для app/code в корень Magento (появится app/code/CryptoLike/Payment) и выполните те же команды bin/magento. В режиме production также разверните статический контент.

#2. Подключите аккаунт CryptoLike

В кабинете CryptoLike откройте Разработчикам → API-ключи → Создать ключ с правами create_invoice и read и вставьте ID ключа и секрет в Stores → Configuration → Sales → Payment Methods → CryptoLike — crypto payments. Скопируйте там URL вебхука (https://ваш-магазин/cryptolike/webhook/, свой для каждого store view), добавьте его в кабинете в Разработчикам → Вебхуки → Добавить эндпоинт со всеми событиями invoice.* и вставьте секрет эндпоинта в поле Секрет вебхука.

#3. Включите способ оплаты и проверьте

Переключите Enable crypto payments в Yes и нажмите Save Config. Проверить соединение покажет «Соединение установлено: доступно валют — N». До запуска проверьте всё с ключом ck_test_ и тестовым адресом в поле URL API (по умолчанию там рабочий; тестовый URL даст поддержка CryptoLike): тестовые ключи работают с тестовыми сетями, в корзине под способом оплаты видна строка тестового режима, а рабочий ключ в тестовом режиме не сохранится.

#Как меняется статус заказа

Время на оплату — из настроек аккаунта (по умолчанию 30 минут), если не задано другое. Отменённый заказ Magento открыть заново не может, поэтому деньги, пришедшие за него, оставляют заказ canceled с комментарием; сумма лежит на вашем балансе CryptoLike — её можно вернуть или оформить на неё новый заказ.

Эти правила одинаковы на всех платформах; остальные платформы для магазинов сравниваются в разделе криптовалюта для интернет-магазина.

#Скриншоты

#Если что-то не работает

Журнал — var/log/cryptolike.log, в нём нет секретов, подписей, тел вебхуков и данных покупателей.

#Разработчикам

Модуль следует общему контракту плагинов CryptoLike: платёж создаётся с сервера, на заказ — один открытый платёж (idempotency_by_order_id; вне магазина по умолчанию order_id в API — <store_id>-<increment_id>), подпись вебхука проверяется по сырому телу, события отсеиваются по event_id, а ответ 200 уходит только после записи заказа. README для разработчика со структурой модуля — в архиве.

#Вопросы и ответы

#Что будет, если покупатель заплатит меньше суммы заказа?

Заказ переходит в holded с комментарием о недостающей сумме, а покупатель видит, сколько отправить на тот же адрес до срока. Доплата вовремя снимает удержание, и заказ становится processing со счётом. После срока заказ уходит в payment_review, где вы нажимаете Accept или Deny.

#Что если покупатель заплатил после окончания срока?

Если заказ отменился по истечении срока, он остаётся canceled: Magento не открывает отменённые заказы. Комментарий покажет, сколько пришло, а деньги будут на вашем балансе. Чтобы заказы оставались открытыми, выберите «Оставить заказ в ожидании оплаты» — тогда поздний платёж попадёт в payment_review с Accept и Deny.

#Как вернуть деньги покупателю?

Возврат делается вручную, потому что перевод в блокчейне нельзя отозвать. Нажмите Deny у платежа на проверке или отмените заказ, затем отправьте возврат выплатой из кабинета CryptoLike на адрес покупателя. Расчёт покажет комиссию платформы и комиссию сети; тарифы — на странице тарифов.

#В какой валюте магазина можно принимать оплату?

Платёж создаётся в валюте заказа (USD, EUR, UAH, GBP или CAD), а CryptoLike пересчитывает её в монету по курсу, зафиксированному до конца срока оплаты. Валюта должна быть включена для платежей в аккаунте. В мультисайте у каждого сайта (website) могут быть свой аккаунт CryptoLike и свои валюты.

#Можно ли проверить модуль без реальных денег?

Да. Включите тестовый режим, сохраните ключ ck_test_ и тестовый URL API, который даст поддержка CryptoLike. Тестовые ключи работают с тестовыми сетями, а тестовые монеты ничего не стоят. В настройках виден значок «Тестовый режим», в корзине — строка тестового режима. Рабочий ключ в тестовом режиме и тестовый в рабочем не сохраняются.

#Работает ли модуль с Adobe Commerce?

Это стандартный платёжный модуль Magento 2, проверенный на Magento Open Source 2.4 (дистрибутив Mage-OS). У Adobe Commerce те же механизмы оформления заказа и оплаты, но там модуль ещё не проверялся — сначала запустите его на копии магазина в тестовом режиме.