VibeFox Khipu for WooCommerce — Помощь

Требования

WordPress: версия 6.0 или выше.

WooCommerce: версия 8.0 или выше, установлен и активен. Без WooCommerce плагин откажется активироваться.

PHP: версия 8.0 или выше.

Валюта магазина: чилийское песо (CLP), аргентинское песо (ARS) или перуанский соль (PEN). Способ оплаты скрывается при оформлении заказа, если магазин или заказ на странице Pay for order использует другую валюту.

Аккаунт Khipu: вам понадобятся Receiver ID («Id de cobrador»), API-ключ и секретный ключ («llave») вашего аккаунта Khipu для приёма платежей. Вы найдёте их в своём аккаунте Khipu в профиле продавца (khipu.com/merchant/profile). Все три обязательны: без секретного ключа ни один платёж не может быть подтверждён.

Доступный сайт: Khipu подтверждает платежи, обращаясь к вашему магазину, поэтому сайт должен быть доступен из интернета (без режима обслуживания, базовой аутентификации или блокировки Khipu в файрволе).

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

Установка

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

2. Нажмите Activate.

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

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

5. Введите Receiver ID, API key и Secret key вашего аккаунта Khipu для приёма платежей (см. раздел «Настройка»).

6. Включите Enable / Disable и сохраните. Чтобы сначала протестировать, используйте ключи тестового аккаунта разработчика Khipu, а затем замените их ключами вашего рабочего аккаунта.

Настройка

Все настройки находятся на одной странице: WooCommerce > Settings > Payments > Khipu. Над полями страница предупреждает, если не указан Receiver ID, API-ключ или секретный ключ (в этом случае Khipu не предлагается при оформлении заказа), а также если валюта магазина не поддерживается. В списке способов оплаты Khipu помечен как требующий настройки, пока не введены все три ключа.

Общие

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

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

Description: текст, отображаемый под способом оплаты при оформлении заказа. По умолчанию: Pay by bank transfer with Khipu.

Аккаунт Khipu

Скопируйте Receiver ID, API-ключ и секретный ключ из вашего аккаунта Khipu для приёма платежей (khipu.com/merchant/profile). У Khipu нет отдельного тестового сервера, и в плагине нет переключателя тестового режима. Для тестирования используйте ключи аккаунта разработчика («desarrollo»): оплата проходит через тестовый банк DemoBank, и реальные деньги не переводятся. При запуске переключитесь на ключи вашего рабочего аккаунта для приёма платежей.

Receiver ID: идентификатор получателя («cobrador») в Khipu. Платежи с других аккаунтов Khipu отклоняются.

API key: используется для создания платежей и для проверки каждого платежа в Khipu.

Secret key: используется для проверки подписи (HMAC-SHA256) уведомлений Khipu о платежах. Без него ни один платёж не может быть подтверждён.

Уведомления о платежах

Khipu подтверждает платежи, обращаясь к URL уведомлений, который показан в этом разделе настроек. Он выглядит так: https://your-site/wc-api/webhook_wc_khipu/. URL передаётся автоматически с каждым платежом, поэтому в вашем аккаунте Khipu ничего настраивать не нужно, но URL должен быть доступен из интернета.

Каждое уведомление должно содержать корректную подпись, созданную с помощью вашего Secret key. Уведомления без корректной подписи отклоняются. Затем плагин запрашивает у Khipu статус платежа и действует по данным, которые сообщает Khipu:

Status after payment: статус заказа после того, как Khipu подтвердит оплату. Статус устанавливается сразу, с одним изменением статуса и одним набором писем.

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

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

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. Данные заказов (ID платежей Khipu в заказах) сохраняются всегда. По умолчанию: выключено.

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

Покупатель выбирает способ оплаты (по умолчанию Khipu) и оформляет заказ. Плагин создаёт платёж Khipu на сумму заказа в валюте заказа, с номером заказа, названием магазина и заказанными товарами, и отправляет покупателя на страницу оплаты Khipu. Адрес электронной почты для выставления счёта передаётся в Khipu, если он корректен. На странице Khipu покупатель оплачивает банковским переводом из своего банка и выбирает там тип перевода из предложенных Khipu.

После оплаты покупатель возвращается на страницу полученного заказа вашего магазина. Заказ помечается как оплаченный только после того, как Khipu подтвердит перевод: с помощью подписанного уведомления или запроса статуса в Khipu, когда покупатель открывает страницу полученного заказа. Сам возврат на сайт никогда не помечает заказ как оплаченный. Пока перевод не подтверждён, страница показывает Khipu is confirming your bank transfer. Your order will be updated automatically as soon as Khipu confirms the payment, and you will receive an e-mail.

Если покупатель покидает страницу Khipu, не оплатив, он попадает на страницу Pay for order с сообщением The Khipu payment was not completed. You can try again or choose another payment method. Новая попытка удаляет предыдущий неоплаченный платёж Khipu, поэтому по старой ссылке оплатить уже нельзя. Если Khipu уже получил предыдущий платёж, заказ завершается и новый платёж не создаётся. Если предыдущий перевод всё ещё проверяется, покупатель видит Your previous Khipu payment for this order is still being verified by the bank. Please wait a few minutes before paying again.

При включённом управлении запасами платёж Khipu истекает вместе со временем Hold stock (minutes) в WooCommerce, поэтому покупатель не может оплатить уже отменённый заказ.

Если Khipu не может создать платёж, покупатель видит короткое сообщение, например Khipu could not create the payment for this order. Please check your billing details and try again, or contact the store. или Khipu is temporarily unavailable. Please try again in a few minutes. Подробности записываются в лог.

Способ оплаты работает в классическом оформлении заказа, в блоке оформления заказа и на странице Pay for order. Он совместим с WooCommerce High-Performance Order Storage (HPOS).

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

Заказы

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

Pending payment: покупатель был отправлен в Khipu и ещё не оплатил, или Khipu ещё не подтвердил перевод. В заметке к заказу указан ID платежа Khipu.

Processing или Completed: Khipu подтвердил платёж. Статус соответствует настройке Status after payment. В заметке к заказу указан ID платежа Khipu, и ID транзакции — это ID платежа Khipu.

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

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

Возвраты

Возвраты не отправляются в Khipu из WooCommerce. Верните деньги покупателю из своего аккаунта Khipu или банковским переводом, а затем вручную зафиксируйте возврат в WooCommerce.

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

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

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

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

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

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

Khipu не появляется при оформлении заказа: проверьте, что лицензия активна, Enable / Disable включено и указаны Receiver ID, API key и Secret key. Валюта магазина должна быть CLP, ARS или PEN. Страница настроек показывает предупреждение, если чего-то не хватает.

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

Уведомление отвечает Secret key not configured: поле Secret key пустое. Введите его. Khipu отправит уведомление повторно.

Уведомление отвечает Invalid signature, Missing signature или Malformed signature: Secret key не принадлежит тому аккаунту для приёма платежей, ключи которого вы используете, либо запрос пришёл не из Khipu.

Уведомление отвечает Payment does not belong to this order: платёж был сделан на другой Receiver ID или по другому заказу. Проверьте Receiver ID.

Уведомление отвечает Payment not final yet или Verification unavailable: перевод всё ещё проверяется или не удалось связаться с Khipu. Khipu отправит уведомление повторно.

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

Покупатель видит «Khipu payments are not available right now»: API-ключ отсутствует или неверен. Проверьте ключи в своём аккаунте Khipu.

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

Если ваш аккаунт Khipu принимает другую валюту, например EUR для Khipu Spain, разработчики могут добавить её с помощью фильтра wc_khp_supported_currencies.

Удаление

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

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