VibeFox PayFast for OpenCart — Допомога

Вимоги

OpenCart: 3.0.x (перевірено на 3.0.5.0) або 4.0.2 і новіші (перевірено на 4.1.0.3).

PHP: 8.0 або новіша.

Currency: південноафриканський ранд (ZAR). PayFast проводить розрахунки лише в рандах, тому замовлення має бути у ZAR. Додайте валюту в розділі System > Localisation > Currencies, якщо її ще немає у вашому магазині. Мінімальна сума замовлення — R5.00.

PayFast account: Merchant ID та Merchant Key вашого облікового запису PayFast, які знаходяться в розділі Settings > Developer Settings панелі PayFast. Настійно рекомендовано використовувати парольну фразу; якщо вона задана в PayFast, у розширенні потрібно ввести ту саму фразу. Для тестів потрібні облікові дані sandbox PayFast.

Reachable store: URL для сповіщень про оплату має бути доступний з інтернету, без базової автентифікації та без блокування файрволом.

VibeFox license key: придбаний на vibefox.net. Один ключ працює на одному домені.

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

Завантаження — це один zip-файл з пакетами для обох версій OpenCart. Розпакуйте його на своєму комп’ютері. Він містить README.txt, пакет для OpenCart 3 wcp_payfast_pay-oc3-(version).ocmod.zip і пакет для OpenCart 4 wcp_payfast_pay.ocmod.zip. Встановлюйте лише пакет для вашої версії OpenCart. Ліцензійний ключ однаковий для обох версій.

OpenCart 3

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

2. Перейдіть до Extensions > Extensions і виберіть тип Payments. Знайдіть VibeFox PayFast Pay Gateway і натисніть Install (зелена кнопка +).

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

4. Введіть Merchant ID, Merchant Key та парольну фразу. Для тестування залиште увімкненим Test mode і введіть облікові дані sandbox.

5. Увімкніть Enable/Disable і натисніть Save. Здійсніть тестовий платіж, а потім вимкніть Test mode, щоб приймати справжні платежі.

OpenCart 4

1. В адміністративній частині перейдіть до Extensions > Installer, натисніть Upload і виберіть файл wcp_payfast_pay.ocmod.zip. Не перейменовуйте файл: OpenCart 4 бере код розширення з імені файлу, і перейменований пакет не працює.

2. Пакет з’явиться у списку встановлених розширень на тій самій сторінці. Натисніть поруч із ним Install (зелена кнопка +).

3. Перейдіть до Extensions > Extensions і виберіть тип Payments. Знайдіть VibeFox PayFast Pay Gateway, натисніть Install (зелена кнопка +), а потім Edit (кнопка з олівцем).

4. Введіть ліцензійний ключ і облікові дані PayFast та протестуйте платіж так само, як у кроках 3–5 для OpenCart 3. Сторінка налаштувань і її поля однакові в обох версіях. Відрізняється лише URL сповіщень (див. Notification URL); його так само передають в PayFast з кожним платежем.

Під час нового встановлення спосіб оплати вимкнено, а тестовий режим увімкнено.

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

Усі налаштування розміщені на сторінці розширення: Extensions > Extensions > Payments > VibeFox PayFast Pay Gateway > Edit. Розділи перелічені ліворуч; кнопка Save під списком зберігає всю сторінку. Над налаштуваннями сторінка попереджає, якщо облікові дані поточного режиму порожні (тоді PayFast приховується на етапі оформлення замовлення), якщо основна валюта магазину не ZAR, якщо в бойовому режимі використовується публічний Merchant ID sandbox 10000100 і якщо парольна фраза не задана. Поки тестовий режим увімкнено, виводиться повідомлення Test mode is on: orders are paid in the PayFast sandbox, no real money is charged.

Під час збереження поле Title не може бути порожнім (до 128 символів), Sort Order має бути цілим числом (від’ємні числа дозволені), Total — числом не менше 0, а обрані географічна зона та статуси замовлень мають існувати; інакше нічого не зберігається, і сторінка вказує на поле. Якщо ви увімкнете спосіб оплати без облікових даних поточного режиму, налаштування зберігаються з попередженням.

PayFast

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

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

