VibeFox CCAvenue for Adobe Commerce — Ajuda

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 OpenSSL extension (used to encrypt the request and decrypt the response). The module package also requires the cURL and JSON extensions.

CCAvenue account: you need a CCAvenue merchant account with a Merchant ID, an Access Code and a Working Key. The Access Code and Working Key are issued for a website domain, so generate them for the domain of this store. CCAvenue uses the same credentials for the test environment; test access must be enabled for your account by CCAvenue. The module uses the CCAvenue India endpoints.

Currency: the order total is sent to CCAvenue in the order currency, the currency the customer sees at checkout. CCAvenue accounts accept INR by default; other currencies require multi-currency processing on your CCAvenue 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-ccavenue-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/CcavenuePayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_CcavenuePayment 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 CCAvenue 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 the Merchant ID, Access Code and Working Key from your CCAvenue dashboard, set Enable to Yes, click Save Config and place a test order while Test mode is Yes. When you are ready, set Test mode to No and click Save Config to accept real payments.

The module adds the CCAvenue payment method 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 one table for the CCAvenue payment attempts. The return URL is sent with every payment, so nothing has to be configured in CCAvenue.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox CCAvenue Payment, in the standard Magento configuration form. 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. Remove data on uninstall is read from the Default Config only. Save Config saves the whole page.

If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Title or a title longer than 128 characters (Enter a title for the payment method (1 to 128 characters).), a Sort order that is not a whole number (Sort order must be a whole number.), or a Minimum Order Total or Maximum Order Total that is not a number of 0 or greater (Order total must be a number, 0 or greater.). Use a dot as the decimal separator, for example 9.99.

While Enable is Yes, the Return URL row shows CCAvenue: Merchant ID, Access Code or Working Key is missing. The payment method stays hidden at checkout. when one of the credentials is empty, and CCAvenue test mode is on. No real payment is taken. while test mode is on. These warnings check the Default Config values.

General

Enable: shows or hides CCAvenue at checkout. It is shown only when the Merchant ID, Access Code and Working Key are all set. Default: No.

Title: the payment method name customers see at checkout. It is also stored in the order. Default: CCAvenue. Required, at most 128 characters.

Description: shown in the payment method list at checkout, under the method when the customer selects it. Default: Pay securely via Credit/Debit card, Net Banking, UPI or Wallet through CCAvenue.

Sort order: the position among the payment methods at checkout. A whole number. Default: 0.

Credentials

Log in to your CCAvenue merchant dashboard (M.A.R.S.) and open Settings > API Keys. Generate the Access Code and Working Key for the domain of this store. Spaces in the credentials are removed on save.

Merchant ID: your numeric CCAvenue Merchant ID. Digits only. If it contains anything other than digits, the message CCAvenue: the Merchant ID must contain digits only — the previous value was kept. is shown on save, the previously saved value stays and the other settings are saved. Other currencies than INR require multi-currency processing on your CCAvenue account.

Access Code: the Access Code for this website (Settings > API Keys).

Working Key: the Working Key (encryption key) for this website. It encrypts the payment request and is the only way to verify the CCAvenue response, so keep it secret.

Magento stores the Access Code and the Working Key encrypted and shows only a mask (******) after saving. Leave the mask unchanged to keep the saved value, type a new value to change it. To delete a saved value, clear the field and click Save Config.

Test mode: sends customers to the CCAvenue test environment (test.ccavenue.com) instead of secure.ccavenue.com. CCAvenue uses the same Merchant ID, Access Code and Working Key for test and live; test access must be enabled for your account by CCAvenue. While it is on, customers see Sandbox mode: no real payment is taken. under the payment method. Default: Yes. Set it to No for real payments.

Restrictions

Payment from Applicable Countries: All Allowed Countries offers CCAvenue for every country your store allows, Specific Countries only for the countries below.

Payment from Specific Countries: offer CCAvenue only for billing addresses in these countries.

Minimum Order Total: offer CCAvenue only from this order total, in the base currency of your store. 0 or empty means no minimum. Default: 0.

Maximum Order Total: offer CCAvenue only up to this order total, in the base currency. 0 or empty means no maximum. Default: 0.

Advanced

