VibeFox Khipu for OpenCart — Помощь

Требования

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

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

Валюта: чилийское песо (CLP), аргентинское песо (ARS) или перуанский соль (PEN). Валюта должна существовать в System > Localisation > Currencies. Khipu предлагается только тогда, когда покупатель платит в одной из этих валют; для других валют способ оплаты скрывается при оформлении заказа.

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

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

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

Установка

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

OpenCart 3

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

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

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

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

5. Включите Enable / Disable и нажмите Save. Для начала тестирования используйте ключи аккаунта разработчика Khipu, затем замените их ключами вашего боевого аккаунта.

OpenCart 4

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

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

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

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

После новой установки способ оплаты выключен.

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Payments > VibeFox Khipu Gateway > Edit. Разделы перечислены слева; кнопка Save под списком сохраняет всю страницу. Над настройками страница предупреждает, если отсутствуют Receiver ID, API key или secret key (тогда Khipu не предлагается при оформлении), и если валюта магазина по умолчанию не поддерживается Khipu (тогда Khipu предлагается только когда покупатель платит в CLP, ARS или PEN). Без права изменять расширение страница показывает настройки, но не может их сохранить.

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

Khipu

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

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

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

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

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

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

Аккаунт Khipu

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

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

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

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

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

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

Notification URL: Khipu подтверждает платежи, вызывая показанный здесь URL. На OpenCart 3 он выглядит так: https://your-store/index.php?route=extension/payment/wcp_khipu_gateway/webhook, на OpenCart 4 — так: https://your-store/index.php?route=extension/wcp_khipu_gateway/payment/wcp_khipu_gateway.webhook. Он формируется из адреса витрины вашей установки OpenCart. URL автоматически передаётся с каждым платежом, поэтому в аккаунте Khipu ничего настраивать не нужно, но URL должен быть доступен из интернета.

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

Status after payment: статус, который получает заказ, как только Khipu подтверждает платёж. Статус устанавливается сразу, одним изменением статуса.

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

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

Complete Order Status: статус после подтверждённого платежа, когда Status after payment — Completed. По умолчанию: Выполнен.

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

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

Debug log: записывает вызовы API и уведомления в файл wc_khp_debug.log.php в папке логов OpenCart (storage/logs). Файл нельзя открыть через браузер; при достижении 5 МБ он переименовывается в wc_khp_debug.old.log.php. Ошибки записываются всегда, даже когда переключатель выключен. Ключи и данные плательщика никогда не записываются. По умолчанию: выключено.

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

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

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

Export: Download JSON сохраняет настройки в файл JSON. Ключи API key и secret key не экспортируются.

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

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

На шаге Payment Method покупатель выбирает способ оплаты (по умолчанию Khipu). На шаге Confirm Order покупатель видит ваше описание над кнопкой подтверждения. OpenCart создаёт заказ на этом шаге, по-прежнему без статуса. Когда покупатель нажимает Confirm Order, расширение создаёт платёж Khipu на сумму заказа в валюте заказа и отправляет покупателя на страницу оплаты Khipu. В Khipu платёж отображается как Order # с номером заказа и названием магазина, вместе со списком товаров. E-mail покупателя передаётся в Khipu, если он корректен. На странице Khipu покупатель платит банковским переводом из своего банка.

На OpenCart 4 покупатель выбирает способ оплаты кнопкой Choose в блоке способа оплаты, в окне Payment method options, и нажимает Confirm Order внизу страницы оформления заказа.

После оплаты покупатель возвращается в ваш магазин. Заказ помечается оплаченным только после подтверждения Khipu: подписанным уведомлением или запросом статуса к Khipu, когда покупатель возвращается. Само возвращение никогда ничего не помечает как оплаченное. Затем заказ получает статус стандартным для OpenCart способом, с обычными письмами о заказе и обновлением остатков, а покупатель видит страницу успешного оформления заказа OpenCart. Если банк ещё проверяет перевод или Khipu недоступен, страница Payment confirmation показывает Khipu is confirming your bank transfer. Your order will be confirmed automatically as soon as Khipu confirms the payment, and you will receive an e-mail. с кнопками Check again и Back to checkout. Если последний платёж Khipu для заказа не удаётся сопоставить с ним (например, он относится к другому Receiver ID), покупатель возвращается к оформлению с сообщением We could not match this payment to an order. If you paid, please contact us.

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

