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

Требования

OpenCart: 3.0.x (проверено на 3.0.5.0) или 4.0.2 и новее (проверено на 4.1.0.3).

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

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

Валюта: AUD, USD, NZD, SGD, EUR, GBP, CAD, HKD, JPY, MYR, THB, PHP, ZAR или IDR. Заказ списывается в своей валюте.

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

Установка

Загружаемый файл — это один ZIP-архив с пакетами для обеих версий OpenCart. Распакуйте его на компьютере. Он содержит README.txt, пакет для OpenCart 3 wcp_pinpayments_gateway-oc3-(version).ocmod.zip и пакет для OpenCart 4 wcp_pinpayments_gateway.ocmod.zip. Устанавливайте только пакет для вашей версии OpenCart. Лицензионный ключ одинаков для обеих версий.

OpenCart 3

1. В административной панели перейдите в Extensions > Installer, нажмите Upload и выберите файл wcp_pinpayments_gateway-oc3-(version).ocmod.zip. Расширение не содержит модификаций OCMOD, поэтому обновлять Extensions > Modifications не нужно. Вместо установщика можно скопировать содержимое папки upload этого пакета в корневую папку вашего магазина.

2. Перейдите в Extensions > Extensions и выберите тип Payments. Найдите VibeFox Pin Payments Gateway и нажмите Install (зелёная кнопка +). Вашему пользователю администратора нужно право на изменение списка расширений оплаты.

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

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

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

OpenCart 4

1. В административной панели перейдите в Extensions > Installer, нажмите Upload и выберите файл wcp_pinpayments_gateway.ocmod.zip. Не переименовывайте файл: OpenCart 4 берёт код расширения из имени файла, и переименованный пакет не работает.

2. Пакет появляется в списке установленных расширений на той же странице. Нажмите рядом с ним Install (зелёная кнопка +).

3. Перейдите в Extensions > Extensions и выберите тип Payments. Найдите VibeFox Pin Payments Gateway, нажмите Install (зелёная кнопка +), затем Edit (кнопка с изображением карандаша).

4. Введите лицензионный ключ и ключи Pin Payments так же, как в шагах 3–5 для OpenCart 3. Страница настроек и её поля одинаковы в обеих версиях.

Новая установка начинает работу с выключенным способом оплаты и включённым тестовым режимом.

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Payments > VibeFox Pin Payments Gateway > Edit. Разделы перечислены слева; кнопка Save под списком сохраняет всю страницу. Над настройками страница показывает Pin Payments работает в ТЕСТОВОМ РЕЖИМЕ: используются тестовый API и тестовые ключи, реальные списания не производятся., пока включён тестовый режим; ошибку, пока публичный или секретный ключ текущего режима пуст (способ оплаты тогда скрыт на оформлении заказа); и ошибку, когда Pin Payments не поддерживает валюту по умолчанию магазина (со списком поддерживаемых валют). Без права на изменение расширения страница показывает настройки, но не может их сохранить.

При сохранении, если какое-то поле заполнено неверно, ничего не сохраняется: Title не может быть пустым (Введите название способа оплаты (не более 128 символов).), Sort Order должен быть целым числом (отрицательные значения допускаются), Total — числом не меньше 0, а Geo Zone и статусы заказов должны существовать.

Pin Payments

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

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

Description: текст, который покупатель видит на шаге Confirm Order над формой карты. По умолчанию: Pay with your credit card via Pin Payments.

Sort Order: место Pin Payments среди способов оплаты на оформлении заказа. Оставьте поле пустым или введите целое число.

Geo Zone: показывать форму карты только для платёжных адресов из выбранной географической зоны. По умолчанию: All zones. Географические зоны настраиваются в разделе System > Localisation > Geo Zones.

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

Ключи API

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

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

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

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

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

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

Пробелы вокруг ключей удаляются. Сохранённые секретные ключи больше не показываются. Поле остаётся пустым и показывает Сохранено — оставьте пустым, чтобы не менять. Вводите новое значение, только если хотите его изменить. Чтобы удалить сохранённый секретный ключ, отметьте под полем Clear the saved value on save и нажмите Save.

Заказы

OpenCart создаёт заказ на шаге Confirm Order без статуса (неполный заказ). Заказ получает статус только после того, как Pin Payments ответит на списание. Каждое поле ниже перечисляет ваши статусы заказов OpenCart.

Order Status After Payment: карта списана ровно на сумму и в валюте заказа. По умолчанию: Processing.

On Hold (Review) Status: списанная сумма или валюта отличается от заказа, списание авторизовано, но не захвачено, либо Pin Payments не дал чёткого ответа (тайм-аут, ошибка сервера), поэтому списание может существовать. Примечание подскажет, что проверить в личном кабинете Pin Payments. По умолчанию: Pending, так как в OpenCart нет статуса On hold. Вы можете создать собственный статус в System > Localisation > Order Statuses и выбрать его здесь.

Refunded Status: устанавливается после полного возврата платежа со вкладки заказа. По умолчанию: Refunded.

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

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

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

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

Импорт / экспорт

Export: Download JSON сохраняет настройки в файл JSON. Секретные ключи не экспортируются.

