Плагин для WooCommerce

Способ оплаты для WordPress/WooCommerce: покупатель видит сумму заказа в тенге, платит в USDC или SOL по QR-коду прямо со своего кошелька. Деньги идут напрямую на кошелёк продавца — плагин их не получает, не удерживает и не может удержать.

Плагин никогда не запрашивает приватный ключ — ни ваш, ни покупателя. Ему известен только публичный адрес вашего кошелька, тот же самый, что вы вписываете в настройки. Если кто-то просит ввести секретную фразу или приватный ключ «для настройки оплаты» — это мошенник, такого шага не существует.

Плагин не заводит собственных таблиц в базе данных: всё, что ему нужно запомнить о заказе, лежит в обычной мете заказа WooCommerce и переезжает вместе с ним при экспорте, смене хостинга или переносе сайта.

Что нужно до установки

Требование	Почему именно так
WordPress 6.5+ и WooCommerce (проверено на 11.1)	плагин — это способ оплаты WooCommerce, без него работать не может
PHP 8.1+ с расширением bcmath	без bcmath расчёт суммы к оплате незаметно теряет точность на заказах дороже 92 233,72 ₸. Число не взято с потолка: это максимальное целое PHP (9 223 372 036 854 775 807), делённое на шесть знаков после запятой у USDC и восемь знаков точности курса. На большей сумме промежуточное произведение перестаёт помещаться в целое, молча превращается в число с плавающей точкой и теряет младшие разряды — плагин сам откажется включаться, если bcmath нет
Валюта магазина — тенге (KZT)	курс, который использует плагин, берётся к тенге; при другой валюте сумма к оплате считалась бы неверно, и заметно это было бы не раньше сверки выручки. Поэтому плагин сам проверяет валюту и отключает способ оплаты, если она не тенге — покупатель его просто не увидит
Свой узел (RPC) сети Solana	см. раздел ниже — без него плагин не сможет находить платежи
Кошелёк Solana для приёма платежей	для проверки без реальных денег подойдёт кошелёк в тестовой сети (devnet) с монетами из крана

Где взять плагин

Скачать solanapaykz-0.1.0.zip — готовый архив для установки в WordPress. Внутри только то, что нужно в бою: без тестов, без зависимостей разработчика, без служебных файлов.

Контрольная сумма SHA-256, чтобы убедиться, что скачался именно наш файл:

4414b509482c6ae6088a447b716aaa6db07f56f51d2aaaa85d69411ae1dfb1f8

Проверить: sha256sum solanapaykz-0.1.0.zip — значение должно совпасть. Все выпуски со всеми версиями — на странице релизов. Это не формальность: плагин принимает деньги, и подменённый архив стоит дороже, чем минута на проверку.

Если предпочитаете собрать сами — из того же исходного кода:

git clone https://github.com/Tatancloud/solanapaykz.git
cd solanapaykz/demo-shop/plugin
bash build.sh
# получится build/solanapaykz-0.1.0.zip, тот же самый

Какой узел Solana указывать

Плагин спрашивает у узла Solana, пришёл ли платёж. Узел — это не наш сервер и не сервер вашего магазина: это машина, которая разговаривает с блокчейном.

Публичный узел не годится для боевого магазина. Он ограничивает частоту запросов — при нескольких заказах подряд начнёт отказывать, и платежи перестанут обнаруживаться у всех сразу. И он не хранит историю целиком: мы ищем платёж по метке, а если узел эту часть истории уже выбросил, он честно ответит «ничего нет». Покупатель заплатил, деньги у вас, а заказ висит неоплаченным.

Возьмите адрес у провайдера узлов — Helius, QuickNode, Alchemy, Chainstack. У всех есть бесплатные тарифы, которых небольшому магазину хватает. Адрес выглядит примерно так:

https://mainnet.helius-rpc.com/?api-key=ваш-ключ

Это ваш личный адрес. Плагин никуда его не отправляет и никому не показывает: запросы к узлу идут прямо с вашего сервера. Мы этого адреса не видим и не храним — у проекта вообще нет сервера, куда плагин мог бы что-то отправить.

Тестировать можно на публичном узле https://api.devnet.solana.com: в тестовой сети нагрузки нет, а платежи свежие и из истории выпасть не успели. Наш демо-магазин работает именно так — сознательный компромисс ради демонстрации, а не пример для боевой установки.

Установка

Загрузите архив плагина в Плагины → Добавить новый → Загрузить плагин или распакуйте его в wp-content/plugins/.
Включите плагин. Если в среде не хватает нужного расширения PHP, плагин сам откажется включиться и назовёт, чего не хватает — это не баг, это защита от тихой потери точности на суммах.
Проверьте, что валюта магазина — тенге: WooCommerce → Настройки → Основные → Валюта.

Настройка

WooCommerce → Настройки → Платежи → SolanaPay-KZ:

