VibeFox Redsys for WooCommerce — Help

Requirements

WordPress: 6.2 or later.

WooCommerce: 8.0 or later, installed and active. The plugin refuses to activate without it.

PHP: 8.0 or later.

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.

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

Reachable site: Redsys must be able to reach your site 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

1. In WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the wcp_redsys_gateway folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Payments > Redsys > Manage, or click Settings under the plugin name on the Plugins page.

4. Enter your VibeFox license key in the license block at the top of the page and click Activate.

5. Enter your merchant code, terminal and the secret key of each environment (see Configuration).

6. Turn on Enable/Disable. Test a payment with Test Mode on, then untick Test Mode to accept real payments.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > Redsys. Above the fields the page warns you when the merchant code is missing or not made of digits, when a secret key is not a valid Redsys SHA-256 key, when the key of the current mode is empty (the payment method is then hidden at checkout) and when the store currency is not supported. While test mode is on it shows Test mode is active: payments go to the Redsys test environment (SIS-T), no real money is charged. After you save, the warnings follow the new settings at once. In the list of payment methods, Redsys is marked as needing setup until the merchant code, the terminal and the key of the current mode are valid.

General

Enable/Disable: Enable Redsys Gateway turns the payment method on or off. Default: off.

Title: the payment method name customers see at checkout. Default: Credit/Debit Card (Redsys).

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

Redsys account

Your bank gives you the merchant code, the terminal and access to the Redsys administration panel, where the SHA-256 secret key of each environment is shown. The section links to the Redsys administration panel.

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

Terminal Number: the terminal number assigned by your bank, up to 3 digits. Default: 1. An empty field is saved as 1.

Secret Key (SHA-256) — live: the Base64 SHA-256 key of the real (production) environment. It is used when test mode is off.

Test mode (SIS-T)

The Redsys test environment has its own secret key. The section shows the public Redsys test data: merchant code 999008881, terminal 1, key sq7HjrUOBfKmC576ILgskD5srU870gJ7, card 4548 8100 0000 0003, expiry 12/49, CVV 123. No real money is charged in test mode.

Test Mode: Enable test mode sends payments and refunds to the Redsys test environment (SIS-T) and signs them with the test key. Default: on. Untick it to take real payments. While it is on, the checkout shows TEST MODE: Redsys test environment, no real money is charged. under the payment method.

Secret Key (SHA-256) — test: the Base64 SHA-256 key of the test environment. Use your own test key or the public test key above.

Payment page and orders

Commerce Name: the shop name shown on the Redsys payment page, at most 25 characters. Default: the name of your site, cut to 25 characters.

Order Status After Payment: the order status set after a successful payment. The status is set once, so the customer receives one e-mail.

Payment notifications

Redsys reports every payment to the notification address of your store. It looks like https://your-site/wc-api/rdsg_redsys/ and is shown in this section. The plugin sends it 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 Pending payment after a successful payment. Notifications without a valid signature are rejected. Without the notification, an order is not marked paid.

Advanced

Debug log: Enable debug logging writes the details of payments, notifications and refunds to WooCommerce > Status > Logs, source wcp_redsys_gateway. Errors are always logged, also when this option is off. Keys, signatures and card data are never logged. Default: off.

Delete Data: Delete the gateway settings when the plugin is deleted. When on, deleting the plugin removes the gateway settings and the plugin logs. Default: off.

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 other currencies. On the Pay for order page the currency of the order counts.

Checkout

The customer chooses the payment method (by default Credit/Debit Card (Redsys)) and places the order. The order is set to Pending payment and the customer sees Redirecting to Redsys for payment. Please wait..., then 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 your store (Spanish, English, Catalan, French, German, Italian, Portuguese and more), or English for other languages.

The amount is sent 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 site name. Stock is reduced when the payment is confirmed, not before.

After paying, the customer returns to the order received page of your store. The order is marked paid only after Redsys confirms it by the signed notification. Until it arrives, the page shows Redsys is confirming your payment. If you completed the payment, your order will be updated in a few moments — please do not pay again.

If the customer cancels or the payment is refused, Redsys sends the customer back to your store. For a checkout order, the order is cancelled the standard WooCommerce way and the cart is kept. For an order you created in the admin (a payment link), the customer comes back to the Pay for order page with the message The Redsys payment was not completed. You can try again or choose another payment method., and the order is not cancelled. The redirect page of your store also offers Cancel order & restore cart or, for admin-created orders, Choose another payment method.

A customer can pay an unpaid order again from the Pay for order page. Each attempt gets a new Redsys order number, and a payment made from any of them, for example from a second browser tab, is still recognised.