OpenCart 4 сохраняет заказ в оформлении до показа страницы успеха. Если за это время заказ был закрыт без оплаты (например, вы его отменили), покупатель возвращается к оформлению с сообщением Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order. Если заказ уже оформлен, а корзина с тех пор изменилась, появляется сообщение Your previous order has already been placed. Your cart has changed since — please confirm the order again to pay for the current cart with a new order. В обоих случаях следующее нажатие Confirm Order оплачивает новый заказ из корзины.

Если Khipu не может создать платёж, покупатель остаётся на шаге Confirm Order с коротким сообщением над кнопкой, например 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. Подробности записываются в лог.

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

Расширение принимает только разовые платежи банковским переводом. Возвраты из OpenCart в Khipu не отправляются, подписок, сохранённых способов оплаты и предавторизаций нет. Неоплаченные платежи не связаны с резервированием товара на складе.

Заказы

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

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

Paid Order Status или Complete Order Status (по умолчанию В обработке или Выполнен): Khipu подтвердил платёж. Статус следует за Status after payment. Примечание показывает Khipu payment verified. Payment ID: с ID платежа и суммой.

On Hold (Review) Status (по умолчанию Ожидает оплаты): Khipu подтвердил платёж, сумма или валюта которого не совпадает с заказом, либо платёж поступил после отмены или отклонения заказа. Примечание объясняет это. Проверьте платёж в вашем аккаунте Khipu, затем завершите заказ или верните деньги покупателю. Если позже для того же заказа поступит платёж правильной суммы, заказ перейдёт в статус оплаченного, а покупатель получит уведомление по e-mail. Если платёж поступит после того, как заказ переведён в другой статус обработки, статус не меняется, а добавляется только примечание.

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

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

Вкладка VibeFox Khipu Gateway

В Sales > Orders откройте заказ, оплаченный через Khipu. Внизу страницы заказа, рядом с History и Additional, вкладка VibeFox Khipu Gateway показывает попытки платежа Khipu по заказу (дата, сумма, ID платежа Khipu, статус Khipu и результат), предупреждение Manual review, пока заказ находится в статусе проверки, и Khipu notes заказа. Вкладка только для чтения и показывается пользователям, которые имеют доступ к расширению.

Возвраты

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

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

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

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

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

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

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

Оплата прошла, но заказ остаётся без статуса: Khipu подтверждает перевод после того, как банк его проверил. Заказ получает статус, когда приходит уведомление от Khipu или когда покупатель нажимает Check again. Проверьте, что ваш магазин доступен из интернета по URL, показанному в Notification URL (без парольной защиты и без файрволла, блокирующего Khipu), и посмотрите поле Log на странице расширения.

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

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

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

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

Уведомление отвечает Busy, retry later или Order could not be updated, retry later: заказ в тот же момент подтверждал другой запрос, либо не удалось установить статус заказа. Khipu отправит уведомление повторно. Причина указана в логе.

Заказ в статусе проверки после оплаты: прочитайте примечания на вкладке VibeFox Khipu Gateway. Сумма или валюта не совпали с заказом, либо платёж поступил после отмены заказа.

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

Для разработчиков: расширение вызывает события OpenCart wc_khp_supported_currencies (чтобы добавить валюту, которую принимает ваш аккаунт Khipu, например EUR для Khipu Испания), wc_khp_currency_decimals и wc_khp_payment_data.

Удаление

Перейдите в Extensions > Extensions, выберите тип Payments и нажмите Uninstall (красная кнопка «−») рядом с VibeFox Khipu Gateway. Лицензионный ключ и статус лицензии этого расширения всегда удаляются. OpenCart всегда удаляет собственные настройки расширения: Enable / Disable, Sort Order, Geo Zone, Total и три статуса заказов, которые при повторной установке возвращаются к значениям по умолчанию. На OpenCart 4 также удаляются его событие и стартовое действие (startup action), которое пропускает уведомление и возврат покупателя в режиме обслуживания. Если Delete data on uninstall включено, удаляются остальные настройки шлюза (название, описание, Receiver ID, ключи, статус после оплаты, отладочный лог) и лог. Если выключено, они сохраняются для повторной установки. Записи попыток платежей Khipu всегда сохраняются, поэтому поздние уведомления по заказам, оплаченным ранее, обрабатываются и после повторной установки. Существующие заказы сохраняют свои примечания об оплате.

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

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