Import: вставьте ранее экспортированный JSON и нажмите Import, чтобы восстановить настройки. Сохранённые секретные ключи остаются без изменений.

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

Способ оплаты показывается, когда он включён, оба ключа текущего режима заполнены, валюта заказа входит в число 14 поддерживаемых, платёжный адрес находится в выбранной Geo Zone, а заказ достигает значения Total.

На шаге Payment Method покупатель выбирает способ оплаты (по умолчанию Credit card (Pin Payments)). OpenCart создаёт заказ на шаге Confirm Order, по-прежнему без статуса. Там покупатель видит ваше описание, значки Visa, Mastercard и American Express и форму карты: Card number, Expiry (MM / YY), CVC и Name on card. На OpenCart 4 покупатель выбирает способ оплаты кнопкой Choose в блоке способа оплаты, в окне Payment method options; форма карты затем появляется в блоке подтверждения внизу страницы оформления заказа, над кнопкой Confirm Order. Перед отправкой форма проверяет длину номера карты, месяц и год окончания срока действия, CVC из 3 или 4 цифр и имя.

Когда покупатель нажимает Confirm Order, Pin.js отправляет данные карты и платёжный адрес заказа (на OpenCart 4, если оформление не запрашивает платёжный адрес, — адрес доставки) из браузера напрямую в Pin Payments и получает одноразовый токен карты. Только этот токен поступает в ваш магазин. Затем расширение создаёт захваченное списание на сумму заказа в валюте заказа с e-mail и IP-адресом покупателя и описанием <store name> - Order <order number>. Pin Payments отвечает в том же запросе.

После успешного списания заказ получает статус обычным для OpenCart способом, с обычными письмами о заказе и обновлением остатков; корзина очищается, и покупатель видит страницу успешного оформления заказа OpenCart с сообщением Your card payment has been received. Если заказ перешёл в статус проверки, страница показывает Ваш платёж картой получен и проверяется. Мы обновим ваш заказ, как только проверка будет завершена.

Если Pin Payments не отвечает (тайм-аут, ошибка сервера, нечитаемый ответ), списание могло быть создано. Тогда заказ переходит в статус проверки с примечанием, а страница успешного оформления показывает Мы не смогли подтвердить ваш платёж через Pin Payments. Перед повторной оплатой проверьте e-mail и выписку по карте или свяжитесь с нами. Повторная отправка той же корзины никогда не создаёт второе списание.

Одновременно выполняется только одна попытка оплаты корзины. Повторная отправка получает Этот заказ уже оплачивается. Подождите немного и проверьте e-mail, прежде чем пробовать снова. OpenCart 3 создаёт новый заказ каждый раз, когда показывается шаг Confirm Order, а OpenCart 4 обновляет заказ оформления (после отказа карты покупатель оплачивает тот же заказ), поэтому корзина, уже оплаченная другим заказом, сразу переходит на страницу успешного оформления, а более ранняя попытка, которая списала или могла списать деньги, передаёт свой статус заказу вместо создания нового списания. Токен карты можно использовать только один раз: после неудачной попытки или когда покупатель меняет данные карты, создаётся новый токен.

OpenCart 4 хранит заказ в оформлении, пока не будет показана страница успеха. Если этот заказ к тому времени уже получил статус при подтверждении нового заказа (например, он был оплачен, а страница успеха так и не открылась, либо вы его отменили), покупатель возвращается в оформление, и следующее нажатие Confirm Order оплачивает новый заказ текущей корзины. Над страницей оформления покупатель видит Ваш предыдущий заказ был отменён или возвращён магазином. Подтвердите заказ снова, чтобы оплатить новым заказом., если заказ был закрыт, или Ваш предыдущий заказ #(number) уже оформлен. Корзина изменилась: подтвердите новый заказ, чтобы оплатить её., если он был оформлен для более ранней корзины. Оплаченный заказ никогда не показывается как оплаченный для другой корзины.

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

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

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

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

Без статуса (неполный заказ): карта была отклонена, списание требовало 3-D Secure, или покупатель не оплатил. В Sales > Orders такие заказы показываются только с фильтром Order Status, установленным в значение Missing Orders.

Order Status After Payment (по умолчанию Processing): Pin Payments сообщил об успешном захваченном списании ровно на сумму и в валюте заказа. Примечание показывает сумму и токен списания (и ТЕСТОВЫЙ РЕЖИМ для тестовых платежей).

On Hold (Review) Status (по умолчанию Pending): списание требует вашей проверки. Примечание объясняет причину: Pin Payments списал сумму или валюту, отличающиеся от заказа; списание авторизовано, но не захвачено (захватите его в личном кабинете Pin Payments, затем измените статус заказа); либо Pin Payments не дал чёткого ответа (найдите описание списания в личном кабинете Pin Payments до отправки заказа).

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

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

Примечания — это записи в History заказа, которые покупатель не видит.

VibeFox Pin Payments Gateway tab

