VibeFox Cashfree for PrestaShop — Допомога

Вимоги

PrestaShop: 8.0–9.x.

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

HTTPS: Cashfree надсилає вебхуки лише на URL-адреси https://. Без HTTPS платежі все одно підтверджуються, коли покупець повертається до магазину, але увімкніть HTTPS перед переходом у робочий режим.

Обліковий запис Cashfree: потрібні App ID і Secret Key вашого облікового запису Cashfree, окремо для тестового середовища (sandbox) і для робочого, а також вебхук у Cashfree Merchant Dashboard (див. Налаштування). Secret Key також використовується для перевірки вебхуків, тож окремого секрету для вебхука немає. Валюта кошика має бути увімкнена для вашого облікового запису Cashfree.

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

Встановлення

1. У back office перейдіть до Modules > Module Manager і натисніть Upload a module. Оберіть ZIP-файл модуля.

2. Коли завантаження завершиться, натисніть Configure або пізніше знайдіть VibeFox Cashfree Payments у списку модулів і натисніть Configure.

3. Введіть ваш ліцензійний ключ VibeFox у поле License key у блоці ліцензії вгорі сторінки Configure і натисніть Activate (див. Ліцензійний ключ).

4. Введіть Sandbox App ID і Sandbox Secret Key, додайте вебхук у Cashfree Merchant Dashboard (див. Налаштування), увімкніть Enable/Disable, натисніть Save і перевірте один платіж.

5. Коли все буде готово, введіть робочі App ID і Secret Key, вимкніть Sandbox Mode і натисніть Save.

Під час встановлення модуль створює статус замовлення Cashfree payment on hold. PrestaShop пропонує новий платіжний модуль для всіх валют, країн і груп клієнтів. Їх можна обмежити в Payment > Preferences.

Налаштування

Усі налаштування розміщені на сторінці модуля: Modules > Module Manager > VibeFox Cashfree Payments > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Над полями сторінка пояснює, що замовлення створюється лише після підтвердження платежу Cashfree. Коли спосіб оплати увімкнено, сторінка попереджає, якщо немає API-ключів обраного режиму (тоді спосіб оплати приховується на оформленні замовлення), і показує Sandbox mode is on: customers see a test checkout and no real money is charged. поки увімкнено режим sandbox. Якщо ви зберігаєте увімкнений спосіб оплати без ключів обраного режиму, попередження повідомить, що він залишатиметься прихованим на оформленні замовлення, доки ключі не буде заповнено.

Cashfree Payments

Enable/Disable: Enable Cashfree Payments вмикає або вимикає спосіб оплати. За замовчуванням: off.

Title: назва способу оплати, яку бачить покупець на оформленні замовлення. Вона також зберігається в замовленні як назва способу оплати. За замовчуванням: Cashfree Payments. Обов'язкове поле.

Description: текст, який відображається під способом оплати на оформленні замовлення. За замовчуванням: Pay securely via Card, UPI, Net Banking, Wallet via Cashfree.

Mode and API keys

App ID і Secret Key беріть у Cashfree Merchant Dashboard, у розділі Developers > API Keys. Тестові та робочі ключі відрізняються.

Sandbox Mode: використовує тестове середовище Cashfree (sandbox). Реальні кошти не списуються, а під способом оплати на оформленні замовлення відображається SANDBOX MODE - no real payments will be processed. За замовчуванням: on. Вимкніть для реальних платежів.

Sandbox App ID: App ID вашого тестового середовища Cashfree.

Sandbox Secret Key: Secret Key вашого тестового середовища Cashfree.

App ID: App ID вашого робочого середовища Cashfree.

Secret Key: Secret Key вашого робочого середовища Cashfree.

Збережені Secret Key більше ніколи не відображаються. Поле залишається порожнім і показує Saved — leave empty to keep it. Вводьте нове значення, лише якщо хочете його змінити.

Clear saved secrets: позначте Secret Key і натисніть Save, щоб видалити його. Порожнє поле зберігає збережене значення.

Платежі зберігають середовище, у якому були створені. Їхні вебхуки перевіряються, статус перевіряється, а повернення надсилаються з ключами цього середовища, тому тримайте ключі sandbox заповненими, доки платежі sandbox не буде завершено після переходу на робочий режим.

Webhook

