VibeFox Razorpay for Adobe Commerce — Aide

Requirements

Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.

PHP: 8.1 to 8.4, with the cURL and JSON extensions.

Razorpay account: you need the Key ID and Key Secret of your Razorpay account for test mode, and for live mode once your account is activated. A webhook with a secret of your choice is strongly recommended (see Configuration). Payments in currencies other than INR and MYR may need International Payments enabled on your Razorpay account.

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

The module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.

1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-razorpay-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/RazorpayPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_RazorpayPayment and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.

3. In the Admin go to Stores > Configuration > Sales > Payment Methods and open VibeFox Razorpay Payment. When the Magento PayPal module is enabled, the group is listed under Other Payment Methods. Paste your VibeFox license key into License key in the license block, the first row of the group, and click Activate (see License key).

4. Enter your Test Key ID and Test Key Secret, set up the webhook in the Razorpay Dashboard and enter its secret (see Configuration). Set Enable to Yes and click Save Config. Make a test payment with Test mode = Yes. When you are ready, enter the Live keys and set Test mode to No.

The module adds the UPI, Cards, NetBanking payment method (you can change this title) to the Magento checkout. It is off after installation (Enable = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates two tables for the Razorpay payment attempts and refunds.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Razorpay Payment, in the standard Magento configuration form, as one list of fields. The headings below only group them. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; Title and Description also for a store view. Delete settings on uninstall is read from the Default Config only. Save Config saves the whole page. Spaces pasted with the Key IDs are removed when you save.

If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Title gives Enter a title for the payment method.; a Sort Order that is not a whole number gives Sort order must be a whole number.; a Minimum Order Total or Maximum Order Total that is not a number of 0 or greater gives Order total must be a number, 0 or greater. Write amounts with a dot, such as 9.99; 9,99 is rejected.

Status: this row shows Webhook URL: and the address of the webhook (see Webhook). When Enable is Yes in the Default Config, it also shows notices for the Default Config: the keys of the current mode are missing (for example Enter the Test Key ID and Test Key Secret — until then Razorpay is not shown at checkout.), the Key ID does not start with rzp_test_ in test mode or rzp_live_ in live mode, Test mode is on: no real money is charged., the webhook secret is empty, or the store currency is not INR or MYR and needs International Payments on your Razorpay account.

General

Enable: shows or hides Razorpay at checkout. Default: No. Notifications for existing payments remain active when it is No.

Title: the payment method name customers see at checkout. It is also the name shown in the order. Default: UPI, Cards, NetBanking. Required.

Description: the text shown under the payment method when the customer selects it at checkout. Default: Pay securely via UPI, Credit/Debit Card, or Internet Banking through Razorpay.

Sort Order: the position among the payment methods at checkout. A whole number or empty.

API keys

Get your keys in the Razorpay Dashboard under Account & Settings > API Keys. Switch the Dashboard to Test mode to generate test keys (rzp_test_...). Live keys (rzp_live_...) are available after your account is activated.

Test mode: uses the Test keys, so no real money is charged. Default: Yes. Set it to No to take real payments. While it is on, customers see TEST MODE — no real payment. Pay only with test credentials. under the payment method. Payments, captures and refunds of an order always use the keys of the mode in which the payment was started, so switching the mode later does not affect existing orders.

Test Key ID: the Key ID from the Razorpay Dashboard in Test mode. It starts with rzp_test_.

Test Key Secret: the Key Secret from the Razorpay Dashboard in Test mode.

Live Key ID: the Key ID from the Razorpay Dashboard in Live mode. It starts with rzp_live_.

Live Key Secret: the Key Secret from the Razorpay Dashboard in Live mode.

Secrets are stored encrypted, and a saved secret shows only a mask. Leave the mask to keep the saved value, type a new value to change it, or clear the field and click Save Config to delete it.

Payment

Payment Action: when the money is taken. Default: Authorize and capture.

Webhook

The webhook confirms payments even when the customer closes the browser right after paying, and records refunds made in the Razorpay Dashboard. In the Razorpay Dashboard go to Account & Settings > Webhooks and add a webhook in Test mode and another one in Live mode. Use the URL shown in Webhook URL: in the Status row, the storefront address of the default store view. It looks like https://your-store/wcprazorpaypayment/checkout/webhook. Copy the URL exactly as the settings show it. Enter a secret of your choice in Razorpay and select these events:

Webhook Secret: the secret you entered when creating the webhook. Use the same secret for the Test and the Live webhook, because the module has one field for both. The secret is read for the store view that serves the webhook address, so enter it in the Default Config or for the website of the default store view. Webhooks without a valid signature are rejected. Without the webhook, a payment is confirmed only when the customer returns from the popup, or when the payment of the same order is started again.

Advanced

Debug logging: the log is written to var/log/razorpay_p_debug.log.php in the Magento folder. The file cannot be opened from the web and is rotated at 5 MB. Errors and warnings are always logged; this option adds the debug details. Keys are never logged, and error descriptions from Razorpay are left out. Default: No.

Log: shows the size and the latest entries of the log. Click Clear log to empty it.

Delete settings on uninstall: when Yes, uninstalling the module with its data removes the module settings and the log (see Uninstall). Payment and refund history always remains. Default: No.

Conditions

Payment from Applicable Countries: All Allowed Countries (default) or Specific Countries, checked against the customer's billing address.

Payment from Specific Countries: the countries in which Razorpay is offered when the option above is Specific Countries.

Minimum Order Total and Maximum Order Total: Razorpay is hidden when the cart total in the base currency is outside these limits. Empty means no limit. In Maximum Order Total do not enter 0.00: Magento treats it as a limit and hides the method.

Currencies are not limited by the module. Customer groups are not configured here.

Checkout

At the payment step the customer chooses the payment method (by default UPI, Cards, NetBanking) and sees the description and the note You will be redirected to Razorpay to complete your payment. After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The module creates a Razorpay order for the order total in the order currency and opens the Razorpay payment page of your store. The Razorpay Checkout popup opens there automatically, with the customer's name, e-mail and phone filled in. The popup shows the name of your store and Order # with the order number. In test mode the page shows TEST MODE — no real payment.

The page also has the Pay Now button to open the popup again and Cancel payment and return to cart, which cancels the order (the stock goes back) and restores the cart. If the popup is closed, the customer sees Payment window closed. You may try again. After a failed attempt the message is Payment failed. You may retry in the payment window. If the Razorpay script cannot be loaded, the message is The payment window could not be loaded. Please try again.

After a successful payment the module checks the Razorpay signature, fetches the payment from the Razorpay API and compares the amount and currency with the order. The order is marked paid only after Razorpay confirms it. Magento then creates the invoice with the Razorpay payment ID as the transaction ID, moves the order to Processing and sends the order e-mail. The customer sees the standard order success page.

If the signature is valid but the payment cannot be fetched at that moment, the order goes On Hold without an invoice, the customer returns to the payment page with Payment verification is pending or failed. A signed notification may complete it., and the webhook confirms the payment later. After an authorization or a review the page shows Your payment is awaiting confirmation or merchant review. Do not submit another payment.

If the payment of the same order is started again, the module reuses its Razorpay order when the amount, currency and mode are unchanged. If that Razorpay order was already paid, the module confirms that payment instead of asking for a second one. If the cart of the order was already paid, the customer sees This cart was already paid.

If Razorpay cannot start the first payment of an order, the order is cancelled, the cart is restored and the customer sees Razorpay is temporarily unavailable. Please try again shortly. in the cart. The technical reason is written to the log. An order in Pending Payment can also be cancelled in Magento, by you or by the Magento cron after the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings). A payment that arrives later does not reopen it (see Orders and refunds).

