Криптоплатежи в WooCommerce: как подключить USDC через API и webhooks

Криптоплатежи в WooCommerce лучше проектировать как полноценный платёжный gateway, а не как ссылку на внешний кошелёк. Магазину нужно связать конкретный заказ с конкретным платежом, получить подтверждение от провайдера и только после этого изменить статус заказа.

Главный принцип — не доверять одному redirect из браузера. Пользователь может закрыть вкладку, сеть может оборваться, а клиентский запрос нельзя считать доказательством оплаты. Надёжный source of truth — серверный API и проверенный webhook платёжного сервиса.

Ниже — практическая схема интеграции stablecoin-платежей, включая USDC, с WooCommerce. В качестве актуального примера используются Coinbase Business Checkout APIs и Payment Acceptance API, но архитектура применима и к другим провайдерам с серверным API и webhooks.

Что нужно связать между WooCommerce и платёжным сервисом

WooCommerce уже хранит заказ, сумму, валюту, товары и статус. Платёжный сервис создаёт собственную сущность checkout или payment и возвращает внешний идентификатор. Интеграция должна сохранить связь между этими двумя сущностями.

В официальной документации WooCommerce REST API заказы и webhooks рассматриваются как отдельные API-ресурсы. Для проекта полезно опираться на Orders API и Webhooks API.

Почему redirect после оплаты недостаточен

Redirect нужен для пользовательского сценария: вернуть покупателя в магазин, показать страницу ожидания или открыть заказ в личном кабинете. Но он не должен единолично менять статус заказа на оплаченный.

Правильнее дождаться серверного подтверждения. Coinbase Business Checkout APIs, например, предусматривают webhook-события для результата оплаты и возврат пользователя после checkout. Актуальный обзор опубликован в официальной документации Coinbase Business Checkout APIs.

Рабочая последовательность платежа

1. Покупатель оформляет заказ в WooCommerce.
2. Gateway на сервере создаёт checkout или payment у провайдера.
3. В metadata заказа сохраняются provider, внешний payment id и стабильный технический ключ операции.
4. Покупатель переходит в checkout провайдера.
5. Провайдер отправляет webhook на HTTPS endpoint магазина или отдельного backend.
6. Endpoint проверяет предусмотренный провайдером механизм подлинности.
7. Интеграция сверяет payment id, сумму, валюту и состояние платежа.
8. Только после подтверждённого события WooCommerce меняет статус заказа.
9. Event id сохраняется, чтобы повтор webhook не выполнил действие второй раз.

Какие статусы WooCommerce использовать

WooCommerce поддерживает стандартные статусы заказов, включая pending, on-hold, processing, completed, cancelled, refunded и failed. Конкретная схема зависит от типа товара и процесса исполнения заказа.

Для физического товара подтверждённая оплата обычно означает начало обработки, а не автоматическое завершение: заказ ещё нужно собрать и отправить. Для цифрового продукта логика может быть другой.

Важно разделять «checkout создан», «платёж ожидается» и «платёж подтверждён». Создание внешнего checkout само по себе не означает, что магазин получил деньги.

Idempotency защищает от двойной обработки webhook

Webhook может прийти повторно. Это нормальная часть устойчивых интеграций: провайдер повторяет доставку, если не уверен, что endpoint получил событие.

Поэтому обработчик должен быть idempotent. Для каждого события сохраняют стабильный event id либо комбинацию provider + payment id + event type. Перед изменением заказа код проверяет, не было ли событие уже обработано.

Это защищает от повторной смены статуса, двойной отправки писем, повторной выдачи цифрового товара и других необратимых действий.

Что проверять в webhook до изменения заказа

• подлинность запроса по правилам конкретного провайдера;
• наличие известного payment или checkout id;
• связь внешнего id с конкретным order_id;
• ожидаемую сумму;
• валюту или актив;
• финальный либо промежуточный статус;
• event id на повтор;
• текущее состояние WooCommerce-заказа.

Нельзя принимать order_id, сумму или флаг success из публичного JavaScript как единственное доказательство оплаты.

Coinbase Commerce и Coinbase Business: на что смотреть в 2026 году

Для новой интеграции важно не брать старую архитектуру Coinbase Commerce из устаревшего туториала. Coinbase опубликовала отдельное руководство по переходу в Coinbase Business с изменениями endpoints, авторизации и webhook-событий. Официальный источник: Migrate from Commerce.

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

Payment Acceptance API и USDC