Debug log: writes CCAvenue events to var/log/ccavenue_p_debug.log.php in the Magento folder: payment results and errors. The file cannot be opened from the web. At 5 MB it is moved to ccavenue_p_debug.old.log.php and a new file is started. Keys, tokens, card data, e-mails and addresses are not logged. Default: No. Nothing is written while it is off, errors included.

Remove data on uninstall: when Yes, uninstalling the module with its data deletes the module settings and the log (see Uninstall). The license key is always removed. The CCAvenue payment attempts, the orders and their history always stay. Default: No.

Return URL

Below the sections, the Return URL row shows, for reference, the address CCAvenue returns the customer to. It looks like https://your-store/wcpccavenuepayment/checkout/back, with the note CCAvenue returns the customer by encrypted form POST. Refunds are managed in the CCAvenue dashboard. Each payment sends the return URL of the store view where the order was placed (as the redirect and cancel URL), so there is nothing to configure in CCAvenue. It must belong to the domain registered with CCAvenue.

Debug log: the last row shows the size and the latest entries of the log, or The log is empty. Click Clear log to empty it.

Checkout

At the payment step the customer chooses the payment method (by default CCAvenue) and sees the description and the note You will be redirected to CCAvenue to complete the payment securely. After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The next page shows You are being redirected to CCAvenue. and sends the customer to the CCAvenue payment page. If that does not happen, the customer clicks Pay via CCAvenue.

Each attempt gets a new CCAvenue order ID made of the Magento order number, the time and a random suffix, because CCAvenue rejects a reused order ID. The order total and currency, the billing details, the shipping address (the billing address when the order has none) and a secret token of the attempt are sent in the encrypted request. Names and addresses are cleaned to the characters and lengths CCAvenue accepts; country and state are sent as names and the phone as digits. The customer chooses the card, Net Banking, UPI, wallet or EMI on the CCAvenue page.

After the payment, CCAvenue returns the customer with an encrypted response. The order is marked paid only after CCAvenue confirms it: the response must decrypt with your Working Key, carry a CCAvenue order ID issued by your store and the token of that attempt, and show the same amount and currency as were sent and as the order total. The return is handled even when Enable is No or the license is not active.

After a successful payment Magento creates the invoice with the CCAvenue tracking ID as the transaction ID, the order moves to Processing and the order e-mail is sent. The customer sees the standard order success page. For an Awaited payment the order stays in Pending Payment and the success page shows Your CCAvenue payment is awaiting bank confirmation. After an amount or currency mismatch it shows Your CCAvenue payment is being reviewed by the store. A customer who comes back in another browser lands on the home page.

If the payment fails, the order is cancelled (the stock goes back), the cart is restored and the customer is back in the cart with Payment was not completed. You may try again. If the customer cancels on the CCAvenue page, the message is Payment was cancelled. You may try again. The customer can pay again or choose another payment method. If the response cannot be verified, the customer sees We could not confirm the CCAvenue payment result. and the order stays in Pending Payment. If the payment cannot be started, the order is cancelled, the cart is restored and the customer sees We could not start the CCAvenue payment. Please try again or choose another payment method. If the cart already has a paid order, a new attempt goes straight to the success page instead of a second payment.

The result is taken only from the customer's return from CCAvenue: there are no server-to-server notifications and no status requests. If the customer closes the browser before returning, the order stays in Pending Payment; check the payment in the CCAvenue dashboard. Magento cancels orders that stay in Pending Payment longer than the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings). If a successful payment is reported later for a cancelled order, the order is not invoiced: it stays Canceled and a note asks you to review the payment.

The module works with the standard Magento checkout. It has no online refunds from Magento, no saved cards, subscriptions or recurring payments, no on-site card form, and no support for CCAvenue UAE or other regional platforms. CCAvenue is not offered for orders created in the Admin.

Orders and refunds

Order statuses

Pending Payment: the order was placed and the customer was sent to CCAvenue, but no verified result has arrived yet, or CCAvenue reported the payment as Awaited (the bank has not confirmed it yet). There is no invoice. A note shows the tracking ID of an Awaited payment. Verify it in the CCAvenue dashboard before fulfilling. A later response with the same tracking ID is still applied: Success invoices the order, Failure or Aborted cancels it. A failure of another attempt does not cancel an order that waits for an Awaited payment.