The module works with the standard Magento checkout and takes one-time payments only. It has no subscriptions or recurring payments, no saved cards, no Razorpay Magic Checkout, Payment Links or Route (split payments), and no offer or affordability widgets. Razorpay is not offered for orders created in the Admin.

Orders and refunds

Order statuses

Pending Payment: the order was placed, but Razorpay has not confirmed a payment yet. There is no invoice. A failed attempt adds a note and the customer can pay again.

Processing: the payment was captured and confirmed. The invoice has the Razorpay payment ID (pay_...) as the transaction ID, and a note shows the mode, the payment ID and the amount. The order then continues in the usual Magento way.

On Hold after an authorization: the payment was only authorized (Authorize only). There is no invoice. Capture it to complete the order.

On Hold after a mismatch: Razorpay reported a different amount or currency than the order total. No invoice is created. The note shows the amount paid and the amount expected. Check the payment and refund it in the Razorpay Dashboard if needed.

On Hold, not verified: the signature was valid, but the payment could not be verified with the Razorpay API at that moment. The note says the order is waiting for a signed webhook. There is no invoice.

Canceled: the customer cancelled the payment, the payment could not be started, or the order was cancelled in Magento. A payment that arrives later does not reopen the order: an authorized payment is not captured, and the note asks you to review it and refund it manually. For an authorized payment on a cancelled order, the note says the money stays reserved until you release it in the Razorpay Dashboard or it expires, because Razorpay has no order cancellation API.

