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

Вимоги

PrestaShop: 8.0–9.x.

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

Валюта: валюта кошика має бути MXN або USD. Для інших валют спосіб оплати приховується.

Обліковий запис Conekta: потрібні приватні API-ключі вашого облікового запису Conekta (тестовий і робочий) та вебхук у панелі Conekta (див. розділ Налаштування). Використовуються лише приватні ключі. Публічний ключ не потрібен, оскільки оплата відбувається на платіжній сторінці Conekta.

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

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

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

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

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

4. Введіть тестовий і робочий приватні ключі, оберіть режим і додайте вебхук у панелі Conekta (див. розділ Налаштування).

5. Увімкніть Enable / Disable і натисніть Save. Перевірте оплату в тестовому режимі, потім вимкніть Test mode.

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

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

Усі параметри розташовані на сторінці модуля: Modules > Module Manager > VibeFox Conekta Gateway > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Над полями сторінка попереджає, якщо Conekta увімкнено, але приватний ключ поточного режиму порожній (тоді спосіб оплати приховано на оформленні замовлення), і якщо валюта магазину за замовчуванням не MXN і не USD. Поки тестовий режим увімкнено, вона показує Тестовий режим увімкнено: платежі імітуються з тестовим приватним ключем. Якщо ви зберігаєте увімкнений шлюз без ключа поточного режиму, попередження просить його ввести.

Conekta

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

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

Description: текст, що відображається під способом оплати на оформленні замовлення. За замовчуванням: Pay securely with card, OXXO cash or SPEI transfer. You will be redirected to Conekta to complete your payment.

Payment methods: способи, що пропонуються на платіжній сторінці Conekta. За замовчуванням: card, cash and bank transfer. Готівка, SPEI та BNPL доступні лише для замовлень у MXN (замовлення в USD приймають лише картки) і мають бути увімкнені у вашому обліковому записі Conekta. Якщо нічого не вибрано, використовується картка, і сторінка попереджає про це під час збереження.

Credit / debit card: оплата карткою.

Cash (OXXO and other stores): покупець отримує референс і сплачує готівкою в магазині.

Bank transfer (SPEI): покупець отримує референс і сплачує банківським переказом.

Buy now, pay later (BNPL): оплата через варіант BNPL, якщо його увімкнено у вашому обліковому записі Conekta.

API-ключі

Скопіюйте приватні ключі з панелі Conekta в розділі Developers > API keys. Тестові та робочі ключі відрізняються.

Test mode: використовує тестовий приватний ключ. Реальні кошти не списуються, а під способом оплати на оформленні замовлення відображається значок TEST MODE із повідомленням Реальні списання не будуть проводитися. Повернення коштів завжди використовують ключ того режиму, в якому було здійснено платіж. За замовчуванням: увімкнено.

Test private key: приватний API-ключ тестового режиму вашого облікового запису Conekta.

Live private key: приватний API-ключ робочого режиму вашого облікового запису Conekta. Тримайте його в таємниці.

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

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

Кожне замовлення Conekta пам'ятає свій режим: повідомлення та повернення використовують відповідний ключ. Тримайте обидва ключі заповненими, доки відкриті старі тестові замовлення.

Webhook

Вебхук повідомляє ваш магазин про платежі, наприклад про платежі OXXO або SPEI, здійснені після того, як покупець залишив сторінку Conekta. У панелі Conekta перейдіть до Developers > Webhooks і додайте URL, який показано в полі Webhook розділу API keys, окремо для тестового і для робочого режиму. З дружніми URL він має такий вигляд: https://your-shop/module/wcp_conekta_gateway/webhook, можливо, з кодом мови, наприклад /en/. Копіюйте URL точно так, як його показують налаштування.

Оберіть ці події (вони також перелічені в налаштуваннях):

order.paid: замовлення оплачено.

order.pending_payment: замовлення очікує на оплату, наприклад після видачі референсу OXXO або SPEI.

order.declined: платіж відхилено.

order.expired: термін дії сторінки оплати або платіжного референсу минув.

order.canceled: замовлення Conekta скасовано.

order.refunded: платіж повернено, наприклад у панелі Conekta.

order.charged_back: покупець оскаржив платіж (чарджбек); модуль додає примітку до замовлення.

Тіло вебхука лише повідомляє модулю, яке замовлення Conekta змінилося. Кожне повідомлення перевіряється повторним читанням замовлення через API Conekta з приватним ключем його режиму; заголовок підпису Digest вебхука не використовується. Повідомлення про замовлення Conekta, які не були створені цим магазином для цього кошика, підтверджуються і ігноруються. Без вебхука замовлення створюється лише тоді, коли покупець повертається до магазину після оплати, або під час наступної спроби оплати того самого кошика.

Додатково

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

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

