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

Требования

PrestaShop: от 8.0 до 9.x.

PHP: 8.0 или новее. Модуль не устанавливается на более старых версиях PHP.

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

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

Установка

1. В бэк-офисе перейдите в Modules > Module Manager и нажмите Upload a module. Выберите ZIP-файл модуля.

2. Когда загрузка завершится, нажмите Configure или позже найдите VibeFox Pin Payments Gateway в списке модулей и нажмите Configure.

3. Введите лицензионный ключ VibeFox в поле License key в блоке лицензии вверху страницы Configure и нажмите Activate (см. Лицензионный ключ).

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

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

При установке модуль создаёт статус заказа Pin Payments payment on hold. PrestaShop предлагает новый способ оплаты для валют, групп клиентов и стран, активных на момент установки. Это можно изменить в Payment > Preferences; страны, которые вы включите позже, нужно отметить там же.

Настройка

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Pin Payments Gateway > Configure. У каждого раздела есть своя кнопка Save, которая сохраняет всю страницу. Над полями страница показывает предупреждение, пока включён тестовый режим, ошибку, если публичный или секретный ключ текущего режима пуст, и ошибку, если Pin Payments не поддерживает валюту по умолчанию магазина (со списком поддерживаемых валют). Без обоих ключей текущего режима способ оплаты скрыт на странице оформления заказа. Пустое поле Title не сохраняется: страница показывает Enter a title for the payment method.

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: использует тестовую среду Pin Payments (test-api.pinpayments.com) и тестовые ключи. Реальные списания не выполняются, а покупатели видят под способом оплаты TEST MODE — no real charges will be made. Когда режим выключен, используются боевой API и боевые ключи. По умолчанию: включено.

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

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

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

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

Пробелы вокруг ключей удаляются. Сохранённые секретные ключи больше не показываются. Поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить.

Clear saved secrets: отметьте секретный ключ и нажмите Save, чтобы удалить его. Пустое поле сохраняет сохранённое значение.

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

Debug log: пишет в logs/wc_ppg_debug.log.php в папке модуля. Файл нельзя открыть из браузера. Ошибки записываются всегда; включите эту опцию, чтобы записывать также каждый вызов API. Данные карты, API-ключи и персональные данные покупателей никогда не записываются. По умолчанию: выключено.

Log: показывает размер и последние записи журнала. Нажмите Clear log, чтобы очистить его.

Delete data on uninstall: если включено, при удалении модуля удаляются настройки шлюза и журнал. Данные платежей по заказам (списания и возвраты) и статус заказа Pin Payments payment on hold всегда сохраняются. По умолчанию: выключено.

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

Способ оплаты показывается, когда он включён, заданы оба ключа текущего режима, валюта корзины входит в 14 поддерживаемых (AUD, USD, NZD, SGD, EUR, GBP, CAD, HKD, JPY, MYR, THB, PHP, ZAR, IDR), и модулю разрешено работать с корзиной в Payment > Preferences.

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

Когда покупатель оформляет заказ, Pin.js отправляет данные карты и платёжный адрес корзины из браузера напрямую в Pin Payments и получает одноразовый токен карты. Только этот токен отправляется в ваш магазин. Затем модуль создаёт списание с захватом средств на сумму корзины в валюте корзины, с e-mail покупателя и описанием <shop name> - Cart <cart number>. Pin Payments отвечает в том же запросе. До этого ответа заказа не существует.

После успешного списания заказ создаётся, и покупатель видит стандартную страницу подтверждения заказа с Your card payment has been received. Если заказ попал в Pin Payments payment on hold, страница показывает Your card payment has been received and is being reviewed. We will update your order as soon as the review is complete.

Если Pin Payments не отвечает (таймаут, ошибка сервера, нечитаемый ответ), списание могло всё же пройти. Тогда заказ создаётся в Pin Payments payment on hold без оплаты, а страница подтверждения показывает We could not confirm your payment with Pin Payments. Please check your e-mail and card statement before paying again, or contact us. Повторная отправка той же корзины никогда не создаёт второе списание.

