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

Вимоги

PrestaShop: 8.0–9.x.

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

HTTPS: ваш магазин має бути доступним з інтернету через HTTPS, щоб Cardcom міг надіслати сповіщення про оплату.

Валюта: валюта кошика має бути ILS, USD, EUR або GBP. Для будь-якої іншої валюти спосіб оплати приховується під час оформлення замовлення.

Обліковий запис Cardcom: для реальних платежів потрібен обліковий запис мерчанта Cardcom з номером терміналу, іменем користувача API та паролем API. Для платежів потрібні лише номер терміналу та ім'я користувача API. Пароль API використовується лише для повернень з PrestaShop. Тестовий режим працює без облікового запису Cardcom.

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

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

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

2. Після завершення завантаження натисніть Configure або пізніше знайдіть VibeFox Cardcom Payment Gateway у списку модулів і натисніть Configure.

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

4. Увімкніть Enable/Disable, залиште Test Mode увімкненим і натисніть Save. Зробіть тестове замовлення карткою 4580 0000 0000 0000, із будь-якою майбутньою датою закінчення терміну дії та CVV 123.

5. Для реальних платежів вимкніть Test Mode, введіть Terminal Number, API Username і API Password, отримані від Cardcom, і натисніть Save.

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

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

Усі налаштування розміщені на сторінці модуля: Modules > Module Manager > VibeFox Cardcom Payment Gateway > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Над полями сторінка показує попередження, доки ввімкнено тестовий режим. У робочому режимі вона попереджає, якщо немає номера терміналу або імені користувача API (тоді Cardcom приховується під час оформлення замовлення), якщо в полях робочого режиму стоїть публічний тестовий термінал 1000 / CardTest1994 (тоді Cardcom також приховується, адже реальні гроші не списувалися б), і нагадує, що без пароля API повернення з PrestaShop неможливі. Вона також попереджає, якщо валюта за замовчуванням вашого магазину не підтримується. Коли ви зберігаєте робочий режим з відсутніми або тестовими обліковими даними, з'являється повідомлення про помилку: шлюз залишається прихованим під час оформлення замовлення, доки ви не введете власні номер терміналу та ім'я користувача API.

Cardcom

Enable/Disable: Enable Cardcom Payment Gateway вмикає або вимикає спосіб оплати. За замовчуванням: вимкнено.

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

Description: текст, що відображається під способом оплати під час оформлення замовлення. За замовчуванням: Pay securely with your credit card via Cardcom.

Тестовий режим

Тестовий режим використовує публічний тестовий термінал Cardcom 1000 (користувач API CardTest1994). Реальні гроші не списуються, обліковий запис Cardcom не потрібен. Тестова картка: 4580 0000 0000 0000, будь-яка майбутня дата закінчення терміну дії, CVV 123. У тестовому режимі під час оформлення замовлення також відображається рядок із цією тестовою карткою.

Test Mode: вмикає тестовий режим (термінал 1000, реальні гроші не списуються). За замовчуванням: увімкнено. Вимкніть його, щоб приймати реальні платежі з робочими обліковими даними нижче. Повернення завжди надсилаються з обліковими даними того режиму, в якому було оплачено замовлення.

Робочі облікові дані

Номер терміналу, ім'я користувача API та пароль API надає Cardcom разом з вашим обліковим записом мерчанта: у панелі Cardcom у розділі налаштувань API або через службу підтримки Cardcom. Ці поля використовуються лише в робочому режимі.

Terminal Number: ваш номер терміналу Cardcom. Він має містити лише цифри. Якщо ви введете щось інше, з'явиться помилка і збережеться попереднє значення.

API Username: ваше ім'я користувача API Cardcom (ApiName) для цього терміналу. Пробіли видаляються під час збереження.

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

Clear the saved API password: позначте прапорець і натисніть Save, щоб видалити пароль. Порожнє поле зберігає збережене значення.

Платіжна сторінка