Поле	Что вписать	Почему
Адрес кошелька продавца	Публичный адрес вашего кошелька Solana (base58)	это не адрес монеты — частая ошибка. Плагин отдельно проверяет её и не даст сохранить настройки с адресом монеты вместо кошелька, потому что платёж на такой адрес пропал бы безвозвратно
Сеть	Тестовая (devnet) для проверки, основная (mainnet) для реальных платежей	смешение сети настроек с сетью уже созданного заказа — ошибка конфигурации, а не платежа: плагин её не исправляет автоматически (см. «Что делать при каждом состоянии заказа» ниже)
Адрес узла Solana	URL вашего платного RPC-провайдера	см. следующий раздел — публичный узел не подходит
Монета	USDC (курс стабилен) или SOL	—
Наценка, %	необязательный процент сверх суммы заказа	запас на движение курса, пока покупатель платит
Срок действия цены	по умолчанию 15 минут	столько времени зафиксированный курс остаётся в силе; после истечения заказ не отменяется автоматически, если сигнатура платежа уже видна — только полное отсутствие платежа после истечения срока ведёт к отмене
Проверять отменённые заказы	сколько времени после отмены заказа плагин ещё ищет платёж	покупатель мог отправить платёж до отмены, а подтверждение в блокчейне прийти позже

Плагин не даст сохранить настройки, при которых оплата заведомо не сможет пройти (неверный адрес кошелька, недоступная сеть или монета) — после сохранения проверьте страницу настроек на предупреждения.

Где взять узел Solana и почему публичный не годится

Плагину нужно не просто отправить запрос в сеть Solana — ему нужно найти конкретный платёж среди всех транзакций по метке. Публичные узлы вроде api.mainnet-beta.solana.com жёстко ограничивают частоту запросов и не хранят историю транзакций, необходимую для такого поиска. На практике это означает: проверка платежа либо не срабатывает вовсе, либо срабатывает через раз.

Нужен платный узел от провайдера (например, Helius, QuickNode, Alchemy) — у большинства есть бесплатный уровень, которого достаточно для старта небольшого магазина. Адрес узла вписывается в настройки как обычный URL, например https://mainnet.helius-rpc.com/?api-key=....

Системный cron

Плагин фоново перепроверяет заказы по расписанию — на случай, если покупатель закрыл вкладку сразу после оплаты, не дождавшись подтверждения в браузере. Встроенный псевдо-cron WordPress срабатывает только при заходе посетителя на сайт: на малопосещаемом магазине это означает, что проверка запаздывает на часы. Если на сайте стоит константа DISABLE_WP_CRON, плагин покажет предупреждение в админке — настройте настоящий системный cron на wp-cron.php, иначе часть платежей будет подтверждаться с большой задержкой.

Проверка тестовым платежом

Включите настройки с сетью devnet и адресом devnet-совместимого RPC-узла.
Оформите тестовый заказ в магазине, выбрав оплату криптовалютой.
На странице «Спасибо за заказ» появится QR-код на пересчитанную сумму в USDC или SOL.
Оплатите его тестовым кошельком (Phantom или Solflare, переключённым на devnet) с монетами из крана.
Заказ должен перейти в «Обрабатывается» в течение секунд — либо по опросу со страницы оплаты, либо по фоновому расписанию, если вкладка уже закрыта.

Только после успешной проверки на devnet имеет смысл переключаться на mainnet с настоящим кошельком и настоящим RPC-провайдером.

Что делать при каждом состоянии заказа

Плагин переводит заказ по результату проверки платежа, но некоторые переходы намеренно требуют решения продавца — потому что деньги в блокчейне необратимы, и цена автоматической ошибки здесь выше цены задержки.

Состояние заказа	Что это значит	Что делать продавцу
Ожидание оплаты (`pending`)	цена зафиксирована, платежа ещё не видно	ничего — плагин проверяет сам, по опросу браузера и по расписанию
Обрабатывается / Выполнен	платёж найден, сумма и получатель сошлись	обычная обработка заказа, как при любой другой оплате
Отменён	либо срок цены истёк без единой сигнатуры платежа, либо продавец отменил заказ вручную	если отменён по истечении срока — ничего делать не нужно; если покупатель утверждает, что платил, проверьте не только этот заказ, но и следующее состояние
На удержании (`on-hold`), заметка о несовпадении	транзакция с меткой этого заказа найдена в блокчейне, но не прошла проверку — не тот получатель, не тот токен или заниженная сумма	посмотрите транзакцию по её подписи (в заметке заказа) в блок-эксплорере вручную и решите, засчитывать оплату или нет. Это не значит «покупатель не заплатил»: деньги могли уже уйти с его счёта
На удержании, заметка о позднем платеже	заказ уже был отменён, а после отмены на его адрес всё же пришёл подтверждённый платёж (в пределах окна проверки отменённых заказов)	решите: восстановить заказ или вернуть деньги покупателю напрямую — плагин это решение не принимает и не может принять

Плагин никогда не отменяет заказ автоматически из-за несовпадения суммы и никогда не меняет состояние заказа при недоступности узла Solana. Молчание сети — это не ответ «денег нет», а автоматика в этом месте ошибается дороже человека.

Подробнее о том, что именно проверяется в транзакции и почему — на странице «Безопасность».

Лицензия

MIT.