Вебхук повідомляє вашому магазину, що платіж був здійснений, не вдався або був повернений. У Cashfree Merchant Dashboard перейдіть до Developers > Webhooks і додайте URL, який відображається в Webhook URL у цьому розділі, з подіями Payment і Refund. З «дружніми» URL він має такий вигляд: https://your-shop/module/wcp_cashfree_payment/webhook. Копіюйте URL точно так, як його показують налаштування. На магазині з HTTPS модуль також передає цей URL до Cashfree з кожним платежем. Якщо ваш магазин не використовує HTTPS, у цьому розділі з'явиться попередження.

Модуль обробляє ці події (вони також перелічені в цьому розділі):

PAYMENT_SUCCESS_WEBHOOK: платіж успішний. Замовлення створюється після перевірки суми та валюти.

PAYMENT_FAILED_WEBHOOK: платіж не вдався. Замовлення не створюється; покупець може оплатити знову.

PAYMENT_USER_DROPPED_WEBHOOK: покупець покинув оплату. Замовлення не створюється; покупець може оплатити знову.

REFUND_STATUS_WEBHOOK and AUTO_REFUND_STATUS_WEBHOOK: змінився статус повернення. Додається примітка з ID повернення, сумою та статусом, а в історії повернень відображається новий статус.

Cashfree підписує кожен вебхук вашим Secret Key. Вебхуки без дійсного підпису відхиляються. Вебхук має бути підписаний Secret Key того середовища, у якому було здійснено платіж, тож ключ sandbox ніколи не підтверджує реальний платіж. Підписані вебхуки для платежів, які не були розпочаті цим магазином (наприклад, іншим магазином в тому самому обліковому записі Cashfree), підтверджуються та ігноруються. Без вебхука замовлення створюється лише тоді, коли покупець повертається до магазину після оплати. Якщо покупець закрив браузер після оплати, замовлення може створити лише вебхук (або наступна спроба оплати того самого кошика).

Advanced

API Version: версія API Cashfree для використання.

v1 (2022-09-01): за замовчуванням.

v2 (2023-08-01): новіша версія API.

Order ID prefix: ID замовлень Cashfree формуються як префікс + ID кошика PrestaShop; нова спроба для того самого кошика отримує номер у кінці (наприклад, 123-2). Залиште поле порожнім, щоб використовувати автоматичний префікс цього магазину, який показано в описі поля. Для кожного магазину, підключеного до того самого облікового запису Cashfree, використовуйте окремий префікс. Дозволені лише літери, цифри, «_» і «-», до 20 символів. Інші символи видаляються під час збереження з попередженням.

Debug log: помилки завжди записуються. Коли опція увімкнена, виклики API Cashfree і вебхуки також записуються до logs/cashfree_p_debug.log.php у папці модуля. Файл не можна відкрити через веб. Ключі та дані покупців ніколи не записуються. За замовчуванням: off.

Log: показує розмір і останні записи журналу. Натисніть Clear log, щоб його очистити.

Delete Data on Uninstall: якщо увімкнено, видалення модуля вилучає налаштування Cashfree і журнал модуля. Замовлення, їхні транзакції та повернення Cashfree, а також статус замовлення Cashfree payment on hold завжди зберігаються, щоб існуючі замовлення продовжували працювати. За замовчуванням: off.

Оформлення замовлення

На етапі оплати покупець обирає спосіб оплати (за замовчуванням Cashfree Payments) і підтверджує вибір. Модуль створює замовлення Cashfree на суму кошика у валюті кошика та відкриває сторінку оплати, яка показує Redirecting to Cashfree for payment... і завантажує сторінку оплати Cashfree. Якщо вона не відкривається сама, покупець може натиснути Pay Now. На сторінці оплати Cashfree покупець платить будь-яким способом, увімкненим в обліковому записі Cashfree, наприклад карткою, через UPI, інтернет-банкінг або електронний гаманець. Електронна пошта та телефон для виставлення рахунку покупця передаються до Cashfree. На цьому етапі замовлення ще не існує.

Після оплати покупець повертається до вашого магазину. Замовлення позначається оплаченим лише після підтвердження Cashfree: підписаним вебхуком або серверним запитом до Cashfree, коли покупець повертається. Тоді замовлення створюється, і покупець бачить стандартну сторінку підтвердження замовлення. Повернення працює і в іншому браузері, наприклад коли покупець повертається з застосунку UPI. Якщо банк ще не підтвердив платіж, сторінка Payment confirmation показує Your payment is being processed by the bank. We will update the order as soon as Cashfree confirms it — please do not pay again. та кнопку Check again; вебхук створює замовлення, щойно банк підтверджує платіж.

