VibeFox Razorpay for OpenCart — Помощь

Требования

OpenCart: 3.0.x (проверено на 3.0.5.0) или 4.0.2 и новее (проверено на 4.1.0.3).

PHP: 8.0 или новее.

Аккаунт Razorpay: вам нужны Key ID и Key Secret вашего аккаунта Razorpay для тестового режима, а для рабочего режима — после активации аккаунта. Настоятельно рекомендуется вебхук с секретом на ваш выбор (см. Настройка). Платежи в валютах, отличных от INR, требуют включённого в вашем аккаунте Razorpay параметра International Payments.

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

Установка

Файл для загрузки — один zip-архив с пакетами для обеих версий OpenCart. Распакуйте его на своём компьютере. Он содержит README.txt, пакет для OpenCart 3 wcp_razorpay_payment-oc3-(version).ocmod.zip и пакет для OpenCart 4 wcp_razorpay_payment.ocmod.zip. Устанавливайте только пакет для вашей версии OpenCart. Лицензионный ключ один и тот же для обеих версий.

OpenCart 3

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

2. Перейдите в Extensions > Extensions и выберите тип Payments. Найдите VibeFox Razorpay Payment и нажмите Install (зелёная кнопка +). Вашему администратору необходимо право на изменение списка платёжных расширений.

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

4. Введите Test Key ID и Test Key Secret, настройте вебхук в Razorpay Dashboard и введите его секрет (см. Настройка).

5. Включите Enable/Disable и нажмите Save. Проведите тестовый платёж при включённом Test mode. Когда всё будет готово, введите ключи Live и выключите Test mode.

OpenCart 4

1. В административной части перейдите в Extensions > Installer, нажмите Upload и выберите файл wcp_razorpay_payment.ocmod.zip. Не переименовывайте файл: OpenCart 4 берёт код расширения из имени файла, и переименованный пакет не работает.

2. Пакет появится в списке установленных расширений на той же странице. Нажмите рядом с ним Install (зелёная кнопка +).

3. Перейдите в Extensions > Extensions и выберите тип Payments. Найдите VibeFox Razorpay Payment, нажмите Install (зелёная кнопка +), а затем Edit (кнопка с карандашом).

4. Введите лицензионный ключ, ключи Razorpay и вебхук так же, как в шагах с 3 по 5 для OpenCart 3. Страница настроек и её поля одинаковы в обеих версиях. Отличается только URL вебхука (см. Вебхук).

Новая установка начинает работу с выключенным способом оплаты и включённым тестовым режимом.

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Payments > VibeFox Razorpay Payment > Edit. Разделы перечислены слева; кнопка Save под списком сохраняет всю страницу. Без права на изменение расширения страница показывает настройки, но не может их сохранить.

Над настройками страница сообщает, что заказ получает статус только после проверки платежа в Razorpay, и выводит уведомления: отсутствуют ключи текущего режима (тогда Razorpay не показывается на оформлении заказа), Key ID не начинается с rzp_test_ в тестовом режиме или с rzp_live_ в рабочем режиме, включён тестовый режим, секрет вебхука пуст или валюта магазина по умолчанию не INR и требует включения International Payments в вашем аккаунте Razorpay. Уведомления обновляются после каждого сохранения.

При сохранении поле Title должно содержать от 1 до 128 символов (Enter a title for the payment method (1 to 128 characters).), Sort Order должно быть целым числом (отрицательные числа допускаются), Total должно быть числом не меньше 0, а геозона и каждый статус заказа должны существовать. Иначе ничего не сохраняется. Пробелы, вставленные вместе с Key ID, удаляются.

Razorpay

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

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

Description: текст, который покупатель видит на шаге Confirm Order над кнопкой подтверждения. По умолчанию: Pay securely via UPI, Credit/Debit Card, or Internet Banking through Razorpay.

Sort Order: позиция Razorpay среди способов оплаты на оформлении заказа. Оставьте поле пустым или введите целое число.

Geo Zone: предлагать Razorpay только для платёжных адресов из выбранной геозоны. По умолчанию: All zones. Геозоны настраиваются в System > Localisation > Geo Zones.