Description: текст, який покупець бачить на кроці Confirm Order над кнопкою підтвердження. За замовчуванням: Pay securely by card, Instant EFT and other methods on the PayFast payment page.

Sort Order: позиція PayFast серед способів оплати на етапі оформлення замовлення. Залиште поле порожнім або введіть ціле число.

Geo Zone: пропонувати PayFast лише для платіжних адрес з вибраної географічної зони. За замовчуванням: All zones. Географічні зони налаштовуються в розділі System > Localisation > Geo Zones. В OpenCart 4, якщо магазин не запитує платіжну адресу, використовується адреса доставки.

Total: сума кошика у основній валюті магазину, якої має досягти замовлення, щоб пропонувався PayFast. Залиште поле порожнім, щоб пропонувати PayFast за будь-якої суми. Сам PayFast завжди вимагає щонайменше R5.00.

Обліковий запис PayFast (бойовий режим)

Merchant ID та Merchant Key можна знайти в панелі PayFast у розділі Settings > Developer Settings (там є посилання на потрібний розділ). Якщо ви задали парольну фразу там, введіть тут точно таку саму.

Merchant ID: ваш бойовий Merchant ID PayFast.

Merchant Key: ваш бойовий Merchant Key PayFast. Він передається в PayFast з кожною платіжною формою, тому це звичайне текстове поле.

Passphrase: парольна фраза (salt) PayFast з розділу Settings > Developer Settings. Настійно рекомендовано: вона підписує платежі та сповіщення.

Sandbox (тестовий режим)

У тестовому режимі платежі надсилаються в sandbox PayFast, і справжні кошти не списуються. Облікові дані sandbox відображаються після входу до sandbox PayFast (публічний тестовий мерчант — 10000100 / 46f0cd694581a).

Test mode: Use the PayFast sandbox and the sandbox credentials below. Поки режим увімкнено, покупець на кроці Confirm Order бачить повідомлення TEST MODE: payments go to the PayFast sandbox, no real money is charged. За замовчуванням: увімкнено.

Sandbox Merchant ID: Merchant ID вашого облікового запису sandbox.

Sandbox Merchant Key: Merchant Key вашого облікового запису sandbox.

Sandbox Passphrase: лише якщо парольна фраза задана у вашому обліковому записі sandbox.

Збережені парольні фрази більше не відображаються. Поле залишається порожнім і показує Saved — leave empty to keep it. Вводьте нове значення, лише якщо хочете його змінити. Щоб видалити збережену парольну фразу, позначте під полем пункт Clear the saved passphrase on save і натисніть Save.

Сповіщення про оплату (ITN)

Notification URL: PayFast підтверджує кожен платіж серверним сповіщенням на URL, який відображається тут. Він має вигляд https://your-store/index.php?route=extension/payment/wcp_payfast_pay/itn для OpenCart 3 та https://your-store/index.php?route=extension/wcp_payfast_pay/payment/wcp_payfast_pay.itn для OpenCart 4 і формується з адреси вітрини вашої інсталяції OpenCart. Адреса передається з кожним платежем, тож у PayFast нічого налаштовувати не потрібно, але вона має бути доступна з інтернету. Замовлення отримують статус лише за цими перевіреними сповіщеннями; повернення покупця в магазин статус замовлення не змінює.

Source check: у бойовому режимі сповіщення приймаються лише з серверів PayFast. Адреси беруться з DNS-записів PayFast (кешуються на 6 годин; кеш скидається під час збереження налаштувань) та з задокументованих PayFast діапазонів адрес. Вимикайте перевірку, лише якщо магазин розташований за проксі або CDN, які приховують адресу відвідувача. Підпис і підтвердження від сервера перевіряються завжди. Сповіщення sandbox за адресою не перевіряються. За замовчуванням: увімкнено.

Замовлення

OpenCart створює замовлення на кроці Confirm Order без статусу (відсутнє замовлення). Статус воно отримує лише з перевіреного сповіщення PayFast. Скасований, невдалий або покинутий платіж залишає замовлення без статусу, і покупець може оплатити знову. Кожне поле нижче перелічує ваші статуси замовлень OpenCart.

Order Status (paid): статус після того, як PayFast підтвердив платіж, а сума та валюта збігаються. За замовчуванням: В обробці.