If the order cannot be sent to Redsys, the customer sees a short message and can choose another payment method: Redsys payments are not configured correctly. Please choose another payment method or contact us., a message that the currency is not accepted, or The order total must be greater than zero.

The payment method works on the classic checkout, on the Checkout block and on the Pay for order page. It is compatible with WooCommerce High-Performance Order Storage (HPOS).

The plugin 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, no pre-authorisation with later capture and no SOAP notifications.

Orders and refunds

Order statuses

Pending payment: the customer was sent to Redsys and has not paid yet, or the Redsys notification has not arrived yet. The order note says Awaiting Redsys payment.

Processing, Completed or On Hold: the payment was confirmed. The status follows Order Status After Payment. The order note shows the Redsys order number (Ds_Order), the authorisation code and the response code, marked [TEST] for test payments. The transaction ID of the order is the Redsys order number.

On hold after payment: Redsys reported a different amount or currency than the order total, a test payment arrived while the store is in live mode (no real money was charged), or the payment arrived after the order had been cancelled. The order note explains it. Check the payment in the Redsys administration panel, then fulfil the order or refund the payment.

Failed: the payment was refused or cancelled at Redsys. The order note shows the response code and, for frequent codes, a short reason such as Insufficient funds, Card expired or Cancelled by the customer. Only an order that still waits for payment becomes Failed. A paid or closed order is never changed by a refused attempt. The attempt is only noted.

Cancelled: the customer cancelled the payment, or the order was cancelled by you or by the WooCommerce stock hold timeout.

If a second, different payment arrives for an order that is already paid or refunded, the order is not changed. A note asks you to refund the duplicate payment in the Redsys administration panel. If Redsys reports that a payment is still in progress, a note is added and the order waits for the final result.

Refunds

Open the order, click Refund, enter the amount and click the refund button via the Redsys payment method (by default Refund via Credit/Debit Card (Redsys)). Full and partial refunds are supported. The refund is sent through the Redsys REST API 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, WooCommerce shows the error and no refund is recorded. A successful refund is added to the order notes with the Redsys order number and the reason.

Refunds made in the Redsys administration panel are not recorded as WooCommerce refunds. When Redsys sends a notification for them, a note is added to the order. If needed, create a manual refund in WooCommerce without the Redsys refund button.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > Redsys. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site 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 customer sees This payment method is not available. Please choose another one. Logged-in store managers still see the payment method, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected: payments already started are still confirmed, and refunds work.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

Troubleshooting

Redsys does not appear at checkout: check that the license is active, Enable/Disable is on, the merchant code and terminal are filled in and the current mode has a valid key: Secret Key (SHA-256) — test in test mode, Secret Key (SHA-256) — live in live mode. Check that the store currency (on the Pay for order page, the order currency) is in the list of supported currencies. The settings page shows a warning for each of these problems.

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 Payment notifications can be reached from the internet without a login, a maintenance page or a firewall block. Turn on Debug log and look at WooCommerce > Status > Logs, source wcp_redsys_gateway.

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 yours. 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 order of this store uses that Redsys order number.

Notification answers Busy: the order was being processed by another notification at the same moment. Redsys retries the notification.

Notification answers Bad request: the request had no or broken Redsys parameters. It did not come from Redsys in the expected format.

Order is On hold after payment: read the order note. The paid amount or currency differed from the order, a test payment arrived while the store is live, or the payment came after the order was cancelled. Fulfil the order or refund the payment.

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

Refund fails: read the error. Redsys refund: the merchant code or the TEST secret key is not configured. (or LIVE) means the key of the environment of the payment is missing. Redsys error codes are explained in the message, for example SIS0057 (the amount exceeds what is left of the payment), SIS0056 (the original payment was not found, other environment or terminal), SIS0042 (signature error, check the key of this environment), SIS0026 (unknown merchant code or terminal) and SIS0027 (currency not configured for the terminal). If Redsys cannot be reached, the refund is not made. Try again later.

Your terminal accepts a currency that is not in the list: developers can change the list of currencies with the rdsg_currency_codes filter. Add a currency only if your bank has enabled it for the terminal.

After updating from version 1.0: the key you used in test mode is now in Secret Key (SHA-256) — test. Enter the live key before you untick Test Mode. Orders created with version 1.0 still receive notifications and refunds.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

Uninstall

Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed. The gateway settings and the plugin logs are removed only if Delete Data was on. Otherwise they stay for a later re-install. The Redsys data stored on orders is always kept, because it documents the payments and is needed for refunds. Existing orders keep their payment notes and transaction IDs.

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