В Sales > Orders откройте заказ, оплаченный через Pin Payments. Внизу страницы заказа, рядом с History и Additional, вкладка VibeFox Pin Payments Gateway показывает токен Charge с меткой Test для тестовых платежей, Status, марку и последние четыре цифры Card, суммы Charged / order / refunded (списано / заказ / возвращено), Charge description, форму возврата, историю возвратов и Pin Payments notes заказа. Вкладка показывается пользователям, имеющим доступ к расширению.

Возвраты

На вкладке VibeFox Pin Payments Gateway введите Amount (подставляется сумма, которая ещё не возвращена), при необходимости Reason (optional), и нажмите Refund via Pin Payments. Подтвердите вопрос Вернуть эту сумму через Pin Payments? Это действие нельзя отменить. Поддерживаются полные и частичные возвраты. Вам нужно право на изменение расширения (задаётся в System > Users > User Groups). Возвраты ограничены суммой и валютой, которые Pin Payments фактически списал, поэтому после расхождения суммы или валюты можно вернуть не больше того, что заплатил покупатель, а не сумму заказа. Возврат отправляется в ту среду (тестовую или боевую), в которой был оплачен заказ, поэтому секретный ключ этого режима должен быть задан. Pin Payments обрабатывает возвраты асинхронно, поэтому обычно статус Pending. Успешный запрос добавляется в историю возвратов и примечания вместе с токеном возврата Pin Payments и его статусом. Полный возврат устанавливает заказу Refunded Status без уведомления покупателя и без возврата товаров на склад, как при ручном изменении статуса. Частичный возврат статус не меняет. Если Pin Payments отклоняет возврат или не отвечает, вкладка показывает ошибку, и возврат не регистрируется.

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

Возвраты товаров в Sales > Returns не возвращают деньги через Pin Payments. Возвраты, сделанные в личном кабинете Pin Payments, не синхронизируются с OpenCart, поэтому выполняйте их со страницы заказа.

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

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

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

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

Без активного ключа Pin Payments не показывается покупателям на оформлении заказа. Если платёж всё же начат, покупатель видит Этот способ оплаты недоступен. Выберите другой. Пользователь-администратор, вошедший в административную панель в том же браузере, по-прежнему видит способ оплаты в магазине, помеченный как (без лицензии — видно только администраторам), чтобы вы могли настроить и протестировать расширение до покупки ключа. На OpenCart 4 этого предпросмотра нет: магазин не видит вход в административную панель, поэтому без действующего ключа способ оплаты скрыт для всех. После того как вы один раз открыли страницу Edit, на Dashboard административной панели появляется напоминание. Закройте его кнопкой ×, чтобы скрыть на 7 дней. Существующие заказы не затрагиваются: возвраты по заказам, оплаченным ранее, по-прежнему работают.

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

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

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

Платёж прошёл, но заказ находится в статусе проверки: прочитайте примечания на вкладке VibeFox Pin Payments Gateway (см. Статусы заказов). Если Pin Payments не дал чёткого ответа, найдите в личном кабинете Pin Payments списание с описанием <store name> - Order <order number>, затем выполните заказ или верните списание в личном кабинете.

Покупатель видит сообщение «Ваш платёж получен, но заказ не удалось завершить автоматически»: карта списана, но статус заказа не удалось установить (например, заказ был удалён в это время). Причина указана в журнале. Покупателю предлагается не платить повторно; повторная отправка той же корзины присваивает заказу статус без нового списания.

Покупатель видит сообщение «Этот способ оплаты недоступен. Обновите страницу оформления заказа.»: сессия оформления заказа больше не соответствует заказу, или способ оплаты тем временем выключили. Покупатель обновляет страницу оформления заказа.

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

Заказы не проходят с сообщением «требуется дополнительная проверка»: ваша учётная запись 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 (успешно), с любой будущей датой окончания срока действия и любым CVC. Заказы сохраняют режим, в котором были оплачены, поэтому возвраты уходят в правильную среду даже после переключения режима.

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

Удаление

Перейдите в Extensions > Extensions, выберите тип Payments и нажмите Uninstall (красная кнопка −) рядом с VibeFox Pin Payments Gateway. Лицензионный ключ и статус лицензии этого расширения удаляются всегда. OpenCart всегда удаляет собственные настройки расширения: Enable/Disable, Sort Order, Geo Zone, Total и статусы заказов из раздела Заказы, которые при повторной установке возвращаются к значениям по умолчанию. Событие OpenCart расширения также удаляется (на OpenCart 4 удаляются его два события, которые показывают сообщения на странице успеха и над страницей оформления заказа). Если включено Delete data on uninstall, удаляются остальные настройки шлюза (название, описание, тестовый режим, ключи, переключатель журнала отладки) и журнал. Если выключено, они сохраняются для повторной установки. Списания и возвраты Pin Payments всегда сохраняются, поэтому заказы, оплаченные ранее, можно вернуть и после повторной установки. Существующие заказы сохраняют примечания об оплате.

На OpenCart 4, чтобы удалить и файлы расширения, после удаления перейдите в Extensions > Installer и нажмите Uninstall (оранжевая кнопка −) рядом с VibeFox Pin Payments Gateway в списке установленных расширений, затем Delete (красная кнопка с корзиной), чтобы удалить загруженный пакет.

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