Awaiting PayFast payment: PayFast повідомив, що платіж очікує обробки (наприклад, Instant EFT). Коли PayFast його завершить, статус зміниться на оплачений. За замовчуванням: Очікується.

PayFast payment on hold: платіж, який потребує вашої перевірки (див. розділ Статуси замовлень). Таке замовлення не позначається оплаченим; примітка пояснює причину. За замовчуванням: Очікується, оскільки в OpenCart немає статусу On hold. Ви можете створити власний статус у розділі System > Localisation > Order Statuses і вибрати його тут.

Payment failed: платіж, що очікував обробки, не пройшов. Якщо PayFast завершить його пізніше, замовлення перейде в оплачений статус. За замовчуванням: Невдало.

Додатково

Debug log: записує кроки платежу у файл payfast_p_debug.log.php у папці логів OpenCart (storage/logs). Файл не можна відкрити через веб, а при досягненні 5 МБ його перейменовують на payfast_p_debug.old.log.php. Помилки та попередження записуються завжди, навіть коли перемикач вимкнено. Парольні фрази, ключі та дані покупців не записуються. За замовчуванням: вимкнено.

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

Uninstall: Delete the gateway settings when the extension is uninstalled (налаштування, кешовані адреси PayFast та журнал). Записи про платежі PayFast і замовлення завжди зберігаються. За замовчуванням: вимкнено.

Імпорт / експорт

Export: Download JSON зберігає налаштування у файл JSON. Парольні фрази не експортуються.

Import: вставте раніше експортований JSON і натисніть Import, щоб відновити налаштування. Збережені парольні фрази зберігаються.

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

На кроці Payment Method покупець обирає спосіб оплати (за замовчуванням PayFast). На кроці Confirm Order покупець бачить ваш опис і примітку Thank you for your order. You will be redirected to PayFast to complete the payment. OpenCart створює замовлення на цьому кроці, ще без статусу. На OpenCart 4 покупець обирає спосіб оплати кнопкою Choose у блоці способу оплати, у вікні Payment method options, і натискає Confirm Order внизу сторінки оформлення замовлення. Коли покупець натискає Confirm Order, розширення надсилає підписану платіжну форму в PayFast. Форма містить суму замовлення в ZAR, Order # з номером замовлення, ім’я та e-mail покупця, платіжне посилання (номер замовлення та спробу) і випадковий токен спроби. Кожна нова спроба отримує нове посилання та новий токен.

На сторінці PayFast покупець платить карткою, через Instant EFT або іншим способом, підключеним до вашого облікового запису PayFast. Потім PayFast надсилає сповіщення про оплату (ITN) до вашого магазину. Замовлення позначається оплаченим лише після того, як PayFast підтвердить платіж сповіщенням, яке проходить усі перевірки:

Далі замовлення отримує статус стандартним для OpenCart способом, зі звичайними листами про замовлення та оновленням залишків на складі. Сповіщення щодо одного кошика обробляються по черзі; якщо інше сповіщення щодо того самого кошика вже обробляється, PayFast отримує відповідь з помилкою і надсилає сповіщення повторно. URL сповіщень працює й тоді, коли магазин перебуває в режимі обслуговування: OpenCart 3 пропускає запити платіжних розширень, а на OpenCart 4 розширення додає стартову дію (startup action), яка пропускає сповіщення та повернення покупця з PayFast.

Коли покупець повертається і замовлення має статус, відображається сторінка успішного оформлення замовлення OpenCart. Якщо PayFast повідомив, що платіж очікує обробки, також виводиться PayFast is confirming your payment. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. Якщо замовлення на утриманні, виводиться Your payment is being reviewed. We will contact you if anything else is needed. Якщо платіж, що очікував, згодом не пройшов, виводиться Your PayFast payment was not completed. Please contact us about this order. (на OpenCart 4 покупця натомість повертають до оформлення замовлення, див. нижче). Якщо сповіщення ще не надійшло, відкривається сторінка Payment confirmation, на якій повідомляється, що PayFast підтверджує платіж, з кнопками Check again та Back to checkout.

