VibeFox Redsys for Adobe Commerce — Guida

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.

Redsys merchant account: your bank (the acquirer that gave you the Redsys virtual POS) gives you the merchant code (FUC), the terminal number and access to the Redsys administration panel, where the SHA-256 secret key of each environment is shown. The key of the test environment is different from the real one. The online notification (HTTP) must be active for your terminal. Ask your bank if you are not sure.

Currency: the order currency must be one of the currencies the module supports (see Configuration), and your Redsys terminal must be enabled by the bank for it. Most terminals accept EUR only.

Reachable store: Redsys must be able to reach your store from the internet, without a login or a firewall block, to deliver the payment notifications.

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-redsys-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/RedsysPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_RedsysPayment 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 Redsys Gateway. 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 merchant code, terminal and the secret key of the test environment, set Enable to Yes, click Save Config and place a test order. When you are ready, enter the live secret key, set Test mode to No and click Save Config.

The module adds the Credit/Debit Card (Redsys) 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 two tables, for the Redsys payment attempts and for the refunds. The notification URL is sent with every payment. Nothing has to be copied into the Redsys panel.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Redsys Gateway, 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. Delete settings on uninstall is read from the Default Config only, and the license block is shown only in the Default Config scope. Save Config saves the whole page.

In some cases Magento shows an error and nothing on the page is saved: an empty Title (Enter a title for the payment method.), a Sort Order that is not a whole number (Sort order must be a whole number.) and 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 point as the decimal separator, for example 9.99.

Status

The first row after the license block shows Notification URL: with the address described below. While Enable is Yes in the Default Config, the same row also warns you, based on the Default Config values:

Notification URL: Redsys reports every payment to this address of your store. The page shows the address of the default store view, which looks like https://your-store/wcpredsysgateway/checkout/notify. The module sends the address of the store view of the order to Redsys with every payment, so there is nothing to copy into the Redsys panel. The online notification (HTTP) must be active for your terminal. Ask your bank if orders stay in Pending Payment after a successful payment. Notifications without a valid signature are rejected. Without the notification, the order is not marked paid.

Payment method

Enable: shows or hides Redsys at checkout. It is shown only when the merchant code, the terminal and a valid key of the current mode are set. Default: No.

Title: the payment method name customers see at checkout. It is also stored in the order. Default: Credit/Debit Card (Redsys). Required.

Description: shown in the payment method list at checkout. Default: Pay securely with your credit or debit card via Redsys.

Redsys account

Merchant code (FUC): your Redsys merchant code, up to 9 digits. Anything that is not a digit is removed when you save.

Terminal: the terminal number assigned by your bank, up to 3 digits. Anything that is not a digit is removed when you save. Default: 1. An empty field is saved as 1.

Live SHA-256 secret key: the Base64 SHA-256 key of the real (production) environment, shown in the Redsys administration panel. It is used when Test mode is No.

Test mode: SIS-T test environment. Use the separate key issued by your bank. A test payment received while live mode is active is held without a paid invoice. New payments go to the Redsys test environment (SIS-T) and are signed with the test key. Default: Yes. Set it to No to take real payments. While it is on, customers see TEST MODE — no real payment. Do not ship test orders. under the payment method.

Test SHA-256 secret key: the Base64 SHA-256 key of the test environment.

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

Each payment remembers its environment and the merchant code and terminal it was started with. Its notifications and refunds use that environment's key, also after you switch from test to live.

Payment page and orders

Commerce name: the store name shown on the Redsys payment page. Maximum 25 characters; HTML is removed. When it is empty, the name of your store is sent, cut to 25 characters: Store Name from Stores > Configuration > General > General > Store Information or, if that is empty, the name of the Magento store.

Order Status After Payment: what happens with the order after a successful payment. The invoice is created in all three cases. A value that is not in the list is rejected with Select a valid order status.

Log and uninstall

Debug logging: also writes the details of refund requests and responses to var/log/rdsg_debug.log.php in the Magento folder. The file cannot be opened from the web. Errors and warnings are always logged, also when this option is No. Keys, signatures and customer addresses are never logged. Default: No.

Log: shows the size and the latest entries of the log. Click Clear log to empty it. The log is rotated at 5 MB.

Delete settings on uninstall: only settings and the log are deleted. Payment and refund history always remains. Uninstalling the module with its data then deletes the gateway settings and the log (see Uninstall). Default: No.