Для одной корзины одновременно выполняется только одна попытка оплаты. Повторная отправка получает This order is already being paid. Please wait a moment and check your e-mail before trying again. Корзина, у которой уже есть заказ, или более ранняя попытка, которая списала или могла списать деньги, повторно не списывается; вместо этого заказ создаётся по этой попытке. Токен карты можно использовать один раз: после неудачной попытки или когда покупатель меняет данные карты, создаётся новый токен.

Если оплата не прошла, заказ не создаётся. Покупатель остаётся на этапе оплаты, корзина сохраняется, и показывается одно из сообщений: Your card was declined. Please use another card or contact your bank.; Your card has insufficient funds. Please use another card.; Your card has expired. Please use another card.; The card security code (CVC) is incorrect.; This card type is not accepted. Please use Visa, Mastercard or American Express.; Payment failed: с причиной от Pin Payments для отклонённых данных; Your card details have expired. Please enter them again and retry., если токен нельзя использовать; The secure card form could not be loaded. Please reload the page or choose another payment method., если Pin.js не загрузился; Card payments are temporarily unavailable. Please try again later or choose another payment method., если Pin Payments отклонил секретный ключ; Your payment could not be processed. Please try again or choose another payment method. при других ошибках. Техническая причина записывается в журнал.

В модуле нет сценария 3-D Secure. Если ваша учётная запись Pin Payments требует 3-D Secure, списание остаётся в ожидании, заказ не создаётся, а покупатель видит Your card payment could not be completed (additional verification is required). Please try another card or another payment method. Нет режима только авторизации с последующим захватом, нет сохранённых карт, подписок, Apple Pay или Google Pay и нет вебхуков.

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

Статусы заказа

No order yet: карта отклонена, списанию требовался 3-D Secure, или покупатель не оплатил. Существует только корзина.

Payment accepted: Pin Payments сообщил об успешном списании с захватом средств точно на сумму и в валюте корзины. Платёж записывается с токеном списания Pin Payments в качестве ID транзакции, а примечание показывает сумму и токен списания (и TEST MODE для тестовых платежей).

Pin Payments payment on hold: списание требует вашей проверки. Примечание объясняет причину: Pin Payments списал сумму или валюту, отличные от корзины (платёж на списанную сумму записывается), корзина изменилась во время оплаты, списание авторизовано, но не захвачено (захватите его в панели Pin Payments, затем переведите заказ в статус «Оплата принята»), или Pin Payments не дал чёткого ответа (платёж не записывается; найдите описание списания в панели Pin Payments до отправки заказа).

Refunded: списание полностью возвращено через модуль.

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

Блок Pin Payments

На странице заказа показан блок Pin Payments со значком Test mode для тестовых платежей, токеном списания, статусом, маркой карты и последними четырьмя цифрами, списанной суммой, суммой заказа и возвращённой суммой, Description at Pin Payments, историей возвратов и Pin Payments notes заказа.

Возвраты

В блоке Pin Payments введите сумму (не возвращённая ещё сумма подставляется автоматически), при необходимости причину, и нажмите Refund via Pin Payments. Подтвердите вопрос Refund this amount through Pin Payments? This cannot be undone. Поддерживаются полные и частичные возвраты. Нужно право на редактирование заказов. Возвраты ограничены суммой и валютой, которые Pin Payments фактически списал, поэтому после расхождения суммы или валюты можно вернуть не больше того, что заплатил покупатель, а не сумму заказа. Возврат отправляется в среду (тестовую или боевую), в которой был оплачен заказ, поэтому секретный ключ этого режима должен быть заполнен. Pin Payments обрабатывает возвраты асинхронно, поэтому статус обычно «В ожидании». Успешный запрос добавляется в историю возвратов и примечания вместе с токеном возврата Pin Payments и его статусом. Полный возврат переводит заказ в статус Refunded. Частичный возврат статус не меняет. Если Pin Payments отклонил возврат или не ответил, блок показывает ошибку, и возврат не записывается.

Если по заказу нет записанного списания (Pin Payments не дал чёткого ответа), блок не показывает форму возврата и подсказывает, какое описание искать в панели Pin Payments.