Delete data on uninstall: якщо увімкнено, видалення модуля вилучає налаштування та журнал. Транзакції й повернення Conekta, статуси замовлень і самі замовлення завжди зберігаються, тож старі замовлення можна буде підтвердити та повернути після повторного встановлення. За замовчуванням: вимкнено.

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

На етапі оплати покупець обирає спосіб оплати (за замовчуванням Conekta) і підтверджує вибір. Модуль створює замовлення Conekta на суму кошика у валюті кошика, з товарами, подарунковим пакуванням, знижками, податком і доставкою, і надсилає покупця на платіжну сторінку Conekta. На сторінці Conekta платіж відображається як Order # і номер кошика. Там покупець сплачує одним із дозволених способів. На цьому етапі замовлення ще не існує.

Після оплати покупець повертається до вашого магазину. Замовлення позначається оплаченим лише після того, як Conekta його підтвердить: модуль читає замовлення через API Conekta, коли надходить вебхук, і коли покупець повертається. Тоді замовлення створюється, і покупець бачить стандартну сторінку підтвердження замовлення з повідомленням Ваш платіж через Conekta отримано. Якщо покупець обрав OXXO або SPEI і отримав платіжний референс, замовлення створюється у статусі Awaiting Conekta payment, а сторінка показує Ваш платіжний референс Conekta видано. Замовлення буде підтверджено, щойно надійде платіж. Якщо референс згодом прострочиться, замовлення скасовується, а на його сторінці підтвердження з'являється повідомлення Ваш платіж через Conekta не було завершено. Будь ласка, зв'яжіться з нами щодо цього замовлення.

Якщо оплату ще не можна підтвердити, коли покупець повертається, відкривається сторінка Підтвердження оплати з текстом Ми підтверджуємо вашу оплату через Conekta. Замовлення буде оновлено автоматично — будь ласка, не оплачуйте повторно. та кнопка Check again. Вебхук створює замовлення, щойно його отримує.

Якщо платіж відхилено, замовлення не створюється, а покупець повертається до оформлення замовлення з повідомленням Платіж через Conekta не було завершено. Спробуйте ще раз або оберіть інший спосіб оплати. Якщо термін дії оплати минув або її скасовано, з'являється повідомлення Термін платежу через Conekta минув або платіж скасовано. Спробуйте ще раз. Кошик зберігається. Коли покупець платить знову, відкрита платіжна сторінка Conekta на ту саму суму використовується повторно; інакше попередня скасовується в Conekta перед створенням нової, тож старе посилання не можна оплатити двічі. Якщо попередню сторінку вже було оплачено, створюється замовлення, а повторного списання не відбувається.

Якщо Conekta не може розпочати оплату, покупець залишається на оформленні замовлення з коротким повідомленням, наприклад Не вдалося розпочати оплату. Спробуйте ще раз за хвилину або оберіть інший спосіб оплати. Повідомлення перевірки від Conekta, наприклад про мінімальну суму, показуються так, як їх надсилає Conekta. Технічна причина записується в журнал.

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

Модуль приймає платежі лише на сторінці Conekta. На сторінці оформлення замовлення немає форми картки, збережених карток, підписок, попередньої авторизації та захоплення, а також щомісячного розстрочення (MSI).

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

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

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

Payment accepted: Conekta підтвердила платіж з тією самою сумою та валютою. Платіж записується з ідентифікатором списання Conekta як ID транзакції, а примітка показує спосіб оплати (наприклад, марку картки та останні чотири цифри, OXXO / готівка або банківський переказ SPEI), замовлення Conekta та списання.

Awaiting Conekta payment: покупець отримав платіжний референс OXXO або SPEI. Замовлення переходить у Payment accepted, коли Conekta повідомляє про платіж.

Conekta payment on hold: сума або валюта, отримані від Conekta, не відповідають кошику (наприклад, кошик змінили після початку оплати), тестовий платіж надійшов, поки магазин працював у робочому режимі (реальні кошти не отримано), або платіж надійшов за вже скасованим замовленням. Примітка пояснює це, а платіж записується з фактично сплаченою сумою. Перевірте замовлення, потім виконайте його або поверніть платіж. Замовлення, яке в Conekta лише попередньо авторизоване, також утримується з приміткою захопити або анулювати його в панелі Conekta.

Canceled: термін дії референсу OXXO або SPEI для замовлення в очікуванні минув, або його замовлення Conekta скасовано.

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

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

Блок платежу Conekta

На сторінці замовлення відображається блок Conekta payment із замовленням Conekta, списанням, статусом платежу, сплаченою та поверненою сумою, значком Test mode для тестових платежів, історією повернень і Conekta notes замовлення.

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