Closed: the payment was fully refunded with a credit memo.

If an additional payment arrives for an order or a cart that is already paid, the order is not changed. A note asks you to review it and refund it in the Razorpay Dashboard. The notes are order comments that the customer does not see.

Razorpay payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title, Razorpay payment (the payment ID), Mode, Amount and Refund status. Below them are the lines Razorpay attempt # (Razorpay order ID, mode, status, amount) and Razorpay refund # (refund ID, amount, status). The amounts in these two lines are in the smallest unit of the currency, for example paise for INR. On the storefront the customer sees only the payment method title.

Capture (Authorize only)

Open the order and click Capture Razorpay payment on the Information tab. This needs the Admin role right to capture orders. The full authorized amount is captured in the mode it was authorized in. The invoice is created only when Razorpay confirms the capture, and the order then moves to Processing. If the answer is uncertain, Magento shows Capture not confirmed. Reconcile the payment before retrying. The next attempt first checks the payment with Razorpay and does not send a second capture. A capture made in the Razorpay Dashboard completes the order by the webhook. The standard Invoice page with Capture Online does not capture: it shows Use Capture Razorpay payment on the order. The invoice is created when capture is confirmed.

Refunds

Open the order, go to the Invoices tab, open the invoice and click Credit Memo. Choose the items and amounts to refund and click Refund. The money is sent back through Razorpay. Full and partial refunds are supported. A credit memo started from the order page instead of the invoice offers only Refund Offline, which does not send money back through Razorpay.

The refund is made in the order currency, up to the amount Razorpay charged minus the amounts already refunded. A larger amount gives Invalid refund amount or currency; exceeds captured funds. The refund is sent with the keys of the mode the payment was made in. If they are not set, Magento shows Stored-mode credentials are missing. After a successful refund Magento records it with the Razorpay refund ID (rfnd_...) as the transaction ID. A full refund closes the order. Refunds are available once the payment is captured and the order has an invoice.

In zero-decimal currencies such as JPY, Magento can keep a total with a fraction, while Razorpay charges a whole amount: an order of 1234.56 is charged as 1235. Each credit memo then refunds the rounded difference of the total refunded so far, and the last credit memo refunds exactly what is left of the charge, so the customer gets back the whole 1235.

If Razorpay does not confirm the refund, Magento shows Razorpay did not confirm the refund. Reconcile before retrying. and the credit memo is not created. When Razorpay clearly refused the request, you can correct the problem and try again. When the answer was uncertain, for example after a network error, further online refunds of the order are blocked with An earlier refund is unconfirmed. Reconcile it before retrying., so the money cannot be sent twice. The same protection applies to a refund accepted by Razorpay without a credit memo: An accepted refund has no native credit memo. Reconcile it before requesting another. The block does not clear by itself. Check the refund in the Razorpay Dashboard and make further refunds of this order there.

Refunds made in the Razorpay Dashboard arrive by the webhook. A refund in the order currency that fits the refundable amount is recorded once as an offline credit memo with the Razorpay refund ID, in the order currency. The credit memo holds only the amount, and the product stock is not changed. A refund in another currency, or larger than the refundable amount, gets a note that it requires manual reconciliation and no credit memo.