Total: сумма заказа в валюте магазина по умолчанию, которую заказ должен достичь, чтобы предлагался Razorpay: число не меньше 0. Оставьте поле пустым, чтобы предлагать Razorpay при любой сумме.

API-ключи

Ключи берутся в Razorpay Dashboard в разделе Account & Settings > API Keys (на странице есть ссылка туда). Переключите Dashboard в тестовый режим, чтобы создать тестовые ключи (rzp_test_...). Ключи Live (rzp_live_...) доступны после активации аккаунта.

Test mode: использует ключи тестового режима, поэтому реальные деньги не списываются. По умолчанию: включено. Выключите его, чтобы принимать реальные платежи. Платежи, списания и возвраты по заказу всегда используют ключи режима, в котором был оплачен заказ, поэтому смена режима позднее не влияет на существующие заказы. Пока режим включён, покупатели на шаге Confirm Order и на странице оплаты видят Razorpay Test mode: no real money will be charged.

Test Key ID: Key ID из Razorpay Dashboard в тестовом режиме. Начинается с rzp_test_.

Test Key Secret: Key Secret из Razorpay Dashboard в тестовом режиме.

Live Key ID: Key ID из Razorpay Dashboard в рабочем режиме. Начинается с rzp_live_.

Live Key Secret: Key Secret из Razorpay Dashboard в рабочем режиме.

Сохранённые секреты больше никогда не показываются. Поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить. Чтобы удалить сохранённое значение, отметьте Clear the saved value on save под полем и нажмите Save.

Оплата

Payment Action: момент списания денег. По умолчанию: Authorize & Capture.

Вебхук

Вебхук подтверждает платежи, даже если покупатель закрыл браузер сразу после оплаты, и фиксирует возвраты, сделанные в Razorpay Dashboard. В Razorpay Dashboard перейдите в Account & Settings > Webhooks и добавьте вебхук в тестовом режиме и ещё один в рабочем режиме. Используйте URL, показанный в поле Webhook URL в этом разделе. В OpenCart 3 он выглядит так: https://your-store/index.php?route=extension/payment/wcp_razorpay_payment/webhook, в OpenCart 4 так: https://your-store/index.php?route=extension/wcp_razorpay_payment/payment/wcp_razorpay_payment.webhook. Он формируется из адреса витрины вашей установки OpenCart. Скопируйте его точно в том виде, в каком он показан в настройках. Введите в Razorpay секрет на ваш выбор и выберите эти события (они также перечислены в этом разделе):

Webhook Secret: секрет, который вы ввели при создании вебхука. Используйте один и тот же секрет для тестового и рабочего вебхуков, потому что у расширения одно поле для обоих. Вебхуки без действительной подписи отклоняются. Без вебхука платёж подтверждается, только когда покупатель возвращается из всплывающего окна, или когда покупатель позднее запускает оплату для той же корзины снова.

Заказы

OpenCart создаёт заказ на шаге Confirm Order без статуса (отсутствующий заказ). Заказ получает статус только после того, как Razorpay подтвердил платёж. Неуспешный или брошенный платёж оставляет заказ без статуса, а корзина сохраняется. В OpenCart нет статусов Authorized и On hold, поэтому вы выбираете существующие статусы; причину объясняют примечания к заказу. Каждое поле ниже перечисляет ваши статусы заказов OpenCart.

Order Status After Payment: платёж списан, сумма и валюта совпадают. По умолчанию: В обработке.

Authorized Status: Authorize Only: деньги зарезервированы, но ещё не списаны. По умолчанию: Ожидание.

On Hold (Review) Status: ручная проверка: оплаченная сумма или валюта отличаются от суммы заказа, платёж пришёл для отменённого заказа, или подпись всплывающего окна была действительной, но платёж не удалось проверить через API Razorpay. По умолчанию: Ожидание. Вы можете создать собственные статусы в System > Localisation > Order Statuses и выбрать их здесь.

Cancelled Status: расширение никогда не устанавливает этот статус. Он лишь сообщает расширению, какие заказы отменены: платёж, списанный позже для такого заказа, переводит его на проверку вместо повторного открытия; авторизованный платёж только добавляет примечание. По умолчанию: Отменён.