Якщо платіж не вдався або покупець покинув сторінку Cashfree без оплати, він повертається на оформлення замовлення і бачить The Cashfree payment was not completed. Please try again or choose another payment method. Кошик зберігається. Відкритий платіж Cashfree повторно використовується, коли покупець намагається знову. Якщо сума кошика змінилася або сесія незабаром закінчиться, старе замовлення Cashfree закривається і створюється нове, щоб кошик не можна було оплатити двічі. Якщо кошик уже оплачено в Cashfree, але не записано, наступна спроба створює замовлення замість повторного списання.

Якщо Cashfree не може розпочати платіж, покупець залишається на оформленні замовлення і бачить We could not start the Cashfree payment. Please try again or choose another payment method. Технічна причина записується в журнал. Сума кошика нижча за мінімум Cashfree (1 одиниця валюти; 0,01 для BHD, JOD, KWD, OMR і 0,1 для TND) не може бути оплачена через Cashfree, і для такого кошика спосіб оплати не показується.

Вебхук працює, поки магазин перебуває в режимі обслуговування, і не блокується обмеженням за країнами вашого магазину.

Модуль приймає лише разові платежі на сторінці оплати Cashfree. Він не підтримує збережені картки, підписки чи регулярні платежі, окремі авторизацію та захоплення, віджет пропозицій Cashfree, оплату при отриманні (COD) або платіжні посилання через Cashfree, а також конвертацію валют: кошик списується у валюті кошика.

Замовлення та повернення

Order statuses

No order yet: покупця було відправлено до Cashfree, і він не оплатив, платіж не вдався або платіж ще очікує в банку. Існує лише кошик.

Payment accepted: платіж підтверджено. Платіж записується з ID платежу Cashfree як ID транзакції, а примітка показує ID транзакції та групу способу оплати (наприклад, upi або credit_card).

Cashfree payment on hold: Cashfree повідомив про оплачену суму або валюту, які відрізняються від суми кошика (наприклад, кошик було змінено в іншій вкладці після початку платежу). У примітці вказано очікувану та отриману суму й ID транзакції. Перевірте платіж у Cashfree Dashboard, а потім виконайте замовлення або поверніть платіж.

Refunded: платіж повністю повернено через модуль.

Платіж, що надійшов після скасування замовлення, все одно записується, і замовлення знову стає оплаченим, бо кошти було списано. Оплачене замовлення ніколи не повертається назад через пізніший невдалий платіж.

Cashfree payment block

На сторінці замовлення є блок Cashfree payment з ID транзакції, замовленням Cashfree, статусом платежу, сплаченою та поверненою сумами, позначкою Sandbox для платежів sandbox, історією повернень і Cashfree notes замовлення.

Refunds

У блоці Cashfree payment введіть суму (підставляється сума, яка ще не повернута), за бажанням причину, і натисніть Refund via Cashfree. Підтвердьте запитання Refund this amount through Cashfree? This cannot be undone. Підтримуються повні та часткові повернення. Вам потрібне право редагувати замовлення; доступ до сторінок модулів не потрібен. Повернення здійснюються в сумі та валюті, які списав Cashfree, тож після розбіжності суми можна повернути не більше того, що покупець фактично сплатив, а не суму замовлення. Повернення надсилається до оплаченого замовлення Cashfree, у тому середовищі (sandbox або робочому), у якому було здійснено платіж, тому ключі цього середовища мають бути заповнені. Якщо Cashfree не приймає повернення або повідомляє, що його скасовано чи відхилено, блок показує помилку, і повернення не записується. Розпочате повернення додається до історії повернень і приміток з його ID, сумою та статусом. Повне повернення переводить замовлення в статус Refunded; часткове повернення статус не змінює. Повернення доступні після того, як Cashfree підтвердив платіж.

Остаточний статус повернення надходить через вебхук повернення і додається до приміток. Модуль не створює кредитні нотатки. Стандартні кнопки повернення PrestaShop на сторінці замовлення не повертають кошти через Cashfree.

Ліцензійний ключ

Модуль працює з ліцензійним ключем VibeFox, отриманим на vibefox.net. Блок ліцензії License — VibeFox Cashfree Payments є першим блоком на сторінці Modules > Module Manager > VibeFox Cashfree Payments > Configure, над налаштуваннями. Введіть ключ у поле License key і натисніть Activate. Після цього блок показує ключ у замаскованому вигляді, статус (наприклад, дату, до якої ліцензія активна, і ваш домен) та кнопки Check now для повторної перевірки статусу, Change key для введення іншого ключа і Remove key для видалення ключа з цього магазину. Нижче розташовані рядок Product: presta-payment-cashfree і посилання 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.