If the credit memo cannot be saved, the order gets a note that the refund could not be recorded and must be reconciled manually, and further online refunds of the order are blocked as described above.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Razorpay Payment is the first row of the VibeFox Razorpay Payment group in Stores > Configuration > Sales > Payment Methods, above the settings. Paste the key into License key and click Activate. After that the block shows the key masked, the status (for example the date the license is active until and your domain) and the buttons Check now to check the status again, Change key to enter another key and Remove key to remove the key from this store. Below them are the line Product: magento-payment-razorpay and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Payment Methods configuration section can change the key. The texts of the block follow the Admin interface locale (English and Russian are included).

If the key is not accepted, the block says why, for example Key not found, This key belongs to another product, Domain limit reached or License expired on a date. After the store address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the module keeps working on the last known status.

One key works on one domain: the domain of the default store view, also when the installation has several websites or stores. Removing the key from the store does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, Razorpay is not shown to customers at checkout. If a payment is started anyway, the order is cancelled, the cart is restored and the customer sees This payment method is not available. Please choose another one. The Magento storefront does not know that you are logged in to the Admin, so the payment method is hidden for you too: you can set up the module before you buy a key, but not test it at checkout. A reminder appears in the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides it for 7 days. Existing orders are not affected: payments already started are still confirmed, and captures and refunds work.

When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data always removes the license key and license status.

Troubleshooting

Razorpay does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that the current mode has both keys: Test Key ID and Test Key Secret in test mode, Live Key ID and Live Key Secret in live mode. Check Payment from Applicable Countries and Payment from Specific Countries against the customer's billing address, and Minimum Order Total and Maximum Order Total.

The payment went through, but the order stays Pending Payment: the webhook is not working. In the Razorpay Dashboard check that the webhook exists in the mode you use (Test or Live), that its URL is exactly the one shown in Webhook URL: and that the events are selected. Check that Webhook Secret is the same secret as in Razorpay. The order is also confirmed when the customer returns from the popup.

Webhook answers Webhook secret not configured: Webhook Secret is empty for the store view that serves the webhook address. Enter the secret of the Razorpay webhook.

Webhook answers Invalid signature or Missing signature: the secret in the settings differs from the secret of the Razorpay webhook. Enter the same secret in both places, for the Test and the Live webhook.

Webhook answers Retry later: the order was being updated by another request at the same moment, or an error occurred while it was being saved. Razorpay delivers the event again automatically. The reason is in the Log.

The webhook URL shows Method not allowed in the browser: this is normal. The URL accepts only POST requests from Razorpay.

Webhooks fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the webhook URL too. Razorpay delivers the event again later, and the order is also confirmed when the customer returns from the popup.

The customer is back in the cart with an error after Place Order: look at the Log field in the module settings. Errors are logged even with Debug logging set to No. Wrong keys, an unsupported currency or another refusal by Razorpay all show Razorpay is temporarily unavailable. Please try again shortly. to the customer. The order of that attempt is cancelled.

The popup does not open: the Razorpay Checkout script was blocked by a content blocker or the connection. The customer sees a message and can try again with Pay Now.

Order is On Hold after payment: read the order notes (see Order statuses), then capture the payment, wait for the webhook, or refund the payment in the Razorpay Dashboard.

Capture or refund fails with a message about credentials: the payment was made in Test or Live mode, and the keys of that mode are not set for the website of the order. Enter them and try again.

The Refund button is missing on the credit memo: start the credit memo from the invoice (Invoices tab), not from the order page. An order without an invoice (for example On Hold after a mismatch) cannot be refunded online; refund it in the Razorpay Dashboard.

The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.

Uninstall

Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:

Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_RazorpayPayment. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_RazorpayPayment to remove the data, then bin/magento module:disable Vibefox_RazorpayPayment, delete the folder app/code/Vibefox/RazorpayPayment and run bin/magento setup:upgrade.

The license key and license status are always removed. If Delete settings on uninstall is Yes, the module settings and the log are removed too. If it is No, the settings are kept for a re-install. The Razorpay transactions and refunds are always kept, so orders paid before can still be captured and refunded after a re-install. Existing orders keep their invoices, payment notes and transaction IDs.

Razorpay is a trademark of its respective owner. This module is not affiliated with or endorsed by Razorpay.