Refunded Status: устанавливается, когда платёж полностью возвращён, со вкладки заказа или в Razorpay Dashboard. По умолчанию: Возвращён.

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

Enable Logging: журнал записывается в razorpay_p_debug.log.php в папке логов OpenCart (storage/logs). Открыть файл через веб нельзя. Ошибки и предупреждения записываются всегда; эта опция добавляет подробности для отладки. Ключи, подписи и контактные данные покупателей никогда не записываются. По умолчанию: выключено.

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

Delete Data on Uninstall: при включении удаление расширения удаляет настройки шлюза и журнал. Заказы, а также их транзакции и возвраты Razorpay всегда сохраняются. По умолчанию: выключено.

Импорт / экспорт

Export: Download JSON сохраняет настройки в файл JSON. Секретные ключи не экспортируются.

Import: вставьте ранее экспортированный JSON и нажмите Import, чтобы восстановить настройки. Сохранённые секретные ключи сохраняются.

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

На шаге Payment Method покупатель выбирает способ оплаты (по умолчанию UPI, Cards, NetBanking). На шаге Confirm Order покупатель видит ваше описание и примечание After "Confirm Order" the Razorpay Checkout window opens to pay securely (UPI, cards, NetBanking, wallets). OpenCart создаёт заказ на этом шаге, по-прежнему без статуса. Когда покупатель нажимает Confirm Order, расширение создаёт заказ Razorpay на точную сумму и валюту заказа и открывает страницу Razorpay payment вашего магазина. Там автоматически открывается всплывающее окно Razorpay Checkout с уже заполненными именем, адресом электронной почты и телефоном покупателя. В OpenCart 4 покупатель выбирает способ оплаты кнопкой Choose в блоке способа оплаты, в окне Payment method options, и нажимает Confirm Order внизу страницы оформления заказа. В Razorpay платёж отображается как Order # и номер заказа. Если всплывающее окно закрыто, покупатель может нажать Pay Now, чтобы открыть его снова, или Choose another payment method, чтобы вернуться к оформлению заказа. Корзина сохраняется.

После успешного платежа покупатель видит Please wait while we process your payment... Расширение проверяет подпись Razorpay, получает платёж через API Razorpay и сравнивает сумму и валюту с заказом. Заказ помечается оплаченным только после подтверждения от Razorpay. Затем заказ получает свой статус обычным для OpenCart способом, с обычными письмами о заказе и обновлением остатков, а покупатель видит страницу успешного оформления заказа OpenCart. Если подпись действительна, но платёж на этот момент не удалось получить, заказ получает статус On Hold (Review) Status, и вебхук подтвердит его позже.

OpenCart 3 создаёт новый заказ каждый раз, когда показывается шаг Confirm Order. OpenCart 4 сохраняет один заказ для оформления и обновляет его, поэтому после закрытия окна или Choose another payment method покупатель оплачивает тот же заказ. Перед запуском нового платежа расширение проверяет открытые заказы Razorpay той же корзины: уже оплаченный заказ, например если покупатель закрыл браузер и вебхука нет, применяется вместо запроса второго платежа, а остальные больше не предлагаются. Если покупатель оплачивает тот же заказ повторно, его заказ Razorpay переиспользуется, когда сумма, валюта и режим не изменились; иначе создаётся новый. Если корзина уже оплачена другим заказом, покупатель сразу попадает на страницу успешного оформления.

Сообщения, которые может видеть покупатель:

В OpenCart 4, если заказ оформления был закрыт магазином или уже оплачен для другой корзины (например, корзина с тех пор изменилась, в том числе новым количеством), покупатель возвращается к оформлению заказа с сообщением Your previous order is already closed or paid. Please confirm the order again: the cart will be paid with a new order., а следующее нажатие Confirm Order оплачивает новый заказ. В OpenCart 4 сообщения, которые возвращают к оформлению заказа, в том числе это, Payment session not found. Please try again. и We could not verify your payment., показываются над страницей оформления заказа.

Вебхук работает и тогда, когда магазин находится в режиме обслуживания: OpenCart 3 пропускает запросы платёжных расширений, а в OpenCart 4 расширение добавляет стартовое действие для вебхука и результата всплывающего окна.

