VibeFox Pin Payments for WooCommerce — Помощь

Требования

WordPress: 6.2 или новее.

WooCommerce: 7.1 или новее, установлен и активен. Плагин не активируется без него.

PHP: 8.0 или новее.

HTTPS: страница оформления заказа должна использовать HTTPS, как того требует приём платежей картами (PCI DSS). Данные карты отправляются из браузера покупателя напрямую в Pin Payments через Pin.js и никогда не попадают на ваш сервер, поэтому магазин подпадает под PCI SAQ A-EP.

Учётная запись Pin Payments: учётная запись мерчанта Pin Payments (для компаний из Австралии или Новой Зеландии; покупатели могут платить из любой страны). Нужны её публичный (publishable) и секретный (secret) ключи — боевые, а для тестов — ключи тестовой среды. Секрет вебхука не нужен: плагин не использует вебхуки.

Лицензионный ключ VibeFox: покупается на vibefox.net. Один ключ работает на одном домене.

Установка

1. В WordPress перейдите в Plugins > Add New > Upload Plugin, выберите ZIP-файл плагина и нажмите Install Now. Также можно загрузить папку wcp_pinpayments_gateway в /wp-content/plugins/ по FTP.

2. Нажмите Activate.

3. Откройте настройки: WooCommerce > Settings > Payments > Pin Payments > Manage или нажмите Settings под названием плагина на странице «Плагины».

4. Введите лицензионный ключ VibeFox в блоке лицензии вверху страницы и нажмите Activate.

5. В панели Pin Payments откройте Account > API Keys и скопируйте тестовые ключи в Test publishable key и Test secret key. Оставьте Test mode включённым, включите Enable/Disable и сохраните.

6. Оформите тестовый заказ тестовой картой Pin Payments. Когда всё работает, введите боевые ключи, выключите Test mode и сохраните.

Настройка

Все параметры находятся на одной странице: WooCommerce > Settings > Payments > Pin Payments. Над полями страница показывает уведомление, пока включён тестовый режим, ошибку, пока публичный или секретный ключ текущего режима пуст, и ошибку, если Pin Payments не поддерживает валюту магазина (со списком поддерживаемых валют). В последних двух случаях способ оплаты скрыт на странице оформления заказа. После сохранения уведомления уже показывают новый режим и ключи. В списке способов оплаты шлюз помечен как требующий настройки, пока в текущем режиме не заполнены оба ключа.

Enable/Disable: Enable Pin Payments включает или выключает способ оплаты. По умолчанию: выключено.

Title: название способа оплаты, которое показывается на оформлении заказа. По умолчанию: Credit card (Pin Payments).

Description: описание способа оплаты, которое показывается на оформлении заказа. По умолчанию: Pay with your credit card via Pin Payments.

API-ключи

Ключи находятся в панели Pin Payments в разделе Account > API Keys. Тестовые ключи работают только с тестовым API, боевые — только с боевым API. Публичный ключ использует Pin.js в браузере покупателя. Секретный ключ никогда не покидает ваш сервер.

Test mode: Enable test mode. Использует тестовую среду Pin Payments (test-api.pinpayments.com) и тестовые ключи. Реальные списания не производятся, а покупатели видят в форме карты сообщение ТЕСТОВЫЙ РЕЖИМ — реальные списания не будут производиться. Когда режим выключен, используются боевой API (api.pinpayments.com) и боевые ключи. По умолчанию: включено.

Test publishable key: публичный ключ вашей тестовой учётной записи Pin Payments.

Test secret key: секретный ключ вашей тестовой учётной записи Pin Payments. Это поле пароля.

Live publishable key: публичный ключ вашей боевой учётной записи Pin Payments.

Live secret key: секретный ключ вашей боевой учётной записи Pin Payments. Это поле пароля.

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

Дополнительно

Debug log: Log Pin Payments API calls — записи сохраняются в WooCommerce > Status > Logs, источник wcp_pinpayments_gateway. Ошибки записываются всегда; включите эту опцию, чтобы записывать и каждый вызов API. Данные карт, API-ключи и персональные данные покупателей никогда не записываются. По умолчанию: выключено.

Delete data on uninstall: Delete the gateway settings and logs when the plugin is deleted. Деактивация плагина ничего не удаляет. Платёжные данные, сохранённые в заказах, всегда сохраняются. По умолчанию: выключено.

Оформление заказа

Покупатель выбирает способ оплаты (по умолчанию Credit card (Pin Payments) с иконками Visa, Mastercard и American Express) и заполняет на вашей странице оформления заказа поля Card number, Expiry (MM / YY), CVC и Name on card. Перед отправкой форма карты проверяет длину номера карты, месяц и год срока действия, CVC из 3 или 4 цифр и имя.

