VibeFox Midtrans for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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

Валюта: индонезийская рупия (IDR). Midtrans принимает оплату только в IDR, поэтому способ оплаты предлагается только тогда, когда валюта корзины — IDR. Конвертация валют не выполняется. Если в вашем магазине нет валюты IDR, добавьте её в разделе International > Localization.

Аккаунт Midtrans: вам нужен Server Key из раздела Midtrans Dashboard > Settings > Access Keys, как в панели sandbox, так и в рабочей панели (production). Используется только Server Key. Client Key для Snap Redirect не нужен. Сами способы оплаты (GoPay, QRIS, виртуальные счета и другие) включаются в вашем аккаунте Midtrans.

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

Установка

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

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

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

4. Введите Server Key и скопируйте URL уведомлений об оплате в панель Midtrans (см. раздел Настройка).

5. Включите Enable/Disable и нажмите Save. Проверьте работу в Sandbox, затем переключите Environment на Production.

При установке модуль создаёт два статуса заказа: Awaiting Midtrans payment и Midtrans payment on hold. PrestaShop предлагает новый модуль оплаты для всех валют, стран и групп покупателей. Ограничить их можно в разделе Payment > Preferences. Модуль должен оставаться разрешённым для валюты IDR.

Настройка

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Midtrans Payment Gateway > Configure. У каждого раздела есть своя кнопка Save, которая сохраняет всю страницу. Над полями страница предупреждает, если Server Key выбранной среды не задан (тогда способ оплаты скрыт при оформлении заказа) или если валюта магазина по умолчанию не IDR, а при выбранной среде Sandbox показывает Sandbox mode: payments are simulated, no real money is charged.

Midtrans

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

Title: название способа оплаты, которое покупатели видят при оформлении заказа. Оно же сохраняется в заказе как название способа оплаты. По умолчанию: Midtrans. Обязательное поле.

Description: текст под способом оплаты при оформлении заказа. По умолчанию: Pay securely via Midtrans — GoPay, QRIS, ShopeePay, cards, bank transfer and more. В Sandbox добавляется строка SANDBOX MODE: no real money is charged.

Учётные данные API

Скопируйте Server Key из раздела Midtrans Dashboard > Settings > Access Keys. В разделе есть ссылки на рабочую панель и на панель sandbox.

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

Sandbox: для тестирования, без реальных денег.

Production: реальные платежи.

Production Server Key: начинается с Mid-server-. Храните его в секрете.

Sandbox Server Key: начинается с SB-Mid-server-.

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

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

URL уведомлений об оплате

Уведомление сообщает вашему магазину, что оплата произведена. Поле Notification URL показывает URL, который нужно использовать. При включённых понятных URL он выглядит так: https://your-shop/module/wcp_midtrans_payment_gateway/webhook, возможно с кодом языка, например /en/. Скопируйте URL точно так, как он показан в настройках, и вставьте его в Midtrans Dashboard > Settings > Payment > Notification URL — в панели sandbox и в рабочей панели, которую вы используете. Если открыть URL в браузере, появится короткое пояснение, так что вы можете проверить, что он доступен. Кнопка Test notification URL в панели Midtrans тоже получит ответ.

Каждое уведомление должно содержать действительную подпись, сделанную одним из ваших Server Key, и среда ключа должна совпадать со средой платежа. Уведомления без действительной подписи отклоняются. Тогда статус повторно запрашивается через API статуса Midtrans. Модуль обрабатывает следующие статусы транзакций Midtrans:

settlement, capture (accepted): оплата произведена. Заказ создаётся как оплаченный, когда сумма (в целых рупиях) и валюта совпадают с корзиной.

capture (challenge): платёж картой, отмеченный системой выявления мошенничества Midtrans. Заказ переводится в Midtrans payment on hold, пока вы не одобрите или не отклоните его в панели Midtrans.

pending: покупатель выбрал отложенный способ (виртуальный счёт, магазин шаговой доступности) и ещё не оплатил. Заказ создаётся в статусе Awaiting Midtrans payment.

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

deny: оплата отклонена. Ожидающий заказ переводится в Payment error.

failure: оплата не прошла. Ожидающий заказ переводится в Payment error.

refund, partial_refund: возврат, оформленный в панели Midtrans, регистрируется в заказе.

Без URL уведомлений заказ создаётся только тогда, когда покупатель возвращается в магазин после оплаты, а отложенный платёж, совершённый позже, не виден до возвращения покупателя.

Настройки оплаты

Midtrans принимает оплату только в IDR, суммы передаются в целых рупиях. Если строки заказа не сходятся с округлённой суммой, в Midtrans отправляется строка Rounding adjustment.

Status after payment: статус заказа после подтверждённой оплаты.

Processing (default): Payment accepted, стандартный статус PrestaShop для оплаченных заказов.

Completed: каждый оплаченный заказ переводится в Delivered.

On hold: каждый оплаченный заказ переводится в Midtrans payment on hold для вашей ручной проверки. Платёж при этом остаётся зарегистрированным в заказе.