Расширение принимает только разовые платежи. Оно не поддерживает подписки и регулярные платежи, сохранённые карты, Razorpay Magic Checkout, Payment Links или Route (разделённые платежи), а также виджеты предложений и рассрочки.

Заказы и возвраты

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

Нет статуса (отсутствующий заказ): покупатель не оплатил, попытка платежа не удалась или Razorpay ещё не подтвердил платёж. В Sales > Orders такие заказы показываются только с фильтром Order Status, установленным в значение Missing Orders.

Order Status After Payment (по умолчанию В обработке): платёж списан и подтверждён. Примечание показывает идентификатор платежа Razorpay (pay_...), сумму и способ подтверждения (callback, webhook, синхронизация или администратор).

Authorized Status (по умолчанию Ожидание): платёж только авторизован (Authorize Only). Списав его, вы завершите заказ.

On Hold (Review) Status (по умолчанию Ожидание): устанавливается в этих случаях, каждый раз с примечанием: оплаченная сумма или валюта не совпали с заказом, платёж списан для отменённого заказа или платёж в этот момент не удалось проверить через API Razorpay. Проверьте заказ и обработайте его или верните платёж.

Cancelled Status: платёж, поступивший позже для отменённого заказа, не открывает его автоматически: авторизованный платёж не списывается и получает только примечание, а списанный платёж переводит заказ на проверку. Повторное уведомление о платеже, который уже оплатил заказ, ничего не меняет, даже если вы отменили заказ позже.

Refunded Status (по умолчанию Возвращён): платёж полностью возвращён.

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

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

Вкладка VibeFox Razorpay Payment

В Sales > Orders откройте заказ, оплаченный через Razorpay. Внизу страницы заказа, рядом с History и Additional, вкладка VibeFox Razorpay Payment показывает Payment ID с меткой Test mode для тестовых платежей, Razorpay order, Status платежа, Paid / refunded (сумму, списанную Razorpay, и сумму возврата), кнопку списания, форму возврата, историю возвратов и Razorpay notes заказа. Вкладка показывается пользователям, которые имеют доступ к расширению. Списание и возвраты требуют права на изменение расширения (задаётся в System > Users > User Groups).

Списание (Authorize Only)

Откройте заказ в статусе Authorized Status, нажмите на вкладке Capture Razorpay payment и подтвердите Capture the authorized Razorpay payment? Платёж списывается в том режиме, в котором был авторизован, а заказ переводится в Order Status After Payment без уведомления покупателя и без изменения остатков, как при ручной смене статуса. Если Razorpay отказывает, вкладка и примечания показывают Razorpay capture failed: с указанием причины. Списание, выполненное в Razorpay Dashboard, завершает заказ через вебхук.

Возвраты

На вкладке введите Amount (подставляется сумма, которая ещё не возвращена), при необходимости Reason (optional), и нажмите Refund via Razorpay. Подтвердите вопрос Refund this amount through Razorpay? This cannot be undone. Поддерживаются полный и частичный возвраты. Возвраты выполняются в сумме и валюте, которые списал Razorpay, поэтому после расхождения суммы вы можете вернуть не больше того, что покупатель фактически заплатил, а не сумму заказа. Сумма больше допустимой выводит Invalid refund amount: at most и саму сумму. Возврат отправляется с ключами того режима, в котором был совершён платёж. Если Razorpay не принимает возврат, вкладка показывает Razorpay refund failed: с причиной, и возврат не фиксируется. Успешный возврат добавляется в историю возвратов и примечания с идентификатором возврата Razorpay, суммой и статусом. Полный возврат переводит заказ в Refunded Status без уведомления покупателя и без возврата товаров на склад. Частичный возврат статус не меняет. Возвраты доступны после списания платежа.

Возвраты товаров в Sales > Returns не возвращают деньги через Razorpay.

Возвраты, сделанные в Razorpay Dashboard, поступают через вебхук и фиксируются один раз в истории возвратов (с пометкой Razorpay Dashboard) и в примечаниях. Когда заказ полностью возвращён, его статус становится Refunded Status. Возврат из Dashboard в другой валюте или больше подлежащей возврату суммы автоматически не фиксируется; примечание просит внести его вручную.

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

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

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

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

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