Якщо покупець скасовує платіж на сторінці PayFast, він повертається до оформлення замовлення з повідомленням The PayFast payment was cancelled. You can try again or choose another payment method. Якщо PayFast повідомив, що платіж не пройшов, виводиться The payment was not completed. You can try again or choose another payment method. Кошик зберігається, і оплатити його можна знову. На OpenCart 4 ці повідомлення відображаються над сторінкою оформлення замовлення. OpenCart 3 створює нове замовлення щоразу, коли показується крок Confirm Order; OpenCart 4 зберігає одне замовлення для оформлення і оновлює його, тому після скасованого або невдалого платежу покупець оплачує те саме замовлення новою спробою. Якщо інше замовлення з того самого кошика вже оброблено PayFast (наприклад, у другій вкладці браузера), покупець переходить на сторінку успіху замість повторної оплати.

OpenCart 4 зберігає замовлення в оформленні, доки не буде показано сторінку успішного оформлення. Якщо це замовлення тим часом закрили без оплати (наприклад, його платіж у очікуванні не пройшов або ви його скасували), покупця повертають до оформлення замовлення з повідомленням Your previous order was cancelled or its payment failed. Please confirm the order again., а наступне натискання Confirm Order оплачує нове замовлення. Якщо це замовлення вже має статус, а в кошику тепер інші товари або кількості, повідомлення буде таким: Your previous order has already been placed for other cart contents. Please confirm the order of your current cart again.

Спосіб оплати приховується, якщо відсутні облікові дані поточного режиму, якщо валюта оформлення замовлення не ZAR або якщо сума нижча за R5.00. Якщо покупець усе ж дійшов до оплати, над кнопкою з’являється коротке пояснення, наприклад PayFast accepts payments from R5.00. Please choose another payment method.

Розширення приймає лише разові платежі у ZAR. Воно не підтримує повернення коштів зі сторінки замовлення, підписки, збережені (токенізовані) картки та розділені платежі.

Замовлення

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

No status (missing order): покупця перенаправлено до PayFast, а сповіщення про оплату ще не надійшло, або PayFast повідомив, що платіж не пройшов. У розділі Sales > Orders такі замовлення показуються лише з фільтром Order Status, встановленим на Missing Orders.

На OpenCart 4 неоплачене замовлення з оформлення може отримати статус Voided, який OpenCart 4 встановлює, коли покупець повертається до кроку Confirm Order. Розширення вважає таке замовлення замовленням без статусу, і пізніший платіж усе одно його підтверджує.

Order Status (paid) (default Processing): PayFast підтвердив платіж. Примітка показує ID платежу PayFast. Платіж sandbox отримує примітку про те, що справжні кошти не списувалися.

Awaiting PayFast payment (default Pending): PayFast повідомив, що платіж очікує обробки. Замовлення переходить в оплачений статус, коли PayFast завершить платіж, або в Payment failed, якщо платіж не пройде; покупець отримує листа про ці зміни.

Payment failed (default Failed): платіж, що очікував обробки, не пройшов. Якщо PayFast завершить його пізніше, замовлення перейде в оплачений статус.

PayFast payment on hold (default Pending): сплачена сума відрізняється від суми замовлення, або замовлення не у ZAR; платіж надійшов для замовлення, статус якого ви тим часом змінили (наприклад, скасували), або спосіб оплати якого вже не PayFast; або платіж sandbox надійшов, коли шлюз працював у бойовому режимі. Примітка пояснює це. Перевірте замовлення та панель PayFast, а потім переведіть замовлення в оплачений статус або скасуйте його та поверніть кошти в PayFast.

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

Примітки — це записи в розділі History замовлення, які покупець не бачить.

Вкладка VibeFox PayFast Pay Gateway

У розділі Sales > Orders відкрийте замовлення, оплачене через PayFast. Унизу сторінки замовлення, поруч із History та Additional, вкладка VibeFox PayFast Pay Gateway показує Payment reference (m_payment_id), PayFast payment ID, Environment (бойовий режим або sandbox), запитувану суму, статус, суми брутто, комісію та нетто у ZAR, а також PayFast notes. Для замовлення на утриманні вона показує нагадування перевірити платіж. Вкладка відображається користувачам, які мають доступ до розширення.

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

Повернення коштів зі сторінки замовлення не підтримуються. Поверніть платіж у панелі PayFast, а потім вручну оновіть замовлення в OpenCart.

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

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

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

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

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