Conditions

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

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

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

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

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

Supported currencies

EUR, USD, GBP, JPY, CHF, CAD, AUD, NZD, NOK, SEK, DKK, PLN, CZK, HUF, BGN, RON, ILS, INR, MYR, SGD, THB, SAR, ZAR, RUB, BRL, MXN, ARS, CLP, COP, PEN, CNY, TWD. The payment method is hidden for carts in other currencies.

Checkout

At the payment step the customer chooses the payment method (by default Credit/Debit Card (Redsys)) and sees the description and the note You will be redirected to Redsys 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 next page shows Redirecting to Redsys for payment… and goes on to the Redsys payment page of your bank. If the browser does not go on by itself, the customer clicks Pay via Redsys.

On the Redsys page the customer pays by card with 3-D Secure, or by Bizum or another method your bank has enabled for the terminal. The page uses the language of the store view (Spanish, English, Catalan, French, German, Italian, Portuguese and more), or English for other languages. The amount is the order total in the minor units of the order currency, for example EUR 43.45 as 4345, and JPY or CLP without decimals. The payment is described as Order with the order number and your store name.

The order is marked paid only after Redsys confirms it by the signed notification. Magento then creates the invoice with the Redsys order number (Ds_Order) as the transaction ID, and the order e-mail is sent. The customer's return to the store never pays an order. A customer who returns after the confirmation sees the standard order success page. If the notification has not arrived yet, a Redsys payment status page shows Redsys is confirming your payment. Please do not pay again. with the current payment status, the button Check again and the link Back to checkout. If the order is held for review, the page shows Your Redsys payment is being reviewed by the store. Do not pay again. A customer who comes back in another browser lands on the cart and sees no order data.

If the customer cancels or the payment is refused, the order is cancelled (the stock goes back), the cart is restored and the customer is back in the cart with The Redsys payment was not completed. Please try again or choose another payment method. Each new attempt gets a new Redsys order number.

If the payment cannot be started, the order is cancelled, the cart is restored and the customer sees a short message in the cart, for example Redsys could not be started., Redsys is not available. or Unsupported order currency. If the cart already has a payment, no second payment form is built: the customer sees its status.

Magento cancels orders that stay in Pending Payment longer than the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings). The module does not stop such a cancellation. If Redsys later reports a payment for a cancelled order, the order is not invoiced and not opened again: a note asks you to check the stock and reconcile or refund the payment in the Redsys administration panel.

The module works with the standard Magento checkout. It takes one-time payments, authorised and captured at once on the Redsys page. It has no card form on your own site (InSite or iframe), no saved cards, one-click payments or tokenisation, no subscriptions or recurring payments and no pre-authorisation with later capture. Redsys 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 Redsys, but no result has arrived yet, or Redsys reports that the payment is still in progress (responses 9997 to 9999, with a note). There is no invoice.

Processing, Complete or On Hold: the payment was confirmed (responses 0000 to 0099). The status follows Order Status After Payment. The invoice is paid, with the Redsys order number as the transaction ID, and a note shows the environment, the Redsys order number, the authorisation code and the response code.

On Hold without an invoice: Redsys reported a different amount or currency than the order total, or a test payment arrived while the store is in live mode (no real money was charged). The note explains it. Check the payment in the Redsys administration panel and refund it there if needed. A payment that arrives while you have put the order on hold yourself also leaves the order on hold, with a note and without an invoice.

Canceled: the payment was refused or cancelled, it could not be started, or the order was cancelled in Magento. The note shows the response code, with a short reason for frequent codes, such as Insufficient funds, Card expired or Cancelled by the customer. A refused result of an older attempt does not cancel an order that waits for a newer attempt.

Closed: the order was fully refunded.

A cancelled order is never opened again, and a refused payment never changes a paid order. If a second, different payment arrives for a cart that is already paid, the order and the original payment are not changed. A note asks you to refund the duplicate in the Redsys administration panel. The notes are order comments that the customer does not see.

Redsys payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, when known, Redsys payment (the Redsys order number), Mode, Authorization code, Response, Amount / ISO numeric and Refund status, then one Redsys attempt row for each Redsys order number issued for the order and one Redsys refund row for each refund. The customer sees only the payment method title.

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 the Redsys REST API. 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 Redsys.