Razorpay не появляется на оформлении заказа: проверьте, что лицензия активна, Enable/Disable включён и в текущем режиме заполнены оба ключа: Test Key ID и Test Key Secret в тестовом режиме, Live Key ID и Live Key Secret в рабочем режиме. Страница настроек показывает уведомление, если их нет. Также проверьте, что платёжный адрес входит в выбранную Geo Zone, и что сумма заказа достигает Total, заданного в настройках.

Платёж прошёл, но заказ остаётся без статуса: вебхук не работает. В Razorpay Dashboard проверьте, что вебхук существует в том режиме, который вы используете (Test или Live), что его URL точно совпадает с показанным в Webhook URL, и что выбраны все пять событий. Проверьте, что Webhook Secret совпадает с секретом в Razorpay. Заказ также получает статус, когда покупатель возвращается из всплывающего окна или запускает оплату той же корзины снова.

Вебхук отвечает Webhook secret not configured: поле Webhook Secret пусто. Введите секрет вебхука Razorpay. Razorpay повторно отправит событие позже.

Вебхук отвечает Invalid signature или Missing signature: секрет в настройках отличается от секрета вебхука Razorpay. Введите один и тот же секрет в обоих местах, для тестового и для рабочего вебхука.

Вебхук отвечает Retry later: расширению не удалось подтвердить списание через API Razorpay, не удалось установить статус заказа, или корзину в тот же момент обновлял другой запрос. Razorpay повторно отправит событие автоматически. Причина указана в Log.

URL вебхука в браузере показывает Method not allowed: это нормально. URL принимает только запросы от Razorpay.

Заказ находится в статусе проверки: прочитайте примечания на вкладке VibeFox Razorpay Payment. Сумма или валюта не совпали с заказом, платёж пришёл для отменённого заказа, либо его не удалось проверить через API Razorpay в этот момент, и он ждёт вебхука.

Покупатель видит ошибку при оплате: посмотрите поле Log на странице расширения. Ошибки записываются даже при выключенном Enable Logging. Неверные ключи выводят сообщение, что способ оплаты сейчас недоступен. Другие причины от Razorpay показываются после Razorpay could not accept this payment:.

Всплывающее окно не открывается: скрипт Razorpay Checkout заблокирован блокировщиком контента или соединением. Покупатель видит сообщение и может перезагрузить страницу.

На вкладке нет формы списания или возврата: вкладка показывает причину: платёж ещё не списан, он полностью возвращён, у вашей группы пользователей нет права на изменение расширения, или не заданы ключи того режима, в котором совершён платёж (The payment was made in Test mode, but the Test Key ID / Key Secret are not configured. или то же самое для рабочего режима). Введите ключи этого режима и повторите попытку.

Удаление

Перейдите в Extensions > Extensions, выберите тип Payments и нажмите Uninstall (красная кнопка −) рядом с VibeFox Razorpay Payment. Лицензионный ключ и статус лицензии этого расширения всегда удаляются. OpenCart всегда удаляет собственные настройки расширения: Enable/Disable, Sort Order, Geo Zone, Total и статусы заказов раздела Orders, которые при повторной установке возвращаются к значениям по умолчанию. В OpenCart 4 также удаляются события расширения и его стартовое действие, которое пропускает вебхук в режиме обслуживания. Если Delete Data on Uninstall включён, удаляются остальные настройки шлюза (заголовок, описание, тестовый режим, ключи, действие оплаты, секрет вебхука, журналирование) и журнал. Если выключен, они сохраняются для будущей повторной установки. Транзакции и возвраты Razorpay всегда сохраняются, поэтому заказы, оплаченные ранее, можно списать и вернуть и после повторной установки. Существующие заказы сохраняют свои примечания об оплате.

В OpenCart 4, чтобы удалить также файлы расширения, после удаления перейдите в Extensions > Installer, нажмите Uninstall (оранжевая кнопка −) рядом с VibeFox Razorpay Payment в списке установленных расширений, а затем Delete (красная кнопка с корзиной), чтобы удалить загруженный пакет.

Razorpay является товарным знаком его правообладателя. Это расширение не связано с Razorpay и не одобрено Razorpay.