Processing: CCAvenue confirmed the payment. The invoice is created with the CCAvenue tracking ID as the transaction ID, and a note says CCAvenue payment confirmed. Tracking ID: followed by the ID.

On Hold: CCAvenue confirmed a payment whose amount or currency differs from the order total or from what was sent (for example, the cart was changed in another tab), or the customer paid after the order had been changed. No invoice is created. The note shows the received and the expected amount. Check the payment in the CCAvenue dashboard, then fulfil the order or refund the payment.

Canceled: the payment failed or was cancelled on the CCAvenue page, the payment could not be started, or the order was cancelled in Magento. The note shows the CCAvenue status.

A paid order is never changed by a later result. If another successful payment arrives for an order or a cart that is already paid (for example from two browser tabs), nothing is invoiced again. A note asks you to review it in the CCAvenue dashboard and refund the duplicate there. The notes are order comments that the customer does not see.

CCAvenue payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, when known, CCAvenue order ID, CCAvenue tracking ID, CCAvenue status, Bank reference, Payment mode, Amount sent, Amount received and Environment (test or live), with the line Refunds: Refunds are managed in the CCAvenue dashboard. The customer sees only the payment method title.

Refunds

Refunds from Magento are not sent to CCAvenue. Refund the payment in the CCAvenue dashboard, then create a credit memo for the invoice with Refund Offline to record the refund in Magento.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox CCAvenue Payment is the first row of the VibeFox CCAvenue 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-ccavenue 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, CCAvenue 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 We could not start the CCAvenue payment. Please try again or choose another payment method. 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 when the customer returns from CCAvenue.

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

CCAvenue does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that all three credentials are set: Merchant ID, Access Code and Working Key. The Return URL row shows a warning when one is missing. Check Payment from Applicable Countries and Payment from Specific Countries against the customer's billing address, and Minimum Order Total and Maximum Order Total. CCAvenue is not offered for an order total of zero.

The payment went through, but the order stays Pending Payment: no verified result reached your store. The customer did not return from CCAvenue, for example because the browser was closed, or the response could not be verified. The module has no server-to-server notifications, so CCAvenue does not send the result again. Check the payment in the CCAvenue dashboard, then invoice or cancel the order manually.

Every payment ends with We could not confirm the CCAvenue payment result: the response cannot be decrypted. The Working Key is wrong, belongs to another domain or was copied with extra characters. Generate the keys for the domain of this store and enter them again. Turn on Debug log and look at the log in the last row of the settings group.

CCAvenue shows an error before the payment page: check that the Access Code and Working Key were generated for this domain, that the return URL belongs to the domain registered with CCAvenue and, in test mode, that CCAvenue enabled test access for your account. For a currency other than INR, multi-currency processing must be enabled on your CCAvenue account.

The customer is back in the cart with We could not start the CCAvenue payment: one of the credentials is missing, the module was disabled or the license is not active. The order of that attempt is cancelled.

The Merchant ID does not change on save: the value contains something other than digits. Enter only the numbers of your Merchant ID.

A payment was made but the order is On Hold or Canceled: the paid amount or currency did not match the order, or the payment arrived after the order had been cancelled, for example by the Pending Payment Order Lifetime cron. Read the order notes and check the payment in the CCAvenue dashboard.

Returns fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the return URL too. The result of such a payment does not reach the store, and the order stays in Pending Payment. Check the payment in the CCAvenue dashboard.

There is no Refund button on the credit memo: this is normal. The module has no online refunds. Refund the payment in the CCAvenue dashboard, then use Refund Offline.

For developers: the data sent to CCAvenue can be changed before encryption with the Magento event ccavenue_p_request_params (transport params and the order), for example merchant_param2 to merchant_param5. Do not change amount, currency, order_id or merchant_param1.

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_CcavenuePayment. It removes the data and the code.

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

The license key and license status are always removed. If Remove data 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 CCAvenue payment attempts are always kept, so the return of an old payment is still handled after a re-install. Existing orders keep their invoices, payment notes and transaction IDs.

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