VibeFox dLocal for WooCommerce — Помощь

Требования

WordPress: 5.8 или новее.

WooCommerce: 7.0 или новее, установлен и активен.

PHP: 8.0 или новее. На более старой версии PHP или WordPress плагин не активируется.

Доступность сайта: ваш сайт должен быть доступен из интернета и использовать 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 сам решает, какие способы оплаты предложить для страны покупателя и валюты магазина.

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

Установка

1. В WordPress перейдите в Plugins > Add New > Upload Plugin, выберите ZIP-файл плагина и нажмите Install Now. Можно также загрузить папку wcp_dlocal_payment в /wp-content/plugins/ по FTP.

2. Нажмите Activate. WooCommerce должен быть активен.

3. Откройте настройки: WooCommerce > Settings > Payments > dLocal Go > Manage или нажмите Settings под названием плагина на странице «Плагины».

4. Введите лицензионный ключ VibeFox в блоке лицензии вверху страницы и нажмите Activate.

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

6. Включите Enable/Disable и сохраните. Проверьте платёж в тестовой среде, затем переключите Environment на Production.

Настройка

Все настройки находятся на одной странице: WooCommerce > Settings > Payments > dLocal Go. В заголовке страницы показано SANDBOX или PRODUCTION. Пока не введены API-ключ и секрет выбранной среды, страница предупреждает, что способ оплаты скрыт на странице оформления заказа. Пока выбрана тестовая среда и шлюз включён, на ней показано Sandbox mode is active: payments are simulated, no money is charged. В списке способов оплаты dLocal Go отмечен как требующий настройки, пока не заданы учётные данные, а в тестовой среде показывает Test mode.

Общие

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 (тестовая среда) или dashboard.dlocalgo.com (рабочая среда). Все поля учётных данных — поля пароля.

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

Sandbox (test): тестовые платежи с учётными данными тестовой среды (по умолчанию).

Production: реальные платежи с учётными данными рабочей среды.

Sandbox API Key: ваш API-ключ dLocal Go для тестовой среды.

Sandbox API Secret: ваш API-секрет dLocal Go для тестовой среды.

Production API Key: ваш API-ключ dLocal Go для рабочей среды.

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

Оплата

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

Auto-complete orders: Set paid orders to "Completed" instead of "Processing". Статус устанавливается сразу, с одним набором писем. По умолчанию: выключено.

Уведомления (IPN)

Уведомления сообщают магазину, что платёж или возврат изменился. Плагин передаёт URL уведомлений в dLocal Go с каждым платежом и возвратом, поэтому в панели dLocal Go ничего настраивать не нужно. В этом разделе настроек показаны оба URL:

Payment IPN: выглядит как https://your-site/wc-api/dlocal_p_ipn/ (на сайтах без ЧПУ — /?wc-api=dlocal_p_ipn).

Refund IPN: выглядит как https://your-site/wc-api/dlocal_p_refund_ipn/.

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

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

Debug log: Log API requests and notifications записывает подробности в WooCommerce > Status > Logs, источник wcp_dlocal_payment, без учётных данных API и персональных данных. Ошибки записываются всегда. По умолчанию: выключено.

Delete data on uninstall: Delete the gateway settings and logs when the plugin is deleted (order payment data is kept). По умолчанию: выключено.

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

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

После оплаты покупатель возвращается на страницу «Заказ получен» вашего магазина. Заказ отмечается оплаченным только после подтверждения от dLocal Go: по подписанному уведомлению или по серверному запросу к API dLocal Go, когда покупатель попадает на эту страницу.

Если покупатель ушёл со страницы dLocal Go без оплаты, он возвращается на страницу оформления заказа (или на страницу Pay for order) и видит 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 could not start the payment: с причиной от dLocal, и может выбрать другой способ. Так бывает и тогда, когда страна покупателя и валюта магазина не включены в вашей учётной записи dLocal Go. Техническая причина записывается в журнал.

Способ оплаты работает на классическом оформлении заказа, в блоке «Оформление заказа» и на странице Pay for order. Он совместим с высокопроизводительным хранилищем заказов WooCommerce (HPOS).

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

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

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

Pending payment: покупатель отправлен в dLocal Go и ещё не оплатил, или платёж ожидает в dLocal Go (например, ваучер для оплаты наличными ещё не оплачен). Каждая новая попытка оплаты записывается в заказ с её ID платежа dLocal, суммой и средой.

Processing or Completed: платёж подтверждён. Заказ получает статус «Обработка» (по умолчанию в WooCommerce) или «Выполнен», если включено Auto-complete orders. ID транзакции — это ID платежа dLocal.

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

Failed: последняя попытка оплаты отклонена или истекла. Покупатель может попробовать снова.

Cancelled: dLocal Go сообщил, что последняя попытка оплаты отменена.

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

Возвраты

Откройте заказ, нажмите Refund, введите сумму и нажмите Refund via dLocal Go. Полные и частичные возвраты поддерживаются для заказов, оплаченных через dLocal Go. Возврат отправляется в ту среду, в которой был сделан платёж, с учётными данными этой среды. Если dLocal Go не принимает возврат, WooCommerce показывает ошибку, и возврат не записывается. Принятый возврат добавляется в заметки к заказу с ID и статусом возврата.

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

Возвраты, сделанные в панели dLocal Go, не записываются как возвраты WooCommerce и обычно не добавляют заметку к заказу. При необходимости создайте ручной возврат в WooCommerce без Refund via dLocal Go.

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

Плагин работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии находится вверху страницы WooCommerce > Settings > Payments > dLocal Go. Вставьте ключ в License key и нажмите Activate. Блок показывает статус, например дату, до которой активна лицензия, и ваш домен. Check now — проверить статус снова, Change key — ввести другой ключ, Remove key — удалить ключ с этого сайта. Ссылка Manage licenses and domains in your account открывает вашу учётную запись vibefox.net.

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

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

Когда лицензия истекает, плагин продолжает работать, но для обновлений и поддержки нужно продление. Статус автоматически перепроверяется в фоновом режиме.

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

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

Платёж прошёл, но заказ остаётся «В ожидании оплаты»: dLocal Go не смог обратиться к URL уведомлений (файрвол, режим обслуживания, базовая аутентификация), а покупатель не вернулся на страницу «Заказ получен». Проверьте WooCommerce > Status > Logs, источник wcp_dlocal_payment, и платёж в панели dLocal Go. Как только придёт уведомление или покупатель откроет страницу «Заказ получен», заказ обновится.

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

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

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

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

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

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

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

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

Для разработчиков: в документации плагина перечислены фильтры dlocal_p_payment_data, dlocal_p_currency_decimals и dlocal_p_icon.

Удаление

При деактивации плагина все данные сохраняются. Чтобы удалить его, деактивируйте и удалите его на странице Plugins. Лицензионный ключ и статус лицензии этого плагина удаляются всегда. Настройки шлюза и журналы удаляются, только если было включено Delete data on uninstall. Иначе они остаются для последующей переустановки. Существующие заказы сохраняют свои заметки об оплате и ID транзакций.

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