The refund is made in the order currency, up to the amount Redsys charged minus the amounts already refunded. In currencies without decimals, such as JPY and CLP, Magento can keep totals with decimals while Redsys charged the rounded total. The module rounds the credit memos so that they add up to the charge, and the credit memo that completes the refund returns exactly what is left. It is sent to the environment the payment was made in (test or live), signed with that environment's key, and the response signature is checked. If Redsys does not accept the refund, Magento shows the error and the credit memo is not created. After a successful refund Magento records it on the order, with the Redsys order number and the refund number as the transaction ID. A full refund closes the order. Refunds are available once Redsys has confirmed the payment and the order has an invoice.

Redsys has no protection against a repeated refund request, so the module keeps its own record of each request. When the result of a request is not certain, for example because Redsys could not be reached or the answer could not be verified, Magento shows Redsys refund was not confirmed. Reconcile in Redsys administration before retrying. The module then sends no more online refunds for this payment, so that the money is never sent back twice. Check the payment in the Redsys administration panel, refund there if needed and record the refund with Refund Offline. When Redsys answers with a SIS error code or refuses the refund with a response code, nothing was refunded and the same message is shown, but online refunds stay available: check the log for the code, correct the problem and try again.

Orders on hold without an invoice, duplicate payments and late payments are refunded in the Redsys administration panel. Refunds made in the panel are not recorded as refunds of the module. When Redsys sends a notification for them, a note is added to the order. The order and credit memos are not changed automatically. Create a credit memo with Refund Offline if needed.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Redsys Gateway is the first row of the VibeFox Redsys Gateway 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-redsys 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, Redsys 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 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

Redsys does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, that Merchant code (FUC) has up to 9 digits and Terminal up to 3 digits, and that the current mode has a valid key: Test SHA-256 secret key in test mode, Live SHA-256 secret key in live mode. Check that the currency of the cart is in the list of supported currencies. 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 Redsys notification did not reach your store. Ask your bank to check that the online notification (HTTP) is active for your terminal. Check that the address shown in Notification URL can be reached from the internet without a login or a firewall block. Look at the Log field on the settings page: rejected notifications are always logged.

Notification answers Forbidden: the signature did not match the secret key of the environment the payment was started in, or the merchant code in the notification is not the one of the payment. Check that the secret keys and the merchant code in the settings are the ones of your terminal.

Notification answers Order not found: the notification was signed correctly, but no payment of this store uses that Redsys order number.

Notification answers Busy: the order was being processed by another request at the same moment, or the order could not be saved. Redsys retries the notification. The log shows the reason.

Notification answers Bad request: the request had no or broken Redsys parameters, or it was not a POST request. It did not come from Redsys in the expected format. Opening the address in a browser shows this answer, and this is normal.

Notifications fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the notification URL too. The order stays Pending Payment until a notification reaches the store.

A payment was made but the order is On Hold or Canceled: the paid amount or currency did not match the order, a test payment arrived in live mode, 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 Redsys administration panel.

Test payments do not confirm orders in live mode: a test payment never pays an order while Test mode is No. The order is put on hold with a note instead. Use test mode with the test key for test payments.

The Refund button is missing on the credit memo: start the credit memo from the invoice, not from the order page. An order without an invoice has no online refund. Refund the payment in the Redsys administration panel.

Refund fails: read the error. Invalid refund amount or currency; exceeds captured funds. means that the amount is above what is left of the payment. Stored-mode Redsys credentials are missing. means the merchant code, the terminal or the key of the environment of the payment is missing. No matching paid Redsys invoice. Review/refund in Redsys administration. means the invoice does not belong to a confirmed Redsys payment. An earlier Redsys refund is unconfirmed. Reconcile it before retrying. and An accepted Redsys refund has no native credit memo. Reconcile it before requesting another. mean that an earlier request must be checked in the Redsys administration panel first (see Refunds). Payment is being updated. Try again shortly. means another request is working on the order at this moment.

Your terminal accepts a currency that is not in the list: developers can change the list of currencies with the Magento event rdsg_currency_codes (transport with codes). Add a currency only if your bank has enabled it for the terminal. The payment parameters can be extended before they are signed with the event rdsg_merchant_parameters (transport with params, and the order). The amount, currency, order number, merchant code, terminal and transaction type cannot be changed.

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

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

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

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