Notification URL: Cardcom надсилає сповіщення про оплату (IndicatorUrl) на цю адресу. З увімкненими зрозумілими URL вона виглядає так: https://your-shop/module/wcp_cardcom_payment_gateway/webhook, можливо, з кодом мови, наприклад /en/. Адреса автоматично передається в Cardcom з кожним платежем разом з ідентифікатором кошика, тож у Cardcom нічого налаштовувати не потрібно. Вона має бути доступною з інтернету через HTTPS.

Operation: що робить Cardcom на платіжній сторінці.

Max Installments: максимальна кількість частин (платежів), яку покупець може обрати на сторінці Cardcom, від 1 до 36. 1 означає без оплати частинами. За замовчуванням: 1.

Success Order Status: статус замовлення після підтвердженої оплати. Замовлення створюється одразу з цим статусом.

Платежі, які не відповідають замовленню, завжди переходять у статус Cardcom payment on hold.

Додатково

Debug log: записує запити до API та сповіщення в logs/cardcom_p_debug.log.php у папці модуля. Файл не можна відкрити через веб. Помилки завжди записуються. Облікові дані, токени карток і дані власника картки ніколи не записуються. За замовчуванням: вимкнено.

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

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

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

На етапі оплати покупець обирає спосіб оплати (за замовчуванням Credit Card (Cardcom)) і бачить примітку You will be redirected to the secure Cardcom payment page. Після підтвердження модуль створює платіжну сторінку Cardcom для суми кошика у валюті кошика і надсилає туди покупця. На цьому етапі замовлення ще не існує. Сторінка відкривається івритом, якщо мова покупця — іврит, інакше англійською. Товари з кошика передаються в Cardcom як назва товару. Покупець вводить дані картки і, якщо оплата частинами дозволена, обирає кількість платежів.

Після оплати покупець повертається до вашого магазину. Замовлення позначається оплаченим лише після підтвердження Cardcom. Cardcom викликає адресу сповіщень, і модуль бере з цього виклику лише код платіжної сторінки. Він перевіряє, що цей код був виданий вашим магазином для цього кошика, а потім запитує у Cardcom фактичний результат від сервера до сервера. Якщо сповіщення запізнилося, та сама перевірка виконується, коли покупець повертається. Тоді замовлення створюється, і покупець бачить стандартну сторінку підтвердження замовлення з написом Your payment with Cardcom has been received. Якщо Cardcom ще не підтвердив оплату, коли покупець повертається, сторінка Payment confirmation показує Your payment is being confirmed by Cardcom. You will receive an e-mail as soon as it is confirmed. з кнопкою Check again; сповіщення створює замовлення, щойно воно надходить.

Якщо оплата не завершена або Cardcom її відхилив, покупець повертається до оформлення замовлення і бачить The card payment was not completed. Please try again or choose a different payment method. Замовлення не створюється, кошик зберігається. Покупець може спробувати знову: кожна спроба отримує нову платіжну сторінку Cardcom. Оплата, зроблена на попередній платіжній сторінці того самого кошика, все одно розпізнається, а відхилення на старій сторінці не впливає на нову спробу.

Якщо Cardcom не може відкрити платіжну сторінку, покупець залишається на оформленні замовлення з коротким повідомленням, наприклад Could not connect to Cardcom. Please try again in a moment., або з повідомленням, що Cardcom не зміг відкрити платіжну сторінку, разом із кодом Cardcom, і може обрати інший спосіб оплати.

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

Модуль приймає оплату карткою лише на платіжній сторінці Cardcom. Він не підтримує збережені картки чи оплату в один клік, підписки, не списує збережені токени, не має налаштувань рахунків чи чеків Cardcom, не підтримує Bit, Apple Pay, Google Pay або PayPal через Cardcom, режим iframe та транзакції з відкладеним захопленням.

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

Статуси замовлення

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

Payment accepted, Delivered or Cardcom payment on hold: оплату підтверджено. Статус відповідає Success Order Status. Платіж фіксується з номером операції (deal) Cardcom як ідентифікатор транзакції. Приватне повідомлення в замовленні показує транзакцію Cardcom і, якщо Cardcom їх передає, останні чотири цифри картки, номер рахунку та кількість частин. Тестові платежі позначаються як Test mode — no real money was charged.

