VibeFox dLocal for PrestaShop — Помощь

Требования

PrestaShop: от 8.0 до 9.x.

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

Доступ к магазину: ваш магазин должен быть доступен из интернета и использовать HTTPS в рабочей среде, чтобы dLocal Go мог отправлять уведомления о платежах.

Учётная запись dLocal Go: вам нужны API-ключ и API-секрет из панели dLocal Go, раздел Payment integration: dashboard-sbx.dlocalgo.com для тестовой среды, dashboard.dlocalgo.com для рабочей. Тестовая и рабочая среды используют разные учётные данные. Корпоративный API dLocal Payments (учётные данные X-Login / X-Trans-Key) — это другой продукт, он не поддерживается.

Страны и валюты: модуль их не ограничивает. dLocal Go сам решает, какие способы оплаты предлагать для страны покупателя и валюты корзины. Действуют только ограничения оплаты PrestaShop.

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

Установка

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

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

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

4. Выберите Environment и вставьте API-ключ и API-секрет этой среды (см. Настройки).

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

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

Настройки

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox dLocal Payment > Configure. У каждого раздела есть собственная кнопка Save, которая сохраняет всю страницу. В заголовке первого раздела отображается SANDBOX или PRODUCTION. Пока не введены API-ключ и секрет выбранной среды, страница предупреждает, что способ оплаты скрыт при оформлении заказа, например Enter the sandbox API key and secret: until then the payment method is hidden at checkout. Когда выбран sandbox и способ оплаты включён, отображается Sandbox mode is active: payments are simulated, no money is charged.

dLocal Go

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

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

Description: текст под способом оплаты при оформлении заказа. По умолчанию: Pay with local cards, bank transfer or cash via dLocal Go.

API-учётные данные

Скопируйте API-ключ и API-секрет из панели dLocal Go, Payment integration: dashboard-sbx.dlocalgo.com (sandbox) или dashboard.dlocalgo.com (production). В разделе есть ссылки на обе панели.

Environment: какие учётные данные и какие серверы dLocal Go используются для новых платежей.

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

Sandbox API Key: ваш API-ключ sandbox dLocal Go.

Sandbox API Secret: ваш API-секрет sandbox dLocal Go.

Production API Key: ваш API-ключ production dLocal Go.

Production API Secret: ваш API-секрет production dLocal Go.

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

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

Оплата

Default country: dLocal Go показывает способы оплаты страны покупателя, которая берётся из адреса для выставления счёта, а если его нет — из адреса доставки. Эта страна используется, когда в корзине нет ни одного из них. По умолчанию: Uruguay.

Auto-complete orders: переводит оплаченные заказы в статус Delivered вместо Payment accepted. Статус устанавливается сразу, одним изменением. По умолчанию: выключено.

Notifications (IPN): уведомления сообщают вашему магазину, что платёж или возврат изменился. Модуль передаёт адреса уведомлений в dLocal Go с каждым платежом и возвратом, поэтому в панели dLocal Go ничего настраивать не нужно. В этом поле показаны оба адреса:

Уведомления проверяются с помощью вашего API-секрета (HMAC-SHA256). Уведомления без корректной подписи отклоняются. Уведомление должно быть подписано учётными данными среды, в которой был совершён платёж. После этого статус, сумма и валюта платежа всегда заново считываются из API dLocal Go; содержимому уведомления не доверяют. Без уведомлений заказ создаётся, только когда покупатель возвращается в магазин.

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

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

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

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

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

На этапе оплаты покупатель выбирает способ оплаты (по умолчанию dLocal Go). В режиме sandbox при оформлении заказа под способом оплаты показывается Sandbox mode: no real payment is made. После подтверждения модуль создаёт платёж dLocal Go на итоговую сумму корзины в валюте корзины с указанием страны, имени, e-mail и телефона покупателя и отправляет покупателя на платёжную страницу dLocal Go. Там покупатель платит способом своей страны. На странице dLocal Go платёж отображается как Order # и номер корзины. На этом этапе заказа ещё нет.

После оплаты покупатель возвращается в ваш магазин. Заказ отмечается оплаченным только после подтверждения dLocal Go: по подписанному уведомлению или серверным запросом к API dLocal Go при возврате покупателя. Затем заказ создаётся, и покупатель видит стандартную страницу подтверждения заказа с Your payment with dLocal Go has been received. Если заказ был переведён на удержание, страница показывает Your dLocal Go payment has been received and is being reviewed by the store. You will be informed when your order is confirmed. Если dLocal Go ещё не подтвердил платёж (например, ваучер для оплаты наличными ещё не оплачен или dLocal Go был недоступен), страница Payment confirmation просит покупателя не платить повторно и предлагает Check again и Back to checkout. Заказ создаётся, как только dLocal Go подтверждает платёж.

Если покупатель уходит со страницы dLocal Go без оплаты, он возвращается к оформлению заказа и видит The payment at dLocal Go was not completed. You can try again or choose another payment method. Если платёж отклонён или истёк, сообщение: Your dLocal payment was not completed: it was declined or it expired. Please try again or choose another payment method. Корзина сохраняется. Каждая новая попытка создаёт новый платёж dLocal Go; более старая ссылка на оплату той же корзины всё ещё может быть оплачена, и тогда она создаст заказ.