При оформлении заказа Pin.js отправляет данные карты и адрес выставления счёта из браузера напрямую в Pin Payments и получает одноразовый токен карты. На ваш сервер отправляется только этот токен. Затем сервер создаёт подтверждённое списание на сумму заказа в валюте заказа с описанием <store name> - Order <number>. Pin Payments отвечает в том же запросе. Заказ отмечается оплаченным только после того, как Pin Payments сообщает об успешном списании, и только на точно совпадающие сумму и валюту заказа. Затем покупатель попадает на страницу «Заказ получен».

Для каждого заказа одновременно выполняется только одна попытка оплаты. Повторная отправка получит Этот заказ уже оплачивается. Подождите немного и проверьте электронную почту, прежде чем пробовать снова. Заказ, который уже оплачен, или списан и удерживается, никогда не списывается повторно. Токен карты можно использовать один раз: после неудачной попытки или когда покупатель меняет данные карты, создаётся новый токен.

Сообщения, которые может увидеть покупатель: Ваша карта отклонена. Используйте другую карту или свяжитесь с банком.; На вашей карте недостаточно средств. Используйте другую карту.; Срок действия вашей карты истёк. Используйте другую карту.; Код безопасности карты (CVC) неверен.; Этот тип карты не принимается. Используйте Visa, Mastercard или American Express.; Оплата не прошла: с причиной от Pin Payments для отклонённых данных; Срок действия данных вашей карты истёк. Введите их заново и повторите попытку., когда токен нельзя использовать; Защищённую форму карты не удалось загрузить. Перезагрузите страницу или выберите другой способ оплаты., когда Pin.js не загружается; Оплата картами временно недоступна. Повторите попытку позже или выберите другой способ оплаты., когда Pin Payments отклоняет секретный ключ; Нам не удалось подтвердить вашу оплату в Pin Payments. Перед повторной попыткой проверьте электронную почту и выписку по карте или свяжитесь с нами., когда Pin Payments не отвечает. Технические подробности записываются в примечания к заказу и в журнал.

Способ оплаты работает на классическом оформлении заказа, в блоке «Оформление заказа» (с теми же полями карты) и на странице Pay for order. Он совместим с High-Performance Order Storage (HPOS) в WooCommerce.

В плагине нет процедуры 3-D Secure. Если ваша учётная запись Pin Payments требует 3-D Secure, списание остаётся в ожидании, и плагин переводит заказ в статус «Неудачный», поэтому деньги при этой попытке не списываются; покупатель видит Оплата вашей картой не может быть завершена (требуется дополнительная проверка). Попробуйте другую карту или другой способ оплаты. Нет режима только авторизации с последующим списанием, сохранённых карт, WooCommerce Subscriptions, Apple Pay или Google Pay и вебхуков.

Заказы и возвраты

Order statuses

Processing: Pin Payments сообщил об успешном подтверждённом списании точно на сумму и в валюте заказа. Заказы только с виртуальными загружаемыми товарами переходят в статус «Выполнен», как принято в WooCommerce по умолчанию. В примечании к заказу указаны сумма и токен списания (и TEST MODE для тестовых платежей). ID транзакции — это токен списания Pin Payments.

Failed: карта отклонена, списание осталось в ожидании (3-D Secure), Pin Payments отклонил секретный ключ или запрос. Каждая неудачная попытка добавляет примечание к заказу с кодом ошибки и сообщением Pin Payments, в том числе если заказ уже был в статусе «Неудачный» после предыдущей попытки. Покупатель может повторить попытку с тем же заказом.

Pending payment: Pin Payments не дал чёткого ответа (таймаут, ошибка сервера, нечитаемый ответ). Заказ не помечается как неудачный, потому что списание могло быть создано. Примечание просит найти описание списания в панели Pin Payments до того, как покупатель заплатит снова или заказ будет отправлен. Этот статус — «Ожидает оплаты».

On hold: Pin Payments списал сумму или валюту, отличные от заказа (в примечании указаны ожидаемая и списанная суммы), либо списание авторизовано, но не подтверждено. Проверьте списание в панели Pin Payments перед выполнением заказа.

Возвраты

Откройте заказ, нажмите Refund, введите сумму и нажмите Refund via Credit card (Pin Payments) (на кнопке отображается ваш Title). Поддерживаются полные и частичные возвраты. Возврат отправляется в тот режим (тестовый или боевой), в котором был оплачен заказ, поэтому секретный ключ этого режима должен быть заполнен. Успешный запрос добавляет примечание к заказу с суммой, токеном возврата Pin Payments и его статусом. Pin Payments обрабатывает возвраты асинхронно, поэтому статус обычно Pending. Если Pin Payments отклоняет возврат или не отвечает, WooCommerce показывает ошибку, и возврат не регистрируется.

Возвраты, сделанные в панели Pin Payments, не синхронизируются с WooCommerce, поэтому оформляйте их из WooCommerce.

Лицензионный ключ