PayFast does not appear at checkout: перевірте, що ліцензія активна, Enable/Disable увімкнено, заповнені Merchant ID і Merchant Key поточного режиму, валюта оформлення замовлення — ZAR, а сума замовлення становить щонайменше R5.00. Сторінка налаштувань показує попередження, якщо чогось бракує. Також перевірте, що платіжна адреса входить до вибраної Geo Zone, а замовлення досягає значення Total, заданого в налаштуваннях.

The payment went through, but the order stays without a status: PayFast не зміг доставити сповіщення про оплату або воно було відхилене. Перегляньте поле Log на сторінці розширення: помилки та відхилені сповіщення записуються завжди, а Debug log додає кожен крок. Типові причини: магазин недоступний з інтернету (базова автентифікація, файрвол), різні парольні фрази в PayFast і в розширенні або, у бойовому режимі за проксі чи CDN, перевірка джерела. У цьому разі вимкніть Source check.

The notification answers Invalid signature: парольна фраза в розширенні не та, що задана в PayFast для режиму, у якому здійснено платіж.

The notification answers Invalid source: сповіщення надійшло не з адреси PayFast, або проксі чи CDN приховує справжню адресу. Вимкніть Source check, якщо магазин розташований за проксі або CDN.

The notification answers Merchant mismatch or Order mismatch: платіж було здійснено на інший обліковий запис PayFast або він не належить до цієї спроби оплати. Нічого не змінюється.

The notification answers Order not found: платіжне посилання невідоме цьому магазину. Нічого не змінюється.

The notification answers Confirmation unavailable, Busy or Temporary error: не вдалося звернутися до PayFast за підтвердженням від сервера, інше сповіщення щодо того самого кошика оброблялося в той самий момент, або не вдалося встановити статус замовлення. PayFast повторить сповіщення. Журнал показує причину.

The notification answers Not configured: відсутні облікові дані режиму, у якому розпочато платіж. Введіть їх знову, наприклад облікові дані sandbox для тестового платежу.

The customer sees PayFast accepts payments in South African rand (ZAR) only: замовлення в іншій валюті. Попросіть покупця платити в рандах або вибрати інший спосіб оплати.

The customer sees This payment method is not available. Please reload the checkout page. Сесія оформлення замовлення більше не відповідає замовленню, або спосіб оплати тим часом вимкнули. Покупець має перезавантажити сторінку оформлення замовлення.

Order is in the on-hold status: прочитайте примітки на вкладці VibeFox PayFast Pay Gateway (див. розділ Статуси замовлень) і панель PayFast, а потім встановіть оплачений статус або поверніть кошти.

A sandbox payment did not pay the order: шлюз працює в бойовому режимі. Платежі sandbox ніколи не оплачують замовлення в бойовому режимі; примітка до замовлення про це повідомляє.

Для розробників: перед підписанням платіжної форми розширення викликає подію OpenCart payfast_p_payment_data з полями форми та замовленням. Облікові дані мерчанта, URL, платіжне посилання, сума та токен через цю подію змінити не можна.

Видалення

Перейдіть до Extensions > Extensions, виберіть тип Payments і натисніть Uninstall (червона кнопка −) поруч із VibeFox PayFast Pay Gateway. Ліцензійний ключ і статус ліцензії цього розширення завжди видаляються. OpenCart завжди видаляє власні налаштування розширення: Enable/Disable, Sort Order, Geo Zone, Total та статуси замовлень із розділу Orders, які під час повторного встановлення повертаються до значень за замовчуванням. Також видаляється подія OpenCart розширення (в OpenCart 4 — його події та стартова дія, яка пропускає сповіщення та повернення покупця з PayFast у режимі обслуговування). Якщо Delete the gateway settings when the extension is uninstalled увімкнено, видаляються решта налаштувань шлюзу (назва, опис, облікові дані, парольні фрази, тестовий режим, перевірка джерела, журналювання), кешовані адреси PayFast і журнал. Якщо вимкнено, їх буде збережено для подальшого повторного встановлення. Записи про платежі PayFast і замовлення завжди зберігаються. Наявні замовлення зберігають свої платіжні примітки.

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

PayFast — торговельна марка її власника. Це розширення не пов’язане з PayFast і не схвалене PayFast.