Если dLocal Go не может начать платёж, покупатель остаётся на оформлении заказа с коротким сообщением, например dLocal could not start the payment:, после которого указана причина от dLocal. Так бывает и тогда, когда страна покупателя и валюта корзины не включены в вашей учётной записи dLocal Go. Если dLocal Go отклоняет ваши учётные данные, покупатель видит This payment method is temporarily unavailable. Please choose another payment method or contact us. Техническая причина записывается в журнал.

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

Модуль принимает только разовые платежи на странице dLocal Go. В нём нет формы карты на вашем сайте, сохранённых карт, подписок и раздельных авторизации и списания.

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

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

Заказа ещё нет: покупатель был переведён на dLocal Go и не оплатил, или платёж ещё ожидает в dLocal Go. Существует только корзина.

Payment accepted или Delivered: платёж подтверждён. Заказ получает статус «Оплата принята» или, если включено Auto-complete orders, статус «Доставлен». Платёж записывается с ID платежа dLocal как ID транзакции, а заметка показывает среду и ID платежа.

dLocal payment on hold: dLocal Go сообщил сумму или валюту, отличающиеся от итоговой суммы корзины (например, корзину изменили в другой вкладке после начала платежа), либо платёж пришёл после отмены заказа. Заметка объясняет это. Сверьтесь с панелью dLocal Go и либо выполните заказ, либо верните платёж.

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

Отклонённый, истёкший или отменённый платёж никогда не меняет существующий заказ. Если второй платёж приходит по уже оплаченному заказу, заказ не меняется. Заметка просит вернуть дублирующий платёж в панели dLocal Go.

Блок оплаты dLocal Go

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

Возвраты

В блоке dLocal Go payment введите сумму (невозвращённая сумма подставляется автоматически), при необходимости причину, и нажмите Refund via dLocal Go. Подтвердите вопрос Refund this amount through dLocal Go? This cannot be undone. Поддерживаются полные и частичные возвраты. Нужно право редактировать заказы; доступ к страницам Modules не требуется. Возвраты делаются в сумме и валюте, которые списал dLocal Go, поэтому после расхождения суммы или валюты можно вернуть до той суммы, которую покупатель реально заплатил, а не до итога заказа. Возврат отправляется в среду, в которой был совершён платёж, с учётными данными этой среды. Если dLocal Go не принимает возврат, блок показывает ошибку, и возврат не записывается. Принятый возврат добавляется в историю возвратов и заметки с ID возврата, статусом и причиной. Полный возврат переводит заказ в статус Refunded. Частичный возврат статус не меняет.

Затем dLocal Go сообщает окончательный статус возврата в уведомлении о возврате, и он добавляется в заметки. Если dLocal Go позже отклоняет или отменяет принятый им возврат, заметка предупреждает, что деньги покупателю не вернулись. Верните деньги покупателю повторно или другим способом.

Модуль не создаёт кредит-ноты (credit slip). Стандартные кнопки возврата PrestaShop на странице заказа не возвращают деньги через dLocal Go. Возвраты, сделанные в панели dLocal Go, не регистрируются в PrestaShop как возвраты и обычно не добавляют заметку. При необходимости обновите заказ вручную.

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

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

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

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

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

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

Решение проблем

dLocal Go не появляется при оформлении заказа: проверьте, что лицензия активна, Enable/Disable включено и API-ключ и API-секрет выбранной Environment заполнены. Страница настроек показывает предупреждение, если их нет. В Payment > Preferences проверьте, что модуль разрешён для валюты корзины, страны покупателя и группы покупателя.

Платёж прошёл, но заказ не создан: dLocal Go не смог обратиться к адресу уведомления (брандмауэр, базовая аутентификация, нет публичного адреса), а покупатель не вернулся в магазин. Включите Debug log, посмотрите поле Log и проверьте платёж в панели dLocal Go. Как только придёт уведомление или покупатель нажмёт Check again, заказ будет создан.

Уведомление отвечает Missing signature или Invalid signature: API-ключ и секрет в настройках не принадлежат аккаунту, который отправил уведомление. Уведомления проверяются учётными данными среды платежа, поэтому платежи, начатые до переключения Environment, по-прежнему подтверждаются, пока учётные данные их среды остаются в настройках.

Уведомление отвечает Gateway not configured: учётные данные среды платежа не заполнены. Введите их; dLocal Go повторит уведомление.

Уведомление отвечает API verification failed: не удалось обратиться к API dLocal Go, чтобы прочитать платёж. dLocal Go повторит уведомление.

Уведомление отвечает Temporarily unavailable: заказ в этот же момент подтверждал другой запрос, или заказ не удалось создать (например, модуль отключён). dLocal Go повторит уведомление. Причина указана в журнале.

Уведомление отвечает Order not found: платёж не относится к корзине этого магазина, например, его создал другой сайт с той же учётной записью dLocal Go.

Покупатель видит This payment method is temporarily unavailable: dLocal Go отклонил API-ключ или секрет. Проверьте учётные данные выбранной среды.

Покупатель видит Payment gateway is not properly configured: учётные данные выбранной среды не заполнены.

Заказ в статусе dLocal payment on hold после оплаты: прочитайте заметки в блоке dLocal Go payment. Оплаченная сумма или валюта отличались от корзины, либо платёж пришёл после отмены заказа. Выполните заказ или верните платёж.

Возврат не проходит с сообщением об отсутствии учётных данных: платёж был совершён в другой среде, и её учётные данные не заполнены. Введите их и повторите попытку.

Для разработчиков: документация модуля перечисляет хуки actionWcpDlocalPaymentData и actionWcpDlocalCurrencyDecimals.

Удаление

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

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