RU
EUR
Назад

VibeFox Khipu for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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

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

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

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

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

Установка

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

2. По окончании загрузки нажмите Configure или позже найдите VibeFox Khipu Gateway в списке модулей и нажмите Configure.

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

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

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

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

Настройки

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Khipu Gateway > Configure. У каждого раздела есть собственная кнопка Save, которая сохраняет всю страницу. Над полями страница предупреждает, если не заполнены Receiver ID, API key или Secret key (тогда Khipu не предлагается на этапе оформления заказа), и если валюта магазина по умолчанию не поддерживается Khipu.

Khipu

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

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

Description: текст под способом оплаты на этапе оформления заказа. По умолчанию: Pay by bank transfer with 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 saved secrets: отметьте API key или Secret key и нажмите Save, чтобы удалить его. Пустое поле сохраняет сохранённое значение.

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

Notification URL: Khipu подтверждает платежи, обращаясь к URL, который показан здесь. При включённых «красивых» URL он выглядит так: https://your-shop/module/wcp_khipu_gateway/webhook, возможно, с кодом языка. URL передаётся автоматически с каждым платежом, поэтому в аккаунте Khipu ничего настраивать не нужно, но URL должен быть доступен из интернета.

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

done: перевод подтверждён. Заказ создаётся после проверок Receiver ID, корзины и суммы.
done, reversed: платёж был отменён. Для неоплаченной корзины заказ не создаётся. Оплаченный заказ получает примечание, его статус не меняется.
pending or verifying: перевод ещё не окончательный. Модуль отвечает «retry later», и Khipu отправляет уведомление повторно.

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

Processing: заказ получает статус Payment accepted (по умолчанию).
Completed: заказ получает статус Delivered.

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

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

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

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

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

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

После оплаты покупатель возвращается в ваш магазин. Заказ отмечается как оплаченный только после подтверждения Khipu: по подписанному уведомлению или по запросу статуса к Khipu при возврате покупателя. Само возвращение никогда ничего не отмечает как оплаченное. Когда заказ создан, покупатель видит стандартную страницу подтверждения заказа. Если банк ещё проверяет перевод или Khipu недоступен, появляется страница Payment confirmation с текстом Khipu is confirming your bank transfer. Your order will be created 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. Корзина сохраняется. Новая попытка удаляет предыдущий неоплаченный платёж 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 не может создать платёж, покупатель остаётся на этапе оформления заказа с коротким сообщением, например 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. Подробности записываются в журнал.

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

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

Заказы

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

No order yet: покупатель был отправлен в Khipu и не оплатил, или Khipu ещё не подтвердил перевод. Существует только корзина.

Payment accepted or Delivered: Khipu подтвердил платёж. Статус следует за Status after payment. Платёж записывается с идентификатором платежа Khipu в качестве ID транзакции, а примечание показывает Khipu payment verified. Payment ID: с идентификатором платежа и суммой.

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

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

Блок оплаты Khipu

На странице заказа отображается блок Khipu payment с попытками оплаты Khipu по корзине заказа (дата, сумма, Khipu payment ID, статус Khipu и результат), предупреждение Manual review, пока заказ находится в статусе Khipu payment on hold, и Khipu notes заказа. Блок только для чтения.

Возвраты

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

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

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

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

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

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

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

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

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

Платёж прошёл, но заказ не создан: 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 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 created, retry later: заказ в этот момент подтверждался другим запросом, либо заказ не удалось создать (например, модуль отключён). Khipu отправит уведомление повторно. Причина указана в журнале.

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

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

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

Удаление

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

Khipu — товарный знак его владельца. Этот модуль не аффилирован с Khipu и не одобрен Khipu.