VibeFox dLocal for OpenCart — Помощь

Требования

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

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

Учётная запись dLocal Go: вам понадобятся API-ключ и API-секрет вашей учётной записи dLocal Go со страницы Payment integration в личном кабинете dLocal Go: dashboard-sbx.dlocalgo.com для песочницы (sandbox), dashboard.dlocalgo.com для рабочего режима. Песочница и рабочий режим используют разные учётные данные. Расширение работает только с dLocal Go, но не с корпоративным API dLocal Payments.

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

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

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

Установка

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

OpenCart 3

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

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

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

4. Введите API-ключ и API-секрет для песочницы и, для реальных платежей, для рабочего режима. Выберите Environment (см. Настройка).

5. Включите Enable/Disable и нажмите Save. Совершите тестовый платёж в песочнице, затем переключите Environment на Production.

OpenCart 4

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

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

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

4. Введите лицензионный ключ и учётные данные dLocal Go и проверьте платёж, как в шагах 3–5 для OpenCart 3. Страница настроек и её поля одинаковы в обеих версиях. Отличаются только URL уведомлений (см. Notifications (IPN)).

В личном кабинете dLocal Go ничего настраивать не нужно: URL уведомлений и возврата передаются с каждым платежом и возвратом. Новая установка начинает работу с выключенным способом оплаты и выбранной песочницей.

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Payments > VibeFox dLocal Payment > Edit. Разделы перечислены слева; кнопка Save под списком сохраняет всю страницу. Пока не введены API-ключ и API-секрет выбранной среды, страница предупреждает, что способ оплаты скрыт при оформлении заказа, например: Введите API-ключ и секрет песочницы: до тех пор способ оплаты скрыт при оформлении заказа. Пока выбрана песочница и способ оплаты включён, отображается Режим песочницы активен: платежи имитируются, деньги не списываются. Без права изменять расширение страница показывает настройки, но не может их сохранить.

При сохранении поле Title не должно быть пустым и содержать не более 128 символов, Sort Order должен быть целым числом, Total — числом не меньше 0, а гео-зона и статусы заказов должны существовать. Иначе ничего не сохраняется, и страница показывает ошибку. Если способ оплаты включён без ключа и секрета выбранной среды, настройки сохраняются с предупреждением выше.

dLocal Go

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

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

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

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

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

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

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

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

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

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

Sandbox API Key: ваш API-ключ песочницы dLocal Go.

Sandbox API Secret: ваш API-секрет песочницы dLocal Go.

Production API Key: ваш рабочий API-ключ dLocal Go.

Production API Secret: ваш рабочий API-секрет dLocal Go.

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

Оплата

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

Auto-complete orders: присваивает оплаченным заказам статус Complete Order Status вместо Paid Order Status. По умолчанию: выключено.

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

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

Заказы

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

Paid Order Status: статус заказа после подтверждённого платежа. По умолчанию: В обработке.

Complete Order Status: статус заказа после подтверждённого платежа, когда включено Auto-complete orders. По умолчанию: Выполнен.

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

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

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

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

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

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

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

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

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

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

На шаге Payment Method покупатель выбирает способ оплаты (по умолчанию dLocal Go). На шаге Confirm Order покупатель видит ваше описание и примечание Вы будете перенаправлены на страницу оплаты dLocal Go. В режиме песочницы также отображается Режим песочницы: реальный платёж не производится. OpenCart создаёт заказ на этом шаге, по-прежнему без статуса. Когда покупатель нажимает Confirm Order, расширение создаёт платёж dLocal Go на сумму заказа в валюте заказа, с указанием страны, имени, e-mail и телефона покупателя, и отправляет покупателя на страницу оплаты dLocal Go. Там покупатель платит способом, доступным в его стране. На странице dLocal Go платёж отображается как Order # и номер заказа. На OpenCart 4 покупатель выбирает способ оплаты кнопкой Choose в блоке способа оплаты, в окне Payment method options, и нажимает Confirm Order внизу страницы оформления заказа. Если магазин не запрашивает адрес оплаты (поведение OpenCart 4 по умолчанию), используются страна адреса доставки и имя покупателя.

После оплаты покупатель возвращается в ваш магазин. Заказ отмечается оплаченным только после подтверждения dLocal Go: по подписанному уведомлению или серверным запросом к API dLocal Go, когда покупатель возвращается. Адрес возврата содержит случайный токен попытки оплаты. Затем заказ получает статус стандартным для OpenCart способом, с обычными письмами о заказе и обновлением остатков, а покупатель видит страницу успешного оформления заказа OpenCart с сообщением 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 подтверждает платёж. На OpenCart 4 браузер не передаёт сессию магазина, когда 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. На OpenCart 4 эти сообщения выводятся над страницей оформления заказа. Корзина сохраняется. Каждое нажатие Confirm Order создаёт новый платёж dLocal Go. OpenCart 3 создаёт новый заказ каждый раз, когда показывается шаг Confirm Order; OpenCart 4 оставляет один заказ на оформление и обновляет его, поэтому новый платёж относится к тому же заказу. Более старая ссылка на оплату по-прежнему может быть оплачена и подтверждает свой заказ. Перед началом нового платежа из dLocal Go запрашиваются открытые платежи того же заказа и той же сессии покупателя (последние 24 часа): если один из них оплачен, его заказ подтверждается, и покупатель переходит на страницу успеха без повторной оплаты.

