Redsys

medusa-payment-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
• 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)
• redsys-easy v5.3.0+ (installed automatically as a dependency)

Installation

1npm install medusa-payment-redsys
2# or
3yarn add medusa-payment-redsys
4# or
5pnpm add medusa-payment-redsys

Configuration

Environment Variables

Add the following to your .env 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:

Merchant Code: 999008881
Terminal: 001
Secret Key: sq7Hj.......
Environment: sandbox

Medusa Configuration

In your medusa-config.ts:

1import { defineConfig } from "@medusajs/framework/config"
2
3export default defineConfig({
4  modules: [
5    {
6      resolve: "@medusajs/medusa/payment",
7      options: {
8        providers: [
9          {
10            resolve: "medusa-payment-redsys/providers/redsys",
11            id: "redsys",
12            options: {
13              secretKey: process.env.REDSYS_SECRET_KEY,
14              merchantCode: process.env.REDSYS_MERCHANT_CODE,
15              terminal: process.env.REDSYS_TERMINAL || "001",
16              environment:
17                process.env.REDSYS_ENVIRONMENT || "sandbox",
18              notificationUrl:
19                process.env.REDSYS_NOTIFICATION_URL,
20              successUrl: process.env.REDSYS_SUCCESS_URL,
21              errorUrl: process.env.REDSYS_ERROR_URL,
22              transactionType: "0", // "0" = immediate capture, "1" = pre-authorization
23            },
24          },
25        ],
26      },
27    },
28  ],
29})

Enable in Region

Enable the Redsys provider in your Medusa admin panel under Settings > Regions and select Redsys as a payment provider.

The provider ID will be:

pp_redsys_redsys

Options

Payment Flow

1. Customer selects Redsys as payment method
2. initiatePayment() creates a signed redirect form with Redsys merchant parameters
3. Customer clicks "Place Order" → storefront calls cart.complete() to create the order, then auto-submits the redirect form to Redsys TPV
4. Customer completes payment on the Redsys hosted payment page
5. Redsys sends a webhook notification to {backendUrl}/hooks/payment/redsys_redsys
6. getWebhookActionAndData() validates the HMAC-SHA256 signature and updates the payment status
7. Redsys redirects the customer's browser to successUrl or errorUrl

Important: authorizePayment Behavior

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

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. src/lib/constants.tsx — Register the payment method

Add Redsys to the payment info map and add a helper function:

1// Inside paymentInfoMap, add:
2pp_redsys_redsys: {
3  title: "Credit / Debit Card",
4  icon: <CreditCard />,
5},
6
7// Add helper function:
8export const isRedsys = (providerId?: string) => {
9  return providerId?.startsWith("pp_redsys_")
10}

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

Add a completeCartWithoutRedirect function. The standard placeOrder does a redirect() (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) {
2  const id = cartId || (await getCartId())
3
4  if (!id) {
5    throw new Error("No existing cart found when completing cart")
6  }
7
8  const headers = {
9    ...(await getAuthHeaders()),
10  }
11
12  const cartRes = await sdk.store.cart
13    .complete(id, {}, headers)
14    .then(async (cartRes) => {
15      const cartCacheTag = await getCacheTag("carts")
16      revalidateTag(cartCacheTag)
17      return cartRes
18    })
19    .catch(medusaError)
20
21  if (cartRes?.type === "order") {
22    const orderCacheTag = await getCacheTag("orders")
23    revalidateTag(orderCacheTag)
24    removeCartId()
25  }
26
27  return cartRes
28}

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

Add a RedsysPaymentButton component that:

1. Reads the payment session data (formUrl, merchantParams, signature) from the cart
2. Calls completeCartWithoutRedirect() to create the order
3. Dynamically builds and auto-submits a <form> to Redsys' TPV