Модуль не создаёт кредитных накладных. Стандартные кнопки возврата PrestaShop на странице заказа не возвращают деньги через Pin Payments. Возвраты, сделанные в панели Pin Payments, не синхронизируются с PrestaShop, поэтому делайте их со страницы заказа.

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

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Pin Payments Gateway — это первый блок на странице Modules > Module Manager > VibeFox Pin Payments Gateway > Configure, над настройками. Введите ключ в поле License key и нажмите Activate. После этого блок показывает ключ в замаскированном виде, статус (например, дату, до которой лицензия действует, и ваш домен), а также кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: presta-payment-pinpayments и ссылка Manage licenses and domains in your account, которая открывает вашу учётную запись vibefox.net. Изменять ключ могут только сотрудники с правом Configure для модуля. Тексты блока следуют языку административной панели (английский и русский включены).

Если ключ не принят, блок сообщает причину, например Key not found, This key belongs to another product, Domain limit reached или License expired on с датой. После смены адреса магазина или после освобождения слота домена в учётной записи нажмите Check now. Если сервер лицензий недоступен, модуль продолжает работать с последним известным статусом.

Один ключ работает на одном домене: домене основного магазина, в том числе при мультимагазинной настройке. Удаление ключа из магазина не освобождает его слот домена. Освободите слот в своей учётной записи vibefox.net.

Без активного ключа Pin Payments не показывается покупателям на странице оформления заказа. Если платёж всё же начат, покупатель видит This payment method is not available. Please choose another one. Витрина PrestaShop не знает, что вы вошли в бэк-офис, поэтому способ оплаты скрыт и для вас: модуль можно настроить до покупки ключа, но протестировать его на странице оформления заказа нельзя. Напоминание появляется в Modules > Module Manager на вкладке Alerts. Существующие заказы не затрагиваются: возвраты по ранее оплаченным заказам продолжают работать.

Когда лицензия истекает, модуль продолжает работать, но для обновлений и поддержки нужно продление. Статус автоматически проверяется, пока вы работаете в бэк-офисе: раз в день в первые 14 дней после ввода ключа, затем раз в неделю. Cron-задание не нужно. Удаление или сброс модуля всегда удаляет лицензионный ключ и статус лицензии.

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

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

Оплата прошла, но заказ в статусе Pin Payments payment on hold: прочитайте примечания в блоке Pin Payments (см. Статусы заказа). Если Pin Payments не дал чёткого ответа, найдите в панели Pin Payments списание с описанием <shop name> - Cart <cart number>, затем отправьте заказ или верните списание в панели.

Покупатель видит Your payment was received, but the order could not be completed automatically: карта списана, но PrestaShop не смог создать заказ (например, модуль тем временем отключили). Причина записана в журнал. Покупателя просят не платить повторно; повторная отправка той же корзины создаёт заказ без нового списания.

Покупатели видят Card payments are temporarily unavailable: Pin Payments отклонил секретный ключ или ключ текущего режима отсутствует. Тестовые ключи работают только в тестовом режиме, боевые — только в боевом. Журнал показывает причину.

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

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

Pin Payments не ответил: токен карты не был создан в браузере за 30 секунд. Покупатель может проверить соединение и попробовать снова; ничего не списано.

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

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

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

Где искать ошибки: ошибки всегда записываются в журнал; см. поле Log на странице модуля. Включите Debug log, чтобы видеть каждый вызов API.

Удаление

Перейдите в Modules > Module Manager, откройте меню рядом с VibeFox Pin Payments Gateway и выберите Uninstall. Лицензионный ключ и статус лицензии этого модуля всегда удаляются. Если Delete data on uninstall включено, настройки шлюза и журнал удаляются. Если выключено, все настройки сохраняются для повторной установки. Списания и возвраты Pin Payments и статус заказа Pin Payments payment on hold всегда сохраняются, поэтому заказы, оплаченные ранее, можно вернуть и после повторной установки. Существующие заказы сохраняют примечания об оплате и ID транзакций.

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