Cardcom payment on hold after payment: Cardcom підтвердив платіж, який не відповідає замовленню, наприклад кошик було змінено після відкриття платіжної сторінки, або списано іншу суму чи валюту. Повідомлення це пояснює, а блок Cardcom показує його в розділі Needs review. Платіж фіксується на суму, яку списав Cardcom, якщо валюта збігається з валютою замовлення. Порівняйте платіж у панелі Cardcom із замовленням, а потім виконайте замовлення або поверніть платіж.

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

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

Блок оплати Cardcom

На сторінці замовлення відображається блок Cardcom payment з транзакцією, кодом платіжної сторінки, статусом, карткою, частинами, рахунком, токеном картки (за Charge + Save token), списаною сумою, сумою замовлення та сумою повернення, позначкою Test mode для тестових платежів та історією повернень.

Повернення коштів

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

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

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

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

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

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

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

Cardcom не з'являється під час оформлення замовлення: перевірте, що ліцензія активна, Enable/Disable увімкнено і валюта кошика — ILS, USD, EUR або GBP. У робочому режимі перевірте, що Terminal Number і API Username заповнені вашими власними обліковими даними, а не тестовим терміналом 1000 / CardTest1994. Сторінка налаштувань показує попередження, якщо чогось бракує. У розділі Payment > Preferences перевірте, що модуль дозволений для валюти кошика, країни покупця та групи покупця.

Оплата пройшла, але замовлення не створено: Cardcom не зміг достукатися до вашого магазину, наприклад через брандмауер, захист паролем або локальний сайт для розробки. Адреса сповіщень має бути доступною з інтернету через HTTPS. Замовлення також створюється, коли покупець повертається до магазину після оплати. Увімкніть Debug log і перегляньте поле Log на сторінці модуля.

Сповіщення відповідає Missing or invalid lowprofilecode or Unknown lowprofilecode for this order: виклик не містив коду платіжної сторінки, виданого вашим магазином для цього кошика. Нічого не змінюється.

Сповіщення відповідає Gateway not configured or Indicator check failed: бракує облікових даних режиму, в якому створено платіжну сторінку, або Cardcom не вдалося зв'язатися для перевірки. Нічого не змінюється; оплата перевіряється знову, коли покупець повертається до магазину.

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

Сповіщення відповідає ReturnValue mismatch or Terminal mismatch: Cardcom повідомив про платіж для іншого кошика або іншого терміналу. Нічого не змінюється. Перевірте, що Terminal Number — це термінал вашого облікового запису.

Покупець бачить Payment error: this currency is not supported by Cardcom.: валюта кошика — не ILS, USD, EUR або GBP.

Покупець бачить Card payment is temporarily unavailable. Please choose another payment method.: увімкнено робочий режим, але номер терміналу або ім'я користувача API не заповнено, або в полях робочого режиму стоїть публічний тестовий термінал.

Покупець бачить помилку під час вибору Cardcom: увімкніть Debug log і перегляньте поле Log. Там записуються проблеми з'єднання та коди помилок Cardcom.

Замовлення має статус Cardcom payment on hold after payment: прочитайте повідомлення в замовленні або Needs review у блоці Cardcom payment. Сплачена сума або валюта відрізнялися від замовлення. Виконайте замовлення або поверніть платіж.

Повернення не виконується з помилкою API username and API password are required for refunds: введіть API Password (і API Username) у налаштуваннях і спробуйте знову.

Повернення не виконується з помилкою Could not connect to Cardcom: перед повторною спробою перевірте панель Cardcom, адже повернення могло бути виконано, а могло й ні.

Для розробників у README описано хук actionCardcomSupportedCurrencies, який розширює список валют (додавайте лише валюти, увімкнені на вашому терміналі Cardcom), і actionCardcomLowProfileParams, який змінює параметри платіжної сторінки.

Видалення

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

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