Coinbase отдельно документирует Payment Acceptance API для stablecoin-платежей. В API предусмотрены операции платежей, webhooks и возвраты; актуальная структура описана в Payment Acceptance API.

Для WooCommerce это удобно моделировать как обычный gateway: серверный вызов API, внешний ID в metadata заказа, webhook endpoint, отображение статуса в админке и административные операции, которые реально поддерживает выбранный провайдер.

Где хранить API-ключи

Секретные credentials нельзя передавать в JavaScript checkout-страницы, вставлять в HTML или писать в открытые логи. Они должны оставаться на серверной стороне.

Если провайдер использует JWT или короткоживущий Bearer token, он формируется на backend. Браузер получает только данные, необходимые для пользовательского интерфейса.

Почему платёжную интеграцию лучше делать отдельным плагином

Критичную платёжную логику не стоит помещать в functions.php темы. Смена дизайна не должна ломать платежи.

Отдельный WooCommerce-плагин позволяет собрать в одном месте настройки провайдера, создание checkout, metadata заказа, webhook endpoint, idempotency, безопасное журналирование и административные действия.

• настройки и credentials;
• создание payment/checkout;
• сопоставление order_id и внешнего id;
• обработка webhook;
• проверка повторов;
• логирование без секретов;
• возврат или отмена, если API это поддерживает;
• совместимость с текущей архитектурой WooCommerce.

Для нестандартного API такой модуль можно реализовать как отдельную задачу в рамках разработки плагинов WordPress.

Возвраты нельзя считать автоматическими

Refund в WooCommerce и фактический возврат средств у криптопровайдера — не всегда одна операция. Нужно отдельно проверить API выбранного сервиса: поддерживаемые активы, комиссии, ограничения и состояние settlement.

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

Что логировать для диагностики

• WooCommerce order_id;
• provider;
• external payment id;
• тип webhook event;
• event id;
• HTTP-код API;
• время обработки;
• старый и новый статус заказа;
• короткое описание ошибки.

Полный Authorization header, API secret и лишние персональные данные в таких логах не нужны.

Что проверить до production

1. Успешную оплату.
2. Отмену пользователем.
3. Истёкший checkout.
4. Повтор одного webhook.
5. Webhook до возврата пользователя на сайт.
6. Возврат пользователя без финального webhook.
7. Несовпадение суммы.
8. Неизвестный payment id.
9. Временную ошибку API.
10. Повтор после timeout.
11. Refund, если он предусмотрен.
12. Работу интеграции после обновления темы.

Когда нужен отдельный backend

Для одного магазина и одного провайдера часто достаточно отдельного WooCommerce-плагина. Если несколько сайтов используют общий платёжный контур, нужны очереди, централизованные логи, CRM и дополнительные автоматизации, интеграционный слой можно вынести в отдельный backend.

Такой вариант пересекается с автоматизацией бизнес-процессов: WordPress остаётся источником заказа, а отдельный сервис управляет обменом между внешними системами.

Что прислать для оценки интеграции

Для технической оценки достаточно ссылки на магазин, страны регистрации бизнеса, выбранного платёжного провайдера, нужных stablecoins или криптовалют, текущего checkout и правил перехода статусов заказа.

Если провайдер уже выбран, полезна ссылка на его официальную API/webhook документацию. Если ещё нет, сначала стоит проверить доступность сервиса для нужной юрисдикции, затем проектировать интеграцию.

A.S Groups может подключить платёжный API к существующему WooCommerce, разработать отдельный gateway/plugin и настроить серверную обработку webhooks. Подробнее — на странице WooCommerce-разработки; отправить задачу можно через контакты.

FAQ

Можно ли подтвердить оплату только по redirect URL?

Для интерфейса redirect полезен, но статус заказа надёжнее менять после серверного подтверждения API или webhook.

Что делать, если webhook пришёл дважды?

Использовать idempotent-обработчик: повтор уже известного event id не должен второй раз выполнять бизнес-действие.

Можно ли хранить API key в JavaScript?

Нет. Секретные credentials должны оставаться на серверной стороне.

Нужно ли ставить completed сразу после оплаты?

Не обязательно. Для физического товара подтверждённая оплата обычно означает переход к обработке; завершение зависит от fulfillment-процесса.

Подойдёт ли старая интеграция Coinbase Commerce?

Для новой разработки нужно сверяться с актуальными Coinbase Business и Payment Acceptance API и официальной migration documentation.