OpenCart 4 хранит заказ в оформлении до показа страницы успеха. Если этот заказ тем временем был закрыт без оплаты (например, отменён или возвращён), Confirm Order или возврат из dLocal Go отправляет покупателя на оформление заказа с сообщением Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order., а следующий Confirm Order оплачивает новый заказ корзины.

Если dLocal Go не может начать платёж, покупатель остаётся на шаге Confirm Order с коротким сообщением, например 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. Техническая причина записывается в журнал.

Уведомления также работают, когда магазин находится в режиме обслуживания: OpenCart 3 пропускает запросы платёжных расширений, а на OpenCart 4 расширение добавляет стартовое действие (startup action), которое пропускает уведомления и возврат покупателя.

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

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

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

Нет статуса (отсутствующий заказ): покупатель был отправлен в dLocal Go и не оплатил, платёж был отклонён или истёк либо всё ещё ожидает в dLocal Go. В Sales > Orders такие заказы показываются только с фильтром Order Status, установленным в Missing Orders.

Paid Order Status (по умолчанию В обработке) или Complete Order Status (по умолчанию Выполнен): платёж подтверждён. Заказ получает Complete Order Status, когда включено Auto-complete orders. В примечании указаны среда и ID платежа dLocal.

On Hold (Review) Status (по умолчанию Ожидает оплаты): dLocal Go сообщил сумму или валюту, отличающиеся от суммы заказа, либо платёж поступил после отмены заказа. Примечание объясняет причину. Сверьте с личным кабинетом dLocal Go и выполните заказ или верните платёж.

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

Отклонённый, истёкший или отменённый платёж никогда не меняет заказ, который уже имеет статус. Если для уже оплаченного заказа поступает второй платёж, заказ не меняется. Примечание просит вас вернуть повторный платёж в личном кабинете dLocal Go. Такое же примечание добавляется к оплаченному заказу, когда та же корзина (та же сессия покупателя и то же содержимое корзины) была оплачена ещё раз с другим заказом, например во второй вкладке браузера; этот другой заказ статуса не получает.

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

Вкладка VibeFox dLocal Payment

В Sales > Orders откройте заказ, оплаченный через dLocal Go. Внизу страницы заказа, рядом с History и Additional, вкладка VibeFox dLocal Payment показывает Payment ID, Environment (песочница или рабочий режим), Status платежа, суммы Paid / refunded, форму возврата, историю возвратов и dLocal Go notes заказа. Вкладка показывается пользователям, имеющим доступ к расширению.

Возвраты

На вкладке VibeFox dLocal Payment введите Amount (подставляется сумма, ещё не возвращённая), при необходимости Reason (optional) и нажмите Refund via dLocal Go. Подтвердите вопрос Refund this amount through dLocal Go? This cannot be undone. Поддерживаются полные и частичные возвраты. Вам нужно право изменять расширение (задаётся в System > Users > User Groups). Возвраты выполняются в сумме и валюте, которые списал dLocal Go, поэтому после расхождения суммы или валюты можно вернуть не больше того, что покупатель фактически заплатил, а не сумму заказа. Возврат отправляется в среду, где был совершён платёж, с её учётными данными. Если dLocal Go не принимает возврат, вкладка показывает ошибку, и возврат не регистрируется. Принятый возврат добавляется в историю возвратов и примечания с ID возврата, статусом и причиной. Полный возврат переводит заказ в Refunded Status без уведомления покупателя и без возврата товаров на склад, как при ручной смене статуса. Частичный возврат статус не меняет. Возвраты доступны, когда dLocal Go подтвердил платёж.

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

Возвраты товаров в Sales > Returns не возвращают деньги через dLocal Go. Возвраты, сделанные в личном кабинете dLocal Go, не регистрируются в OpenCart как возвраты. При необходимости обновите заказ вручную.

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

Расширение работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox dLocal Payment — это первый блок в Extensions > Extensions > Payments > VibeFox dLocal Payment > Edit, над настройками. Вставьте ключ в License key и нажмите Activate. После этого блок показывает ключ в замаскированном виде, статус (например, дату, до которой действует лицензия, и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: opencart-payment-dlocal и ссылка 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.

Без активного ключа dLocal Go не показывается покупателям при оформлении заказа. Если платёж всё же начат, покупатель видит This payment method is not available. Please choose another one. Администратор, вошедший в административную часть в том же браузере, по-прежнему видит способ оплаты в магазине с пометкой (unlicensed — visible to admins only), поэтому вы можете настроить и протестировать расширение до покупки ключа. На OpenCart 4 этот предпросмотр недоступен: магазин не видит вход в административную часть, поэтому без активного ключа способ оплаты скрыт для всех. После однократного открытия страницы Edit на Dashboard административной части появляется напоминание. Закройте его кнопкой ×, чтобы скрыть на 7 дней. Существующие заказы не затрагиваются: уже начатые платежи по-прежнему подтверждаются, и возвраты работают.

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

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

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

Платёж прошёл, но заказ остался без статуса: dLocal Go не смог обратиться к URL уведомления (брандмауэр, базовая аутентификация или отсутствие публичного HTTPS-адреса), а покупатель не вернулся в магазин. Включите 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-ключ или API-секрет. Проверьте учётные данные выбранной среды.

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

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

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

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

Для разработчиков: расширение запускает события OpenCart dlocal_p_payment_data (запрос на оплату и заказ, до создания платежа) и dlocal_p_currency_decimals (количество десятичных знаков валюты).

Удаление

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

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

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