Payment page expiry (minutes): сколько времени покупатель может оплатить (страница Snap, виртуальный счёт и т. д.). Оставьте поле пустым или укажите 0, чтобы использовать значение Midtrans по умолчанию. Значение, которое не является целым числом минут, отклоняется с ошибкой при сохранении.

Order ID prefix: добавляется к номеру, который отправляется в Midtrans, чтобы несколько магазинов могли использовать один аккаунт Midtrans. Номер состоит из ID корзины с отметкой времени, например WC-123-1700000000. Допускаются только буквы, цифры и символы - _ . ~, до 20 символов; остальные символы удаляются при сохранении. Уведомления других магазинов игнорируются. По умолчанию: WC-.

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

Debug log: записывает вызовы API и уведомления в файл logs/midtrans_p_debug.log.php в папке модуля. Файл нельзя открыть из веб-браузера. Ошибки записываются всегда. Ключи и данные покупателей никогда не записываются. По умолчанию: выключено.

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

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

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

На этапе оплаты покупатель выбирает способ оплаты (по умолчанию Midtrans) и подтверждает. Модуль создаёт транзакцию Midtrans Snap на сумму корзины в целых рупиях, с позициями заказа, доставкой, скидками, подарочной упаковкой, налогом и платёжными и адресными данными покупателя, и отправляет покупателя на страницу оплаты Midtrans. Там покупатель выбирает любой способ, включённый в вашем аккаунте Midtrans. На этом этапе заказа ещё не существует.

После оплаты покупатель возвращается в ваш магазин. Ссылка возврата сама по себе никогда не отмечает заказ как оплаченный: заказ отмечается оплаченным только после подтверждения Midtrans — подписанным уведомлением или запросом к API статуса Midtrans, когда покупатель возвращается. Тогда заказ создаётся, и покупатель видит стандартную страницу подтверждения заказа с использованным способом оплаты. Для отложенного платежа страница показывает We are waiting for Midtrans to confirm your payment. If you chose a bank transfer, virtual account or convenience store, please complete the payment using the instructions from Midtrans. You will receive an e-mail once the payment is confirmed. Для заказа, закрытого без оплаты, — Your Midtrans payment was not completed. Please contact us about this order. Если Midtrans недоступен, когда покупатель возвращается, страница Payment confirmation показывает We are confirming your payment with Midtrans. The order will be updated automatically — please do not pay again. с кнопкой Check again.

Если покупатель покинул страницу Snap, не оплатив, он возвращается к оформлению заказа с сообщением The Midtrans payment was not completed. You can try again below. Если оплата отклонена или срок её истёк, сообщение: Your Midtrans payment was declined or has expired. Please try again or choose another payment method. Корзина сохраняется. Когда покупатель оплачивает снова, повторно используется неиспользованный или ожидающий Snap на ту же сумму. Если сумма изменилась, ожидающая транзакция сначала истекает в Midtrans. Если предыдущий Snap тем временем оплачен, заказ создаётся, и новая транзакция не создаётся. Если заказ уже существует и был закрыт без оплаты, сообщение: Your Midtrans payment was declined or has expired. Please place a new order or contact us.

Если Midtrans не может начать оплату, покупатель остаётся на оформлении заказа с кратким сообщением: Could not connect to Midtrans. Please try again in a moment., Midtrans payments are temporarily unavailable. Please choose another payment method or contact us. (например, при неверном Server Key) или причина, которую сообщает Midtrans. Техническая причина записывается в журнал. Корзина не в IDR выводит сообщение Midtrans only supports payments in IDR (Indonesian Rupiah). Please choose another payment method.

Уведомление работает, когда магазин находится в режиме обслуживания, и не блокируется ограничением по странам вашего магазина.

Модуль использует только Snap Redirect. У него нет всплывающего окна Snap, формы карты на вашем сайте, сохранённых карт или оплаты в один клик, настроек рассрочки или промоакций (способы оплаты настраиваются в панели Midtrans) и подписок. Платежи картой списываются сразу, без раздельной авторизации и списания.

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

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

No order yet: покупатель был направлен в Midtrans и не оплатил, или Midtrans ещё не подтвердил оплату. Существует только корзина.

Awaiting Midtrans payment: покупатель выбрал отложенный способ (виртуальный счёт, магазин шаговой доступности) или начал платёж картой, который не завершён. Заказ становится оплаченным, когда Midtrans сообщает об оплате.

Payment accepted, Delivered или Midtrans payment on hold: оплата подтверждена. Статус следует за настройкой Status after payment. Платёж регистрируется с ID транзакции Midtrans, а примечание показывает способ оплаты и ID заказа Midtrans.

Midtrans payment on hold: также устанавливается, когда платёж картой находится на проверке безопасности (challenge, оплата ещё не зарегистрирована), когда оплаченная сумма или валюта не совпали с заказом (заказ не отмечается оплаченным) или когда поступил платёж за отменённый заказ (заказ не открывается заново автоматически). Примечание объясняет причину. Проверьте заказ, затем выполните его или верните платёж.

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

Payment error: оплата не прошла или платёж картой, отправленный на проверку, был отклонён.