У блоці Conekta payment введіть суму (підставляється сума, яка ще не повернута), за потреби причину, і натисніть Refund via Conekta. Підтвердіть запитання Повернути цю суму через Conekta? Цю дію не можна скасувати. Підтримуються повні та часткові повернення. Вам потрібне право редагувати замовлення. Повернення обмежені сумою та валютою, які Conekta фактично списала, тож після розбіжності в сумі можна повернути не більше того, що сплатив покупець, а не загальну суму замовлення. Повернення надсилається до замовлення Conekta, що містить платіж, і використовує ключ того режиму, в якому було здійснено платіж, тому цей ключ має бути налаштований. Якщо Conekta не приймає повернення, блок показує помилку, і повернення не реєструється. Успішне повернення додається до історії повернень і приміток із сумою, режимом, замовленням Conekta, ID повернення та причиною. Повне повернення переводить замовлення у Refunded. Часткове повернення статус не змінює. Повернення доступні після того, як Conekta повідомила про платіж.

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

Повернення, проведені в панелі Conekta, надходять через вебхук і додаються як примітка із сумою, повернутою в Conekta та в PrestaShop. Вони не реєструються автоматично. Оновіть замовлення вручну, не використовуючи Refund via Conekta. Чарджбек, про який повідомила Conekta, також додається як примітка.

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

Модуль працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії License — VibeFox Conekta Gateway — це перший блок на сторінці Modules > Module Manager > VibeFox Conekta Gateway > Configure, над налаштуваннями. Вставте ключ у поле License key і натисніть Activate. Після цього блок показує ключ замаскованим, статус (наприклад, дату, до якої ліцензія дійсна, і ваш домен), а також кнопки Check now, щоб знову перевірити статус, Change key, щоб ввести інший ключ, і Remove key, щоб вилучити ключ із цього магазину. Нижче розташовані рядок Product: presta-payment-conekta і посилання Керування ліцензіями та доменами у вашому акаунті, яке відкриває ваш акаунт vibefox.net. Змінювати ключ можуть лише співробітники з правом Configure для модуля. Тексти блоку відповідають мові бек-офісу (включено англійську та російську).

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

Один ключ працює на одному домені: домені основного магазину, також у конфігурації з кількома магазинами. Видалення ключа з магазину не звільняє слот домену. Звільніть слот у своєму акаунті vibefox.net.

Без активного ключа Conekta не показується покупцям на оформленні замовлення. Якщо платіж усе ж розпочато, покупець бачить Цей спосіб оплати недоступний. Оберіть інший. Вітрина PrestaShop не знає, що ви ввійшли в бек-офіс, тож спосіб оплати приховується і для вас: ви можете налаштувати модуль до купівлі ключа, але не можете перевірити його на оформленні замовлення. Нагадування з'являється в Modules > Module Manager на вкладці Alerts. Наявні замовлення не змінюються: платежі, які вже почалися, як і раніше підтверджуються, і повернення працюють.

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

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

Conekta не з'являється на оформленні замовлення: перевірте, що ліцензія активна, що Enable / Disable увімкнено, що приватний ключ поточного режиму заповнено (Test private key у тестовому режимі, Live private key у робочому режимі) і що валюта кошика — MXN або USD. Сторінка налаштувань показує попередження, якщо ключ відсутній або валюта магазину не підтримується. У розділі Payment > Preferences перевірте, чи дозволено модуль для валюти кошика, країни покупця та групи покупця.

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

Вебхук відповідає Temporarily unavailable: не вдалося звернутися до API Conekta, відсутній приватний ключ режиму замовлення, кошик зараз обробляв інший запит, або замовлення не вдалося створити (наприклад, модуль вимкнено). Conekta повторює вебхук. Причину дивіться в полі Log.

Вебхук відповідає Verification failed, Invalid payload або Invalid order id: API Conekta не підтвердив замовлення, або повідомлення не було дійсною подією замовлення Conekta.

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

URL вебхука в браузері показує Method not allowed: це нормально. URL приймає лише запити від Conekta.

Покупець бачить Не вдалося перевірити статус вашої попередньої спроби оплати: попередню платіжну сторінку Conekta для кошика не вдалося прочитати, тож нову не створюють, щоб уникнути подвійної оплати. Спробуйте ще раз за хвилину.

Покупець бачить Платіжний шлюз не налаштовано: відсутній приватний ключ поточного режиму.

Покупець бачить Перевірка платежу не пройшла: посилання повернення від Conekta не збіглося з кошиком. Перевірте замовлення в панелі Conekta; вебхук усе одно підтверджує реальний платіж.

Замовлення має статус Awaiting Conekta payment або Conekta payment on hold: прочитайте Conekta notes у блоці замовлення. Покупець ще не сплатив референс OXXO або SPEI, сума чи валюта не збіглися, тестовий платіж надійшов, поки магазин працював у робочому режимі, або платіж лише попередньо авторизований.

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

Для розробників README перелічує хуки actionWcpConektaSupportedCurrencies, actionWcpConektaOrderRequest, actionWcpConektaAllowedPaymentMethods та actionWcpConektaRefundReason.

Видалення

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

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