1// Add import:
2import { isManual, isRedsys, isStripeLike } from "@lib/constants"
3import { completeCartWithoutRedirect, placeOrder } from "@lib/data/cart"
4
5// Add case in PaymentButton's switch:
6case isRedsys(paymentSession?.provider_id):
7  return (
8    <RedsysPaymentButton
9      notReady={notReady}
10      cart={cart}
11      data-testid={dataTestId}
12    />
13  )
14
15// Add the component:
16const RedsysPaymentButton = ({
17  cart,
18  notReady,
19  "data-testid": dataTestId,
20}: {
21  cart: HttpTypes.StoreCart
22  notReady: boolean
23  "data-testid"?: string
24}) => {
25  const [submitting, setSubmitting] = useState(false)
26  const [errorMessage, setErrorMessage] = useState<string | null>(null)
27
28  const handlePayment = async () => {
29    setSubmitting(true)
30
31    const paymentSession = cart.payment_collection?.payment_sessions?.find(
32      (s) => s.status === "pending" && isRedsys(s.provider_id)
33    )
34
35    const redsysData = paymentSession?.data as Record<string, string> | undefined
36
37    if (!redsysData?.formUrl || !redsysData?.merchantParams || !redsysData?.signature) {
38      setErrorMessage("No se pudieron obtener los datos de pago de Redsys")
39      setSubmitting(false)
40      return
41    }
42
43    const cartRes = await completeCartWithoutRedirect()
44      .catch((err) => {
45        setErrorMessage(err.message)
46        setSubmitting(false)
47        return null
48      })
49
50    if (!cartRes || cartRes.type !== "order") {
51      setErrorMessage(cartRes ? "Error al crear el pedido" : "")
52      setSubmitting(false)
53      return
54    }
55
56    const form = document.createElement("form")
57    form.method = "POST"
58    form.action = redsysData.formUrl
59
60    const fields: Record<string, string> = {
61      Ds_SignatureVersion: redsysData.signatureVersion,
62      Ds_MerchantParameters: redsysData.merchantParams,
63      Ds_Signature: redsysData.signature,
64    }
65
66    Object.entries(fields).forEach(([name, value]) => {
67      const input = document.createElement("input")
68      input.type = "hidden"
69      input.name = name
70      input.value = value
71      form.appendChild(input)
72    })
73
74    document.body.appendChild(form)
75    form.submit()
76  }
77
78  return (
79    <>
80      <Button
81        disabled={notReady || submitting}
82        isLoading={submitting}
83        onClick={handlePayment}
84        size="large"
85        data-testid={dataTestId}
86      >
87        Place order
88      </Button>
89      <ErrorMessage
90        error={errorMessage}
91        data-testid="redsys-payment-error-message"
92      />
93    </>
94  )
95}

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

Create the page Redsys redirects to after payment. It reads the orderId query param and redirects to the order confirmation page:

1import { retrieveOrder } from "@lib/data/orders"
2import { Metadata } from "next"
3import { redirect } from "next/navigation"
4
5export const metadata: Metadata = {
6  title: "Resultado del pago",
7  description: "Resultado de la operación con Redsys",
8}
9
10type Props = {
11  searchParams: Promise<{ [key: string]: string | undefined }>
12}
13
14export default async function RedsysCallbackPage(props: Props) {
15  const searchParams = await props.searchParams
16  const isError = searchParams.error === "1"
17  const orderId = searchParams.orderId
18
19  if (isError) {
20    return (
21      <div className="flex flex-col items-center justify-center min-h-[50vh] gap-4 p-8">
22        <h1 className="text-2xl font-bold text-red-600">Pago no completado</h1>
23        <p className="text-gray-600">
24          La operación no se ha completado correctamente.
25        </p>
26        <a href="/" className="mt-4 px-6 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700">
27          Volver a la tienda
28        </a>
29      </div>
30    )
31  }
32
33  if (orderId) {
34    try {
35      const order = await retrieveOrder(orderId)
36      if (order) {
37        const countryCode = order.shipping_address?.country_code?.toLowerCase() || "dk"
38        return redirect(`/${countryCode}/order/${orderId}/confirmed`)
39      }
40    } catch {
41      // Order not found, show success anyway
42    }
43  }
44
45  return (
46    <div className="flex flex-col items-center justify-center min-h-[50vh] gap-4 p-8">
47      <h1 className="text-2xl font-bold text-green-600">Pago procesado</h1>
48      <p className="text-gray-600">Tu pago ha sido procesado correctamente.</p>
49      <a href="/" className="mt-4 px-6 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700">
50        Volver a la tienda
51      </a>
52    </div>
53  )
54}

5. src/middleware.ts — 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 /checkout/redsys-callback is not redirected. Add this early in the middleware function:

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

6. medusa-config.ts — 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 data field returned by initiatePayment:

1{
2  orderId: "1234ABCD5678",
3  amount: "2550",
4  currency: "978",
5  status: "pending",
6  transactionType: "0",
7  merchantParams: "base64...",          // Base64-encoded merchant parameters
8  signature: "hmac...",                 // HMAC-SHA256 signature
9  signatureVersion: "HMAC_SHA256_V1",
10  formUrl: "https://sis-t.redsys.es:25443/sis/realizarPago"
11}

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

Webhook

Medusa automatically exposes a webhook endpoint for the Redsys provider at:

/hooks/payment/redsys_redsys

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

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

Test Cards (Sandbox)

Transaction Types

Security

• Never log PAN, CVV, or the secret key. The provider strips sensitive fields from log output.
• Always validate signatures server-side. getWebhookActionAndData() uses redsys-easy's processRestNotification() 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 (978). See src/types.ts 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/medusa-payment-redsys

License

MIT — see LICENSE file for details.

Support

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