Redsys

Redsys / Sermepa TPV Virtual payment provider plugin for MedusaJS v2

npm install @jsm406/medusa-plugin-redsys

Категория

Платежи

Создано

Jsm406

Версия

1.1.0

Последнее обновление

3 недели назад

Ежемесячные загрузки

Звезды на Github

NPM Github

@jsm406/medusa-plugin-redsys

Redsys / Sermepa TPV Virtual payment provider plugin for MedusaJS v2.

This plugin enables payment processing through Redsys' hosted payment page (TPV Virtual) via redirect flow. Customers are redirected to the Redsys secure payment page to complete their transaction.

Production-proven: This plugin is derived from a live production Medusa store processing real Redsys payments.

Features

Redsys hosted payment page / TPV Virtual redirect flow
Bizum mobile payment support via Redsys TPV
Sandbox and production environments
One-step payment (immediate capture) and two-step payment (pre-authorization + capture)
Full and partial refunds via Redsys API
Payment cancellation
Webhook handling with HMAC-SHA256 signature verification
Spanish error messages for Redsys response codes
Zero PCI scope — card data is handled by Redsys' secure page

Prerequisites

MedusaJS v2.13.0 or later
Node.js v20 or later
A Redsys merchant account (or sandbox test credentials)
v5.3.0+ (installed automatically as a dependency)

Installation

1npm install @jsm406/medusa-plugin-redsys
2# or
3yarn add @jsm406/medusa-plugin-redsys
4# or
5pnpm add @jsm406/medusa-plugin-redsys

Configuration

Environment Variables

Add the following to your file:

1REDSYS_SECRET_KEY=sq7Hj....
2REDSYS_MERCHANT_CODE=999008881
3REDSYS_TERMINAL=001
4REDSYS_ENVIRONMENT=sandbox
5REDSYS_NOTIFICATION_URL=https://your-api.com/hooks/payment/redsys_redsys
6REDSYS_SUCCESS_URL=https://your-store.com/checkout/redsys-callback
7REDSYS_ERROR_URL=https://your-store.com/checkout/redsys-callback?error=1

For sandbox testing, use the following test credentials from Redsys:

1Merchant Code: 999008881
2Terminal: 001
3Secret Key: sq7Hj.......
4Environment: sandbox

Medusa Configuration

In your :

1import { defineConfig } from "@medusajs/framework/config"
2
3export default defineConfig({
modules: [
  {
    resolve: "@medusajs/medusa/payment",
    options: {
      providers: [
        {
          resolve: "@jsm406/medusa-plugin-redsys/providers/redsys",
          id: "redsys",
          options: {
            secretKey: process.env.REDSYS_SECRET_KEY,
            merchantCode: process.env.REDSYS_MERCHANT_CODE,
            terminal: process.env.REDSYS_TERMINAL || "001",
            environment:
              process.env.REDSYS_ENVIRONMENT || "sandbox",
            notificationUrl:
              process.env.REDSYS_NOTIFICATION_URL,
            successUrl: process.env.REDSYS_SUCCESS_URL,
            errorUrl: process.env.REDSYS_ERROR_URL,
            transactionType: "0", // "0" = immediate capture, "1" = pre-authorization
          },
        },
        // Bizum provider (optional - uses same credentials)
        {
          resolve: "@jsm406/medusa-plugin-redsys/providers/redsys-bizum",
          id: "redsys-bizum",
          options: {
            secretKey: process.env.REDSYS_SECRET_KEY,
            merchantCode: process.env.REDSYS_MERCHANT_CODE,
            terminal: process.env.REDSYS_TERMINAL || "001",
            environment:
              process.env.REDSYS_ENVIRONMENT || "sandbox",
            notificationUrl:
              process.env.REDSYS_BIZUM_NOTIFICATION_URL || process.env.REDSYS_NOTIFICATION_URL,
            successUrl: process.env.REDSYS_SUCCESS_URL,
            errorUrl: process.env.REDSYS_ERROR_URL,
            transactionType: "0",
          },
        },
      ],
    },
  },
],
46})

Enable in Region

Enable the Redsys provider(s) in your Medusa admin panel under Settings > Regions:

Credit/Debit Card: Select Redsys as a payment provider
- Provider ID:
Bizum: Select Redsys Bizum as a payment provider
- Provider ID:

You can enable one or both providers depending on which payment methods you want to offer.

Options

Type	Required	Default	Description
string	Yes	—	Redsys HMAC-SHA256 secret key
string	Yes	—	Redsys merchant code (FUC)
string	No		Terminal number
string	No		or
string	No	—	Webhook URL for Redsys to POST transaction results
string	No	—	URL to redirect after successful payment (URLOK)
string	No	—	URL to redirect after failed payment (URLKO)
string	No		= immediate capture, = pre-authorization

Payment Flow

Customer selects Redsys as payment method
creates a signed redirect form with Redsys merchant parameters
Customer clicks "Place Order" → storefront calls to create the order, stores a cookie mapping the Redsys internal order ID to the Medusa order ID, then auto-submits the redirect form to Redsys TPV
Customer completes payment on the Redsys hosted payment page
Redsys sends a webhook notification to
validates the HMAC-SHA256 signature and updates the payment status
Redsys redirects the customer's browser to or with the Redsys order ID as a query parameter
Storefront callback page reads the sessionStorage to resolve the Medusa order ID and redirects to the order confirmation page

Important: authorizePayment Behavior