Refunded: платёж полностью возвращён.

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

Блок оплаты Midtrans

На странице заказа показан блок Midtrans payment с ID заказа Midtrans, ID транзакции (со ссылкой на транзакцию в панели Midtrans той среды, в которой произошёл платёж), способом оплаты, статусом, оплаченной и возвращённой суммой, значком Sandbox для тестовых платежей, историей возвратов и Midtrans notes заказа.

Возвраты

В блоке Midtrans payment введите сумму (подставляется сумма, которая ещё не возвращена), при необходимости причину, и нажмите Refund via Midtrans. Подтвердите вопрос Refund this amount through Midtrans? This cannot be undone. Полные и частичные возвраты поддерживаются в целых рупиях; сумма с десятичными знаками отклоняется. Вам нужно право редактировать заказы. Можно вернуть сумму, не более той, которую Midtrans фактически списал, даже если заказ редактировался позже. Возврат отправляется в той среде, где совершён платёж, поэтому для неё должен быть задан её Server Key. Midtrans разрешает возвраты через API только для некоторых способов оплаты и состояний транзакций (например, для проведённых платежей картой, GoPay, QRIS или ShopeePay). Если Midtrans не принимает возврат, блок показывает ошибку и возврат не регистрируется; тогда оформите возврат в панели Midtrans. Успешный возврат добавляется в историю возвратов и примечания. Полный возврат переводит заказ в Refunded. Частичный возврат статус не меняет. Возвраты доступны, когда Midtrans сообщил, что платёж проведён.

Модуль не создаёт кредитные чеки. Стандартные кнопки возврата PrestaShop на странице заказа не возвращают деньги через Midtrans.

Возвраты, оформленные в панели Midtrans, приходят в уведомлении и автоматически добавляются в историю возвратов с причиной Refunded in the Midtrans dashboard. Когда весь платёж возвращён там, заказ переводится в Refunded.

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

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Midtrans Payment Gateway — это первый блок на странице Modules > Module Manager > VibeFox Midtrans Payment Gateway > Configure, над настройками. Введите ключ в поле License key и нажмите Activate. После этого блок показывает ключ в скрытом виде, статус (например, дату, до которой действует лицензия, и ваш домен), а также кнопки Check now, чтобы снова проверить статус, Change key, чтобы ввести другой ключ, и Remove key, чтобы удалить ключ из этого магазина. Ниже находятся строка Product: presta-payment-midtrans и ссылка 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.

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

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

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

Midtrans does not appear at checkout: проверьте, что лицензия действует, что Enable/Disable включено и что для выбранной Environment задан Server Key. Проверьте, что валюта корзины — IDR. В разделе Payment > Preferences проверьте, что модуль разрешён для IDR, для страны покупателя и для его группы. На странице настроек появляется предупреждение, если ключ не задан или валюта магазина не IDR.

The payment went through, but no order was created: уведомление не работает. Проверьте, что URL уведомлений об оплате задан в панели Midtrans той среды, которую вы используете (sandbox или production), что он в точности совпадает с URL из Notification URL и что он доступен: откройте его в браузере, должно появиться короткое пояснение. Включите Debug log, чтобы увидеть уведомления. Заказ также создаётся, когда покупатель возвращается в магазин после оплаты.

Notification answers Invalid signature: уведомление не подписано вашим Server Key Sandbox или Production. Проверьте, что ключи в настройках принадлежат тому же аккаунту Midtrans, что и панель, отправляющая уведомления.

Notification answers Server key not configured: Server Key не задан. Введите его в настройках; Midtrans повторит уведомление.

Notification answers Order not found — ignored: ID заказа Midtrans не был выдан этим магазином, например другим магазином на том же аккаунте Midtrans. Задайте каждому магазину свой Order ID prefix.

Notification answers Environment mismatch — ignored: уведомление подписано ключом среды, отличной от той, в которой был совершён платёж.

Notification answers Verification failed, please retry: API статуса Midtrans недоступен. Midtrans повторит уведомление.

Notification answers Busy, please retry: корзина в этот момент обновлялась другим запросом, либо заказ не удалось создать (например, модуль отключён). Midtrans повторит уведомление. Причину смотрите в журнале.

The order is Midtrans payment on hold: прочитайте Midtrans notes в блоке. Платёж картой проходит проверку безопасности, оплаченная сумма или валюта не совпали с заказом, либо платёж поступил после отмены заказа.

The customer sees an error when choosing Midtrans: посмотрите поле Log на странице модуля; ошибки записываются всегда. Неверный Server Key выводит сообщение, что оплата Midtrans временно недоступна.

Refund fails: способ оплаты или состояние транзакции не позволяют возвраты через API; оформите возврат в панели Midtrans, и он будет автоматически записан в заказ. Если сообщение говорит, что для среды, в которой оплачен заказ, не задан Server Key, введите этот ключ и повторите попытку.

Разработчики могут изменить данные, отправляемые в Midtrans, с помощью хука actionWcpMidtransSnapPayload; ID заказа и сумму изменить нельзя.

Удаление

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

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