Что вам нужно
| Поле | Что оно делает |
|---|---|
| Access token | Позволяет нам вызвать Square, чтобы создать ссылку на оформление. Секретный. |
| Webhook signature key | Подтверждает, что вебхук действительно пришёл от Square. Секретный. |
| Location ID | Локация Square, которая получает платёж. Задаёт валюту. |
| URL успеха / URL отмены | Куда попадает покупатель после оплаты или отказа. |
Почему мы спрашиваем каждое поле
Access token
Авторизует создание ссылки на оформление, чтобы списание прошло через ваш счёт.
Webhook signature key
Доказывает, что входящий вебхук подлинно от Square, так что никто не подделает событие «оплачено». Это отдельное значение от access token.
Location ID
Говорит Square, какая локация получает деньги, и задаёт валюту оформления. Не секретный.
URL успеха и отмены
Простые настройки: куда попадает покупатель после оплаты или отказа. Не секретные.
Настройка
- Откройте панель разработчика Square
Войдите на developer.squareup.com. У каждого приложения собственные учётные данные, а рядом с ним автоматически создаётся бесплатная песочница для тестирования. Это руководство описывает работу в песочнице; процесс для Live идентичен — просто переключите тумблер Sandbox / Production и используйте боевые учётные данные. Чтобы создать новое приложение, нажмите плитку «+» на экране Applications.
Square Developer → Applications - Назовите ваше приложение
Дайте приложению имя, которое вы узнаете (например, «Coin Moebius»), затем нажмите «Next».
Square → Name your application - Скопируйте access token
Откройте приложение и перейдите в Credentials. Убедитесь, что тумблер Sandbox / Production вверху соответствует настраиваемому окружению. Нажмите значок копирования рядом с Access token и сохраните его.
Square → Credentials Access token секретный, обращайтесь с ним как с паролем. У Sandbox и Production отдельные токены, не смешивайте их.
- Скопируйте Location ID
В левом меню откройте Locations. Скопируйте Location ID локации, которая должна получать платежи. Он задаёт валюту оформления, поэтому выберите ту, в валюте которой хотите принимать оплату.
Square → Locations - Откройте Webhooks → Subscriptions
Square называет вебхук-эндпоинт «подпиской» (subscription). В левом меню раскройте Webhooks, откройте Subscriptions и нажмите «Add subscription».
Square → Webhooks → Subscriptions → Add subscription - Добавьте подписку и выберите события
Дайте ей имя (например, «coin-moebius»). В поле Notification URL вставьте адрес вебхука Square для вашего проекта (ниже). Затем в разделе Events найдите и отметьте события, которые прослушивает Coin Moebius, и нажмите «Save».
- Разовые платежи: payment.created, payment.updated, refund.created, refund.updated, dispute.created, dispute.state.updated.
- Подписки (только если вы их продаёте): subscription.created, subscription.updated, subscription.canceled, subscription.deactivated, invoice.payment_made, invoice.scheduled_charge_failed. Если вы не выставляете счёт на регулярной основе, пропустите их.
https://api.coinmoebius.com/webhook/square/<your project id>Square → Add a webhook subscription Id вашего проекта находится под его названием в панели Coin Moebius; подставьте его в адрес выше. Лишние события безвредны, мы игнорируем всё, что не используем. Карточка подключённого провайдера (последний шаг) показывает тот же URL для справки.
- Откройте только что созданную подписку
Square сохраняет подписку и отображает её в разделе Webhooks со статусом Enabled. Нажмите на её имя, чтобы открыть панель сведений, где находится ключ подписи.
Square → Webhooks → ваша подписка (Enabled) - Скопируйте Signature key
В панели Properties подписки нажмите значок копирования рядом с Signature key. Это значение Coin Moebius использует, чтобы подтверждать, что каждый вебхук действительно пришёл от Square. Он существует только после создания подписки, поэтому вебхук настраивается раньше подключения.
Square → ваша подписка → Signature key - Обратно в Coin Moebius: Добавить провайдера → Square
В вашем проекте откройте вкладку «Провайдеры», нажмите «Добавить провайдера», выберите «Подключить сервис» и выберите Square. Укажите URL успеха и URL отмены. На вкладке Live вставьте Access token, Webhook signature key и Location ID, затем нажмите «Сохранить». Сначала настраиваете с учётными данными песочницы? Вставьте их на вкладке Test, а боевые учётные данные добавьте позже через «Редактировать».
Coin Moebius → Добавить провайдера → Square - Вы подключены
Square теперь отображается на вкладке «Провайдеры» с датой подключения. Карточка показывает тот же URL вебхука, который вы вставили в Square, а также кнопки «Редактировать» и «Отключить». Используйте переключатель «Тестовый режим», чтобы провести заказ из песочницы от начала до конца перед выходом в боевую среду.
Coin Moebius → Провайдеры → Square (подключено) Карты песочницы никогда не списывают с реальной карты. Используйте карту 4111 1111 1111 1111, CVV 111, любую будущую дату окончания, любой действительный почтовый индекс (например, 94103).
После подключения
Сделайте один тестовый платёж до запуска:
- Создайте товар и задайте его Environment как Testing. Это запускает товар на учётных данных песочницы, так что вы можете оформить полный заказ без движения денег. (Если вы пропустили набор песочницы, товар Testing откатывается к боевой среде, так что сначала добавьте его.)
- Поставьте кнопку покупки на страницу (подойдёт локальный HTML-файл), направленную на ваш проект.
- Завершите оформление тестовой картой песочницы из списка выше.
- Откройте вкладку «Транзакции». Появляется новая строка с меткой Testing. Когда её статус достигнет succeeded, ваши учётные данные и вебхук оба работают от начала до конца.
Переключите Environment товара на Live, когда будете готовы к реальным платежам.
Решение проблем
Начните с «Проверить». В панели нажмите «Проверить» (или «Проверить тестовые учётные данные»), чтобы проверить ваш access token и локацию.
«Проверить» не проходит.
Перекопируйте access token и Location ID. У Production и Sandbox отдельные токены, так что не смешивайте их.
Проверка подписи не проходит, или заказ остаётся в ожидании.
Square подписывает по точному URL уведомлений плюс телу. URL, который вы регистрируете в Square, должен совпадать с вашим URL вебхука символ в символ, без завершающего слеша и без лишней строки запроса. Затем перекопируйте signature key с того же эндпоинта.
Подтвердите всё от начала до конца.
Square Developer Console → Webhooks → ваша подписка → Send Test Event, затем смотрите, как обновляется заказ.
Полезно знать
Валюта следует за локацией. Оформление списывает в валюте локации, id которой вы указываете.
Ротация секретов. Меняйте access token или signature key когда угодно, затем вставьте новое значение. Секретные поля остаются пустыми при редактировании.
Вопросы? Join our Discord