Плагин работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии находится вверху страницы WooCommerce > Settings > Payments > Pin Payments. Вставьте ключ в поле License key и нажмите Activate. В блоке показывается статус, например дата, до которой действует лицензия, и ваш домен. Check now повторно проверяет статус, Change key позволяет ввести другой ключ, а Remove key удаляет его с этого сайта. Ссылка Manage licenses and domains in your account открывает ваш аккаунт на vibefox.net.

Один ключ работает на одном домене. Удаление ключа с сайта не освобождает занятый им слот домена. Освободите слот в своём аккаунте на vibefox.net.

Без активного ключа Pin Payments не показывается покупателям на оформлении заказа. Если оплата всё же начата, покупатель видит Этот способ оплаты недоступен. Выберите другой. Авторизованные менеджеры магазина по-прежнему видят способ оплаты, помеченный как (без лицензии — видно только администраторам), чтобы вы могли настроить и протестировать плагин до покупки ключа. Напоминание появляется на странице «Плагины» и на страницах WooCommerce. Существующие заказы не затрагиваются: возвраты продолжают работать.

Когда лицензия истекает, плагин продолжает работать, но для обновлений и поддержки нужно продление. Статус автоматически проверяется в фоновом режиме.

Устранение неполадок

Pin Payments не появляется на оформлении заказа: проверьте, что лицензия активна, Enable/Disable включён, заполнены оба ключа текущего режима (Test publishable key и Test secret key в тестовом режиме, боевые ключи в остальных случаях) и валюта корзины входит в 14 поддерживаемых. На странице Pay for order учитывается валюта заказа. На странице настроек отображается ошибка при отсутствии ключей и при неподдерживаемой валюте.

На оформлении заказа написано «Нам не удалось подтвердить вашу оплату»: Pin Payments не ответил вовремя. Заказ остаётся в статусе «Ожидает оплаты» с примечанием. Найдите в панели Pin Payments списание с описанием <store name> - Order <number>, прежде чем покупатель заплатит снова или заказ будет отправлен. Плагин сам такое списание не ищет, а новая попытка создаёт новое списание.

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

Заказы не проходят с сообщением «требуется дополнительная проверка»: ваша учётная запись Pin Payments требует 3-D Secure, который плагин не поддерживает. Попросите Pin Payments отключить обязательный 3-D Secure.

Заказ в статусе «На удержании» с примечанием «does not match»: Pin Payments сообщил о сумме или валюте списания, отличных от заказа. Проверьте списание в панели Pin Payments и вручную сделайте возврат или завершите заказ.

Защищённую форму карты не удалось загрузить: Pin.js с CDN Pin Payments не загрузился в браузере, например из-за блокировщика скриптов или плагина кэширования или оптимизации, который меняет скрипты. Исключите страницу оформления заказа из таких оптимизаций.

Возврат не проходит: прочитайте сообщение. Сообщение о режиме TEST или LIVE означает, что секретный ключ режима, в котором оплачен заказ, пуст. Pin Payments не подтвердил возврат означает, что ответа не было; проверьте списание в панели Pin Payments, прежде чем повторять попытку.

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

Тестовые платежи: тестовый режим использует тестовую среду и тестовые ключи. Используйте тестовые карты из документации разработчика Pin Payments, например 4200 0000 0000 0000 (успешно) или 4100 0000 0000 0001 (отклонено), с любым будущим сроком действия и любым CVC. Заказы сохраняют режим, в котором были оплачены, поэтому возвраты уходят в нужную среду после переключения режима.

Где искать ошибки: ошибки всегда записываются в WooCommerce > Status > Logs, источник wcp_pinpayments_gateway. Включите Debug log, чтобы видеть каждый вызов API.

Блок лицензии показывает ошибку: следуйте сообщению в блоке. Например, если ключ уже используется на другом домене, освободите слот в аккаунте vibefox.net и нажмите Check now. Если адрес сайта изменился, нажмите Check now, чтобы активировать ключ для нового домена. Если сервер лицензий недоступен, плагин продолжит работать по последнему известному статусу.

Для разработчиков: фильтр wc_ppg_supported_currencies меняет список валют, а wc_ppg_icon меняет значок в списке способов оплаты WooCommerce.

Удаление

Деактивация плагина сохраняет все данные. Чтобы удалить его, деактивируйте и удалите плагин на странице Plugins. Лицензионный ключ и статус лицензии этого плагина удаляются всегда. Настройки шлюза, версионные опции плагина и его журналы (файлы журналов, включая ротированные, и записи журнала в базе данных) удаляются только если была включена опция Delete data on uninstall. Иначе они сохраняются для повторной установки. Платёжные данные, сохранённые в заказах, например токен списания Pin Payments, никогда не удаляются. Существующие заказы сохраняют свои платёжные примечания и ID транзакций.

Pin Payments — торговая марка её правообладателя. Этот плагин не связан с Pin Payments и не одобрен компанией Pin Payments.