Без активного ключа Cashfree не показується покупцям на оформленні замовлення. Якщо оплату все ж розпочато, покупець бачить This payment method is not available. Please choose another one. Вітрина PrestaShop не знає, що ви ввійшли в адмін-панель, тому спосіб оплати приховано й для вас: налаштувати модуль можна до купівлі ключа, але протестувати його на оформленні замовлення не можна. Нагадування з'являється в Modules > Module Manager на вкладці Alerts. Існуючі замовлення не зачіпаються: уже розпочаті платежі все одно підтверджуються, а повернення працюють.

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

Усунення несправностей

Cashfree не з'являється на оформленні замовлення: перевірте, що ліцензія активна, що Enable/Disable увімкнено і що для поточного режиму є ключі: Sandbox App ID і Sandbox Secret Key у режимі sandbox, App ID і Secret Key у робочому режимі. Сторінка налаштувань показує попередження, коли ключів немає. Спосіб оплати також приховується, якщо сума кошика нижча за мінімум Cashfree. У Payment > Preferences перевірте, чи дозволено модуль для валюти кошика, країни покупця та групи покупця.

Платіж пройшов, але замовлення не створено: вебхук не працює. Перевірте, що ваш магазин використовує HTTPS, що URL у Developers > Webhooks точно відповідає показаному в Webhook URL і що вибрано події Payment. Перевірте, що Secret Key у налаштуваннях належить до середовища, у якому було здійснено платіж. Cashfree Dashboard показує відповідь вашого магазину на кожен вебхук. Замовлення також створюється, коли покупець повертається до магазину після оплати, і під час наступної спроби оплати того самого кошика.

Вебхук відповідає Missing signature або Invalid signature: виклик не містив дійсного підпису Cashfree, або Secret Key у налаштуваннях не відповідає середовищу, у якому було здійснено платіж. Перевірте, що ключі sandbox і робочого режиму не переплутані.

Вебхук відповідає Ignored: вебхук підписано правильно, але він стосується платежу, який не був розпочатий цим магазином, наприклад іншим магазином у тому самому обліковому записі Cashfree. Дайте кожному магазину власний Order ID prefix.

Вебхук відповідає Busy, retry later: замовлення в цей момент створював інший запит, або замовлення не вдалося створити (наприклад, модуль вимкнено). Cashfree повторить вебхук. Увімкніть Debug log, щоб побачити причину.

Покупець бачить The Cashfree payment page could not be loaded: скрипт Cashfree не вдалося завантажити в браузері, наприклад через блокувальник. Покупець може знову натиснути Pay Now або Choose another payment method.

Покупець бачить We could not start the Cashfree payment: перегляньте поле Log на сторінці модуля. Типові причини — неправильні ключі для обраного режиму або валюта, не увімкнена для вашого облікового запису Cashfree.

Покупець бачить We could not verify the payment: посилання повернення не збіглося з кошиком. Якщо кошти було списано, вебхук все одно створить замовлення. Перевірте платіж у Cashfree Dashboard, перш ніж покупець оплатить знову.

Замовлення має статус Cashfree payment on hold після оплати: прочитайте примітки в блоці Cashfree payment (див. Order statuses), а потім виконайте замовлення або поверніть платіж.

Повернення не проходить з повідомленням про режим sandbox або робочий: платіж було здійснено в цьому середовищі, а його API-ключі не заповнені. Введіть їх і спробуйте знову.

Видалення

Перейдіть до Modules > Module Manager, відкрийте меню поруч із VibeFox Cashfree Payments і виберіть Uninstall. Ліцензійний ключ і статус ліцензії цього модуля завжди видаляються. Якщо Delete Data on Uninstall увімкнено, налаштування Cashfree і журнал буде видалено. Якщо вимкнено, усі налаштування зберігаються для подальшого повторного встановлення. Транзакції та повернення Cashfree і статус замовлення Cashfree payment on hold завжди зберігаються, тож замовлення, оплачені раніше, можна повертати й після повторного встановлення. Існуючі замовлення зберігають свої платіжні примітки та ID транзакцій.

Cashfree є товарним знаком його власника. Цей модуль не пов'язаний із Cashfree і не схвалений Cashfree.