This plugin's returns for sessions with status and . This is intentional for the redirect flow: the real authorization happens on Redsys TPV and is confirmed via webhook. Without this, would fail with a 400 error because Medusa requires the payment session to be authorized before completing the cart.

ID Mapping (Redsys → Medusa)

The plugin generates a 12-character alphanumeric (e.g. ) used as Redsys' merchant order reference. When the order is completed via , Medusa generates its own order ID (e.g. ). These are different IDs.

The callback URL from Redsys only contains the Redsys order ID, not the Medusa order ID. To bridge this gap, the storefront stores the mapping → in before redirecting to the TPV. The callback page reads this value to redirect to the correct order confirmation page.

Storefront Integration

Redsys is a redirect-based payment method (no card input in your storefront — the customer enters card data on Redsys' secure TPV). You must adapt your Medusa Next.js storefront with the changes below.

1. — Register the payment methods

Add Redsys and Bizum to the payment info map and add helper functions:

1// Inside paymentInfoMap, add:
2pp_redsys_redsys: {
3  title: "Credit / Debit Card",
4  icon: <CreditCard />,
5},
6pp_redsys_redsys_bizum: {
7  title: "Bizum",
8  icon: <Smartphone />,
9},
10
11// Add helper functions:
12export const isRedsys = (providerId?: string) => {
13  return providerId?.startsWith("pp_redsys_redsys") && !providerId?.includes("bizum")
14}
15
16export const isRedsysBizum = (providerId?: string) => {
17  return providerId?.startsWith("pp_redsys_redsys_bizum")
18}

2. — Add order completion without redirect

Add a function. The standard does a (server-side), but Redsys needs to redirect the browser to the TPV instead. This function completes the cart, creates the order, but returns the result so the client can handle the TPV redirect:

1export async function completeCartWithoutRedirect(cartId?: string) {
const id = cartId || (await getCartId())
3
if (!id) {
  throw new Error("No existing cart found when completing cart")
}
7
const headers = {
  ...(await getAuthHeaders()),
}
11
const cartRes = await sdk.store.cart
  .complete(id, {}, headers)
  .then(async (cartRes) => {
    const cartCacheTag = await getCacheTag("carts")
    revalidateTag(cartCacheTag)
    return cartRes
  })
  .catch(medusaError)
20
if (cartRes?.type === "order") {
  const orderCacheTag = await getCacheTag("orders")
  revalidateTag(orderCacheTag)
  removeCartId()
}
26
return cartRes
28}

3. — Payment buttons

Add payment button components for both Redsys (card) and Bizum. Both use the same redirect flow but with different provider IDs.

1// Add imports:
2import { isManual, isRedsys, isRedsysBizum, isStripeLike } from "@lib/constants"
3import { completeCartWithoutRedirect, placeOrder } from "@lib/data/cart"
4
5// Add cases in PaymentButton's switch:
6case isRedsysBizum(paymentSession?.provider_id):
return (
  <RedsysBizumPaymentButton
    notReady={notReady}
    cart={cart}
    data-testid={dataTestId}
  />
)
14
15case isRedsys(paymentSession?.provider_id):
return (
  <RedsysPaymentButton
    notReady={notReady}
    cart={cart}
    data-testid={dataTestId}
  />
)
23
24// Redsys Card Payment Button:
25const RedsysPaymentButton = ({
cart,
notReady,
"data-testid": dataTestId,
29}: {
cart: HttpTypes.StoreCart
notReady: boolean
"data-testid"?: string
33}) => {
const [submitting, setSubmitting] = useState(false)
const [errorMessage, setErrorMessage] = useState<string | null>(null)
36
const handlePayment = async () => {
  setSubmitting(true)
39
  const paymentSession = cart.payment_collection?.payment_sessions?.find(
    (s) => s.status === "pending" && isRedsys(s.provider_id)
  )
43
  const redsysData = paymentSession?.data as Record<string, string> | undefined
45
  if (!redsysData?.formUrl || !redsysData?.merchantParams || !redsysData?.signature) {
    setErrorMessage("No se pudieron obtener los datos de pago de Redsys")
    setSubmitting(false)
    return
  }
51
  const cartRes = await completeCartWithoutRedirect()
    .catch((err) => {
      setErrorMessage(err.message)
      setSubmitting(false)
      return null
    })
58
  if (!cartRes || cartRes.type !== "order") {
    setErrorMessage(cartRes ? "Error al crear el pedido" : "")
    setSubmitting(false)
    return
  }
64
  const medusaOrderId = cartRes.order.id
  const redsysOrderId = redsysData.orderId || ""
  const countryCode = cart.shipping_address?.country_code?.toLowerCase() || "dk"
  sessionStorage.setItem(
    `redsys_map_${redsysOrderId}`,
    JSON.stringify({ medusaOrderId, countryCode })
  )
72
  const form = document.createElement("form")
  form.method = "POST"
  form.action = redsysData.formUrl
76
  const fields: Record<string, string> = {
    Ds_SignatureVersion: redsysData.signatureVersion,
    Ds_MerchantParameters: redsysData.merchantParams,
    Ds_Signature: redsysData.signature,
  }
82
  Object.entries(fields).forEach(([name, value]) => {
    const input = document.createElement("input")
    input.type = "hidden"
    input.name = name
    input.value = value
    form.appendChild(input)
  })
90
  document.body.appendChild(form)
  form.submit()
}
94
return (
  <>
    <Button
      disabled={notReady || submitting}
      isLoading={submitting}
      onClick={handlePayment}
      size="large"
      data-testid={dataTestId}
    >
      Place order
    </Button>
    <ErrorMessage
      error={errorMessage}
      data-testid="redsys-payment-error-message"
    />
  </>
)
112}
113
114// Bizum Payment Button (identical flow, different provider check):
115const RedsysBizumPaymentButton = ({
cart,
notReady,
"data-testid": dataTestId,
119}: {
cart: HttpTypes.StoreCart
notReady: boolean
"data-testid"?: string
123}) => {
const [submitting, setSubmitting] = useState(false)
const [errorMessage, setErrorMessage] = useState<string | null>(null)
126
const handlePayment = async () => {
  setSubmitting(true)
129
  const paymentSession = cart.payment_collection?.payment_sessions?.find(
    (s) => s.status === "pending" && isRedsysBizum(s.provider_id)
  )
133
  const redsysData = paymentSession?.data as Record<string, string> | undefined
135
  if (!redsysData?.formUrl || !redsysData?.merchantParams || !redsysData?.signature) {
    setErrorMessage("No se pudieron obtener los datos de pago de Bizum")
    setSubmitting(false)
    return
  }
141
  const cartRes = await completeCartWithoutRedirect()
    .catch((err) => {
      setErrorMessage(err.message)
      setSubmitting(false)
      return null
    })
148
  if (!cartRes || cartRes.type !== "order") {
    setErrorMessage(cartRes ? "Error al crear el pedido" : "")
    setSubmitting(false)
    return
  }
154
  const medusaOrderId = cartRes.order.id
  const redsysOrderId = redsysData.orderId || ""
  const countryCode = cart.shipping_address?.country_code?.toLowerCase() || "dk"
  sessionStorage.setItem(
    `redsys_map_${redsysOrderId}`,
    JSON.stringify({ medusaOrderId, countryCode })
  )
162
  const form = document.createElement("form")
  form.method = "POST"
  form.action = redsysData.formUrl
166
  const fields: Record<string, string> = {
    Ds_SignatureVersion: redsysData.signatureVersion,
    Ds_MerchantParameters: redsysData.merchantParams,
    Ds_Signature: redsysData.signature,
  }
172
  Object.entries(fields).forEach(([name, value]) => {
    const input = document.createElement("input")
    input.type = "hidden"
    input.name = name
    input.value = value
    form.appendChild(input)
  })
180
  document.body.appendChild(form)
  form.submit()
}
184
return (
  <>
    <Button
      disabled={notReady || submitting}
      isLoading={submitting}
      onClick={handlePayment}
      size="large"
      data-testid={dataTestId}
    >
      Pagar con Bizum
    </Button>
    <ErrorMessage
      error={errorMessage}
      data-testid="redsys-bizum-payment-error-message"
    />
  </>
)
202}

4. — Callback page (new file)

Create a client component page that Redsys redirects to after payment. It reads the query param (Redsys internal ID), looks up the real Medusa order ID from , and redirects to the order confirmation page:

1"use client"
2
3import { useRouter, useSearchParams } from "next/navigation"
4import { useEffect, useState } from "react"
5
6export default function RedsysCallbackPage() {
const searchParams = useSearchParams()
const router = useRouter()
const [status, setStatus] = useState<"loading" | "error" | "success">("loading")
10
const isError = searchParams?.get("error") === "1"
const redsysOrderId = searchParams?.get("orderId")
13
useEffect(() => {
  if (isError) {
    setStatus("error")
    return
  }
19
  if (!redsysOrderId) {
    setStatus("success")
    return
  }
24
  const stored = sessionStorage.getItem(`redsys_map_${redsysOrderId}`)
26
  if (stored) {
    let orderData: { medusaOrderId: string; countryCode: string }
    try {
      orderData = JSON.parse(stored)
    } catch {
      orderData = { medusaOrderId: stored, countryCode: "dk" }
    }
    sessionStorage.removeItem(`redsys_map_${redsysOrderId}`)
    router.replace(
      `/${orderData.countryCode}/order/${orderData.medusaOrderId}/confirmed`
    )
    return
  }
40
  setStatus("success")
}, [isError, redsysOrderId, router])
43
if (status === "loading") {
  return (
    <div className="flex flex-col items-center justify-center min-h-[50vh] gap-4 p-8">
      <p className="text-gray-600">Procesando pago...</p>
    </div>
  )
}
51
if (status === "error") {
  return (
    <div className="flex flex-col items-center justify-center min-h-[50vh] gap-4 p-8">
      <h1 className="text-2xl font-bold text-red-600">Pago no completado</h1>
      <p className="text-gray-600">
        La operación no se ha completado correctamente.
      </p>
      <a href="/" className="mt-4 px-6 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700">
        Volver a la tienda
      </a>
    </div>
  )
}
65
return (
  <div className="flex flex-col items-center justify-center min-h-[50vh] gap-4 p-8">
    <h1 className="text-2xl font-bold text-green-600">Pago procesado</h1>
    <p className="text-gray-600">Tu pago ha sido procesado correctamente.</p>
    <a href="/" className="mt-4 px-6 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700">
      Volver a la tienda
    </a>
  </div>
)
75}

5. — Bypass region redirect

If your storefront uses middleware to enforce region/country code prefixes in URLs (as the default Medusa Next.js storefront does), add a bypass so is not redirected. Add this early in the function:

1// Redsys callback URL — bypass region redirect
2if (request.nextUrl.pathname.startsWith("/checkout/redsys-callback")) {
3  return NextResponse.next()
4}

6. — CORS

Ensure your storefront domain is allowed in CORS:

1projectConfig: {
2  http: {
3    storeCors: "http://localhost:8000,https://your-store.com",
4  },
5}

Session Data Reference

The payment session field returned by :

1{
orderId: "1234ABCD5678",
amount: "2550",
currency: "978",
status: "pending",
transactionType: "0",
merchantParams: "base64...",          // Base64-encoded merchant parameters
signature: "hmac...",                 // HMAC-SHA256 signature
signatureVersion: "HMAC_SHA256_V1",   // Normal - version identifier from redsys-es library
formUrl: "https://sis-t.redsys.es:25443/sis/realizarPago"
11}

Note: The identifier in the URL callback is the value returned by the library and is normal. This does not indicate a problem - the actual signature computation follows the Redsys v4.1 specification. The value is informational in the callback URL.

These fields are used in step 3 to build the auto-submitting redirect form.

Webhook

Medusa automatically exposes webhook endpoints for the Redsys providers at:

1/hooks/payment/redsys_redsys        (Card payments)
2/hooks/payment/redsys_redsys_bizum  (Bizum payments)

For local development with sandbox, you must expose your backend to the internet (e.g., via ngrok) so Redsys can reach the webhook. Set to the ngrok URL.

Important: Redsys sends the notification to but the signature verification and payment status update happens through the Medusa webhook handler — make sure points to the same endpoint or forward notifications accordingly.

Test Cards (Sandbox)

Card Payments

Card Number	Brand	Behavior
4548810000000003	VISA	3DS v2 approved
5576441563045037	Mastercard	3DS v2 approved
4548814479727229	VISA	3DS frictionless
4548817212493017	VISA	3DS challenge
Any + CVV 999	Any	Payment declined

Bizum (Sandbox)

Important: In sandbox, Bizum transactions cannot exceed 10€. Use a discount coupon or low-price test product.

Field	Value
Phone number
PIN
SMS code

Test scenarios by amount:

Amount	Result
< 5€	Payment approved
5€ - 10€	Payment approved
10€ - 15€	Payment declined (exceeds sandbox limit)
> 15€	Payment declined (no Bizum user)

Transaction Types

Code	Type	Description
	Payment	Authorization + immediate capture (default)
	Pre-authorization	Reserve funds only
	Confirmation	Capture pre-authorized funds
	Refund	Full or partial refund
	Cancellation	Cancel/void a transaction

Security

Never log PAN, CVV, or the secret key. The provider strips sensitive fields from log output.
Always validate signatures server-side. uses 's for HMAC-SHA256 verification.
Use HTTPS for all communication with Redsys.
Do not trust client-side payment data. The webhook with signature verification is the source of truth.
The redirect flow keeps you out of PCI scope — card data is handled by Redsys' secure page.

Currency Support

The plugin includes built-in numeric currency codes for all major currencies. If your currency is not listed, it defaults to EUR (). See for the full list.

Development

1# Install dependencies
2npm install
3
4# Build
5npm run build
6
7# Run tests
8npm test
9
10# Watch mode (for local plugin development)
11npm run dev

Local Testing with a Medusa Project

1# From your plugin directory
2npm run dev
3
4# In your Medusa project directory:
5npx medusa plugin:add ../path-to/@jsm406/medusa-plugin-redsys

License

MIT — see LICENSE file for details.

Version History

v1.1.0 (2026-06-16)

Added: Bizum payment method support via Redsys TPV
New provider with parameter
Full lifecycle support: initiate, authorize, capture, cancel, refund, webhook
Same configuration as card provider (can share credentials)
Separate webhook endpoint at

v1.0.12 (2026-05-13)

Fixed: Response code validation for payment authorization (codes 0-99), refunds/confirmations (code 900), cancellations (code 400)
Note: The in the callback URL is normal - it's the identifier returned by the redsys-es library. The actual HMAC computation follows Redsys v4.1 specification.

v1.0.0 (2025-05-05)

Initial release

Support

For issues and questions, please open an issue on GitHub.

Еще в этой категории

Посмотреть все

Платежи

Braintree

От Lambda Curry

Поддержка платежей и 3D Secure через Braintree

Платежи

Pay.

От Webbers

Принимайте кредитные карты, цифровые платежи и купи сейчас — плати потом

Платежи

Mollie

От Variable Vic

Легко принимайте мультивалютные платежи через Mollie

Еще от этого автора

Посмотреть все

Другое

Product reviews

От Jsm406

Product Reviews plugin for Medusa v2 — fork of @lambdacurry/medusa-product-reviews with Zod v4 / Medusa 2.14+ compatibility

Плагины

Redsys

Redsys / Sermepa TPV Virtual payment provider plugin for MedusaJS v2

npm install @jsm406/medusa-plugin-redsys

Категория

Платежи

Создано

Jsm406

Версия

1.1.0

Последнее обновление

3 недели назад

Ежемесячные загрузки

Звезды на Github

NPM Github

@jsm406/medusa-plugin-redsys

Redsys / Sermepa TPV Virtual payment provider plugin for MedusaJS v2.

This plugin enables payment processing through Redsys' hosted payment page (TPV Virtual) via redirect flow. Customers are redirected to the Redsys secure payment page to complete their transaction.

Production-proven: This plugin is derived from a live production Medusa store processing real Redsys payments.

Features

Redsys hosted payment page / TPV Virtual redirect flow
Bizum mobile payment support via Redsys TPV
Sandbox and production environments
One-step payment (immediate capture) and two-step payment (pre-authorization + capture)
Full and partial refunds via Redsys API
Payment cancellation
Webhook handling with HMAC-SHA256 signature verification
Spanish error messages for Redsys response codes
Zero PCI scope — card data is handled by Redsys' secure page

Prerequisites

MedusaJS v2.13.0 or later
Node.js v20 or later
A Redsys merchant account (or sandbox test credentials)
v5.3.0+ (installed automatically as a dependency)

Installation

1npm install @jsm406/medusa-plugin-redsys
2# or
3yarn add @jsm406/medusa-plugin-redsys
4# or
5pnpm add @jsm406/medusa-plugin-redsys

Configuration

Environment Variables

Add the following to your file:

1REDSYS_SECRET_KEY=sq7Hj....
2REDSYS_MERCHANT_CODE=999008881
3REDSYS_TERMINAL=001
4REDSYS_ENVIRONMENT=sandbox
5REDSYS_NOTIFICATION_URL=https://your-api.com/hooks/payment/redsys_redsys
6REDSYS_SUCCESS_URL=https://your-store.com/checkout/redsys-callback
7REDSYS_ERROR_URL=https://your-store.com/checkout/redsys-callback?error=1

For sandbox testing, use the following test credentials from Redsys:

1Merchant Code: 999008881
2Terminal: 001
3Secret Key: sq7Hj.......
4Environment: sandbox

Medusa Configuration

In your :

1import { defineConfig } from "@medusajs/framework/config"
2
3export default defineConfig({
modules: [
  {
    resolve: "@medusajs/medusa/payment",
    options: {
      providers: [
        {
          resolve: "@jsm406/medusa-plugin-redsys/providers/redsys",
          id: "redsys",
          options: {
            secretKey: process.env.REDSYS_SECRET_KEY,
            merchantCode: process.env.REDSYS_MERCHANT_CODE,
            terminal: process.env.REDSYS_TERMINAL || "001",
            environment:
              process.env.REDSYS_ENVIRONMENT || "sandbox",
            notificationUrl:
              process.env.REDSYS_NOTIFICATION_URL,
            successUrl: process.env.REDSYS_SUCCESS_URL,
            errorUrl: process.env.REDSYS_ERROR_URL,
            transactionType: "0", // "0" = immediate capture, "1" = pre-authorization
          },
        },
        // Bizum provider (optional - uses same credentials)
        {
          resolve: "@jsm406/medusa-plugin-redsys/providers/redsys-bizum",
          id: "redsys-bizum",
          options: {
            secretKey: process.env.REDSYS_SECRET_KEY,
            merchantCode: process.env.REDSYS_MERCHANT_CODE,
            terminal: process.env.REDSYS_TERMINAL || "001",
            environment:
              process.env.REDSYS_ENVIRONMENT || "sandbox",
            notificationUrl:
              process.env.REDSYS_BIZUM_NOTIFICATION_URL || process.env.REDSYS_NOTIFICATION_URL,
            successUrl: process.env.REDSYS_SUCCESS_URL,
            errorUrl: process.env.REDSYS_ERROR_URL,
            transactionType: "0",
          },
        },
      ],
    },
  },
],
46})

Enable in Region

Enable the Redsys provider(s) in your Medusa admin panel under Settings > Regions:

Credit/Debit Card: Select Redsys as a payment provider
- Provider ID:
Bizum: Select Redsys Bizum as a payment provider
- Provider ID:

You can enable one or both providers depending on which payment methods you want to offer.

Options

Type	Required	Default	Description
string	Yes	—	Redsys HMAC-SHA256 secret key
string	Yes	—	Redsys merchant code (FUC)
string	No		Terminal number
string	No		or
string	No	—	Webhook URL for Redsys to POST transaction results
string	No	—	URL to redirect after successful payment (URLOK)
string	No	—	URL to redirect after failed payment (URLKO)
string	No		= immediate capture, = pre-authorization

Payment Flow

Customer selects Redsys as payment method
creates a signed redirect form with Redsys merchant parameters
Customer clicks "Place Order" → storefront calls to create the order, stores a cookie mapping the Redsys internal order ID to the Medusa order ID, then auto-submits the redirect form to Redsys TPV
Customer completes payment on the Redsys hosted payment page
Redsys sends a webhook notification to
validates the HMAC-SHA256 signature and updates the payment status
Redsys redirects the customer's browser to or with the Redsys order ID as a query parameter
Storefront callback page reads the sessionStorage to resolve the Medusa order ID and redirects to the order confirmation page

Important: authorizePayment Behavior

ID Mapping (Redsys → Medusa)

Storefront Integration

1. — Register the payment methods

Add Redsys and Bizum to the payment info map and add helper functions:

1// Inside paymentInfoMap, add:
2pp_redsys_redsys: {
3  title: "Credit / Debit Card",
4  icon: <CreditCard />,
5},
6pp_redsys_redsys_bizum: {
7  title: "Bizum",
8  icon: <Smartphone />,
9},
10
11// Add helper functions:
12export const isRedsys = (providerId?: string) => {
13  return providerId?.startsWith("pp_redsys_redsys") && !providerId?.includes("bizum")
14}
15
16export const isRedsysBizum = (providerId?: string) => {
17  return providerId?.startsWith("pp_redsys_redsys_bizum")
18}

2. — Add order completion without redirect

1export async function completeCartWithoutRedirect(cartId?: string) {
const id = cartId || (await getCartId())
3
if (!id) {
  throw new Error("No existing cart found when completing cart")
}
7
const headers = {
  ...(await getAuthHeaders()),
}
11
const cartRes = await sdk.store.cart
  .complete(id, {}, headers)
  .then(async (cartRes) => {
    const cartCacheTag = await getCacheTag("carts")
    revalidateTag(cartCacheTag)
    return cartRes
  })
  .catch(medusaError)
20
if (cartRes?.type === "order") {
  const orderCacheTag = await getCacheTag("orders")
  revalidateTag(orderCacheTag)
  removeCartId()
}
26
return cartRes
28}

3. — Payment buttons

Add payment button components for both Redsys (card) and Bizum. Both use the same redirect flow but with different provider IDs.

1// Add imports:
2import { isManual, isRedsys, isRedsysBizum, isStripeLike } from "@lib/constants"
3import { completeCartWithoutRedirect, placeOrder } from "@lib/data/cart"
4
5// Add cases in PaymentButton's switch:
6case isRedsysBizum(paymentSession?.provider_id):
return (
  <RedsysBizumPaymentButton
    notReady={notReady}
    cart={cart}
    data-testid={dataTestId}
  />
)
14
15case isRedsys(paymentSession?.provider_id):
return (
  <RedsysPaymentButton
    notReady={notReady}
    cart={cart}
    data-testid={dataTestId}
  />
)
23
24// Redsys Card Payment Button:
25const RedsysPaymentButton = ({
cart,
notReady,
"data-testid": dataTestId,
29}: {
cart: HttpTypes.StoreCart
notReady: boolean
"data-testid"?: string
33}) => {
const [submitting, setSubmitting] = useState(false)
const [errorMessage, setErrorMessage] = useState<string | null>(null)
36
const handlePayment = async () => {
  setSubmitting(true)
39
  const paymentSession = cart.payment_collection?.payment_sessions?.find(
    (s) => s.status === "pending" && isRedsys(s.provider_id)
  )
43
  const redsysData = paymentSession?.data as Record<string, string> | undefined
45
  if (!redsysData?.formUrl || !redsysData?.merchantParams || !redsysData?.signature) {
    setErrorMessage("No se pudieron obtener los datos de pago de Redsys")
    setSubmitting(false)
    return
  }
51
  const cartRes = await completeCartWithoutRedirect()
    .catch((err) => {
      setErrorMessage(err.message)
      setSubmitting(false)
      return null
    })
58
  if (!cartRes || cartRes.type !== "order") {
    setErrorMessage(cartRes ? "Error al crear el pedido" : "")
    setSubmitting(false)
    return
  }
64
  const medusaOrderId = cartRes.order.id
  const redsysOrderId = redsysData.orderId || ""
  const countryCode = cart.shipping_address?.country_code?.toLowerCase() || "dk"
  sessionStorage.setItem(
    `redsys_map_${redsysOrderId}`,
    JSON.stringify({ medusaOrderId, countryCode })
  )
72
  const form = document.createElement("form")
  form.method = "POST"
  form.action = redsysData.formUrl
76
  const fields: Record<string, string> = {
    Ds_SignatureVersion: redsysData.signatureVersion,
    Ds_MerchantParameters: redsysData.merchantParams,
    Ds_Signature: redsysData.signature,
  }
82
  Object.entries(fields).forEach(([name, value]) => {
    const input = document.createElement("input")
    input.type = "hidden"
    input.name = name
    input.value = value
    form.appendChild(input)
  })
90
  document.body.appendChild(form)
  form.submit()
}
94
return (
  <>
    <Button
      disabled={notReady || submitting}
      isLoading={submitting}
      onClick={handlePayment}
      size="large"
      data-testid={dataTestId}
    >
      Place order
    </Button>
    <ErrorMessage
      error={errorMessage}
      data-testid="redsys-payment-error-message"
    />
  </>
)
112}
113
114// Bizum Payment Button (identical flow, different provider check):
115const RedsysBizumPaymentButton = ({
cart,
notReady,
"data-testid": dataTestId,
119}: {
cart: HttpTypes.StoreCart
notReady: boolean
"data-testid"?: string
123}) => {
const [submitting, setSubmitting] = useState(false)
const [errorMessage, setErrorMessage] = useState<string | null>(null)
126
const handlePayment = async () => {
  setSubmitting(true)
129
  const paymentSession = cart.payment_collection?.payment_sessions?.find(
    (s) => s.status === "pending" && isRedsysBizum(s.provider_id)
  )
133
  const redsysData = paymentSession?.data as Record<string, string> | undefined
135
  if (!redsysData?.formUrl || !redsysData?.merchantParams || !redsysData?.signature) {
    setErrorMessage("No se pudieron obtener los datos de pago de Bizum")
    setSubmitting(false)
    return
  }
141
  const cartRes = await completeCartWithoutRedirect()
    .catch((err) => {
      setErrorMessage(err.message)
      setSubmitting(false)
      return null
    })
148
  if (!cartRes || cartRes.type !== "order") {
    setErrorMessage(cartRes ? "Error al crear el pedido" : "")
    setSubmitting(false)
    return
  }
154
  const medusaOrderId = cartRes.order.id
  const redsysOrderId = redsysData.orderId || ""
  const countryCode = cart.shipping_address?.country_code?.toLowerCase() || "dk"
  sessionStorage.setItem(
    `redsys_map_${redsysOrderId}`,
    JSON.stringify({ medusaOrderId, countryCode })
  )
162
  const form = document.createElement("form")
  form.method = "POST"
  form.action = redsysData.formUrl
166
  const fields: Record<string, string> = {
    Ds_SignatureVersion: redsysData.signatureVersion,
    Ds_MerchantParameters: redsysData.merchantParams,
    Ds_Signature: redsysData.signature,
  }
172
  Object.entries(fields).forEach(([name, value]) => {
    const input = document.createElement("input")
    input.type = "hidden"
    input.name = name
    input.value = value
    form.appendChild(input)
  })
180
  document.body.appendChild(form)
  form.submit()
}
184
return (
  <>
    <Button
      disabled={notReady || submitting}
      isLoading={submitting}
      onClick={handlePayment}
      size="large"
      data-testid={dataTestId}
    >
      Pagar con Bizum
    </Button>
    <ErrorMessage
      error={errorMessage}
      data-testid="redsys-bizum-payment-error-message"
    />
  </>
)
202}

4. — Callback page (new file)

1"use client"
2
3import { useRouter, useSearchParams } from "next/navigation"
4import { useEffect, useState } from "react"
5
6export default function RedsysCallbackPage() {
const searchParams = useSearchParams()
const router = useRouter()
const [status, setStatus] = useState<"loading" | "error" | "success">("loading")
10
const isError = searchParams?.get("error") === "1"
const redsysOrderId = searchParams?.get("orderId")
13
useEffect(() => {
  if (isError) {
    setStatus("error")
    return
  }
19
  if (!redsysOrderId) {
    setStatus("success")
    return
  }
24
  const stored = sessionStorage.getItem(`redsys_map_${redsysOrderId}`)
26
  if (stored) {
    let orderData: { medusaOrderId: string; countryCode: string }
    try {
      orderData = JSON.parse(stored)
    } catch {
      orderData = { medusaOrderId: stored, countryCode: "dk" }
    }
    sessionStorage.removeItem(`redsys_map_${redsysOrderId}`)
    router.replace(
      `/${orderData.countryCode}/order/${orderData.medusaOrderId}/confirmed`
    )
    return
  }
40
  setStatus("success")
}, [isError, redsysOrderId, router])
43
if (status === "loading") {
  return (
    <div className="flex flex-col items-center justify-center min-h-[50vh] gap-4 p-8">
      <p className="text-gray-600">Procesando pago...</p>
    </div>
  )
}
51
if (status === "error") {
  return (
    <div className="flex flex-col items-center justify-center min-h-[50vh] gap-4 p-8">
      <h1 className="text-2xl font-bold text-red-600">Pago no completado</h1>
      <p className="text-gray-600">
        La operación no se ha completado correctamente.
      </p>
      <a href="/" className="mt-4 px-6 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700">
        Volver a la tienda
      </a>
    </div>
  )
}
65
return (
  <div className="flex flex-col items-center justify-center min-h-[50vh] gap-4 p-8">
    <h1 className="text-2xl font-bold text-green-600">Pago procesado</h1>
    <p className="text-gray-600">Tu pago ha sido procesado correctamente.</p>
    <a href="/" className="mt-4 px-6 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700">
      Volver a la tienda
    </a>
  </div>
)
75}

5. — Bypass region redirect

If your storefront uses middleware to enforce region/country code prefixes in URLs (as the default Medusa Next.js storefront does), add a bypass so is not redirected. Add this early in the function:

1// Redsys callback URL — bypass region redirect
2if (request.nextUrl.pathname.startsWith("/checkout/redsys-callback")) {
3  return NextResponse.next()
4}

6. — CORS

Ensure your storefront domain is allowed in CORS:

1projectConfig: {
2  http: {
3    storeCors: "http://localhost:8000,https://your-store.com",
4  },
5}

Session Data Reference

The payment session field returned by :

1{
orderId: "1234ABCD5678",
amount: "2550",
currency: "978",
status: "pending",
transactionType: "0",
merchantParams: "base64...",          // Base64-encoded merchant parameters
signature: "hmac...",                 // HMAC-SHA256 signature
signatureVersion: "HMAC_SHA256_V1",   // Normal - version identifier from redsys-es library
formUrl: "https://sis-t.redsys.es:25443/sis/realizarPago"
11}

Note: The identifier in the URL callback is the value returned by the library and is normal. This does not indicate a problem - the actual signature computation follows the Redsys v4.1 specification. The value is informational in the callback URL.

These fields are used in step 3 to build the auto-submitting redirect form.

Webhook

Medusa automatically exposes webhook endpoints for the Redsys providers at:

1/hooks/payment/redsys_redsys        (Card payments)
2/hooks/payment/redsys_redsys_bizum  (Bizum payments)

For local development with sandbox, you must expose your backend to the internet (e.g., via ngrok) so Redsys can reach the webhook. Set to the ngrok URL.

Test Cards (Sandbox)

Card Payments

Card Number	Brand	Behavior
4548810000000003	VISA	3DS v2 approved
5576441563045037	Mastercard	3DS v2 approved
4548814479727229	VISA	3DS frictionless
4548817212493017	VISA	3DS challenge
Any + CVV 999	Any	Payment declined

Bizum (Sandbox)

Important: In sandbox, Bizum transactions cannot exceed 10€. Use a discount coupon or low-price test product.

Field	Value
Phone number
PIN
SMS code

Test scenarios by amount:

Amount	Result
< 5€	Payment approved
5€ - 10€	Payment approved
10€ - 15€	Payment declined (exceeds sandbox limit)
> 15€	Payment declined (no Bizum user)

Transaction Types

Code	Type	Description
	Payment	Authorization + immediate capture (default)
	Pre-authorization	Reserve funds only
	Confirmation	Capture pre-authorized funds
	Refund	Full or partial refund
	Cancellation	Cancel/void a transaction

Security

Never log PAN, CVV, or the secret key. The provider strips sensitive fields from log output.
Always validate signatures server-side. uses 's for HMAC-SHA256 verification.
Use HTTPS for all communication with Redsys.
Do not trust client-side payment data. The webhook with signature verification is the source of truth.
The redirect flow keeps you out of PCI scope — card data is handled by Redsys' secure page.

Currency Support

The plugin includes built-in numeric currency codes for all major currencies. If your currency is not listed, it defaults to EUR (). See for the full list.

Development

1# Install dependencies
2npm install
3
4# Build
5npm run build
6
7# Run tests
8npm test
9
10# Watch mode (for local plugin development)
11npm run dev

Local Testing with a Medusa Project

1# From your plugin directory
2npm run dev
3
4# In your Medusa project directory:
5npx medusa plugin:add ../path-to/@jsm406/medusa-plugin-redsys

License

MIT — see LICENSE file for details.

Version History

v1.1.0 (2026-06-16)

Added: Bizum payment method support via Redsys TPV
New provider with parameter
Full lifecycle support: initiate, authorize, capture, cancel, refund, webhook
Same configuration as card provider (can share credentials)
Separate webhook endpoint at

v1.0.12 (2026-05-13)

Fixed: Response code validation for payment authorization (codes 0-99), refunds/confirmations (code 900), cancellations (code 400)
Note: The in the callback URL is normal - it's the identifier returned by the redsys-es library. The actual HMAC computation follows Redsys v4.1 specification.

v1.0.0 (2025-05-05)

Initial release

Support

For issues and questions, please open an issue on GitHub.

Еще в этой категории

Посмотреть все

Платежи

Braintree

От Lambda Curry

Поддержка платежей и 3D Secure через Braintree

Платежи

Pay.

От Webbers

Принимайте кредитные карты, цифровые платежи и купи сейчас — плати потом

Платежи

Mollie

От Variable Vic

Легко принимайте мультивалютные платежи через Mollie

Еще от этого автора

Посмотреть все

Другое

Product reviews

От Jsm406

Product Reviews plugin for Medusa v2 — fork of @lambdacurry/medusa-product-reviews with Zod v4 / Medusa 2.14+ compatibility

Redsys

@jsm406/medusa-plugin-redsys

Features

Prerequisites

Installation

Configuration

Environment Variables

Medusa Configuration

Enable in Region

Options

Payment Flow

Important: authorizePayment Behavior

ID Mapping (Redsys → Medusa)

Storefront Integration

1. src/lib/constants.tsx — Register the payment methods

2. src/lib/data/cart.ts — Add order completion without redirect

3. src/modules/checkout/components/payment-button/index.tsx — Payment buttons

4. src/app/checkout/redsys-callback/page.tsx — Callback page (new file)

5. src/middleware.ts — Bypass region redirect

6. medusa-config.ts — CORS

Session Data Reference

Webhook

Test Cards (Sandbox)

Card Payments

Bizum (Sandbox)

Transaction Types

Security

Currency Support

Development

Local Testing with a Medusa Project

License

Version History

v1.1.0 (2026-06-16)

v1.0.12 (2026-05-13)

v1.0.0 (2025-05-05)

Support

Еще в этой категории

Braintree

Pay.

Mollie

Еще от этого автора

Product reviews

Redsys

@jsm406/medusa-plugin-redsys

Features

Prerequisites

Installation

Configuration

Environment Variables

Medusa Configuration

Enable in Region

Options

Payment Flow

Important: authorizePayment Behavior

ID Mapping (Redsys → Medusa)

Storefront Integration

1. src/lib/constants.tsx — Register the payment methods

2. src/lib/data/cart.ts — Add order completion without redirect

3. src/modules/checkout/components/payment-button/index.tsx — Payment buttons

4. src/app/checkout/redsys-callback/page.tsx — Callback page (new file)

5. src/middleware.ts — Bypass region redirect

6. medusa-config.ts — CORS

Session Data Reference

Webhook

Test Cards (Sandbox)

Card Payments

Bizum (Sandbox)

Transaction Types

Security

Currency Support

Development

Local Testing with a Medusa Project

License

Version History

v1.1.0 (2026-06-16)

v1.0.12 (2026-05-13)

v1.0.0 (2025-05-05)

Support

Еще в этой категории

Braintree

1. — Register the payment methods

2. — Add order completion without redirect

3. — Payment buttons

4. — Callback page (new file)

5. — Bypass region redirect

6. — CORS

1. — Register the payment methods

2. — Add order completion without redirect

3. — Payment buttons

4. — Callback page (new file)

5. — Bypass region redirect

6. — CORS