@paykit-sdk/redsys 1.0.0

package/README.md

@@ -0,0 +1,96 @@
+# @paykit-sdk/redsys
+
+Redsys inSite provider for PayKit.
+
+## Overview
+
+This package integrates Redsys's inSite payment method into PayKit. inSite allows customers to enter their card details directly on your website through secure iframes hosted by Redsys, without redirecting to an external payment page.
+
+## Installation
+
+```bash
+npm install @paykit-sdk/redsys
+# or
+pnpm add @paykit-sdk/redsys
+```
+
+## Quick Start
+
+```typescript
+import { createEndpointHandlers, PayKit } from '@paykit-sdk/core';
+import { redsys } from '@paykit-sdk/redsys';
+
+// Configure the provider
+const provider = redsys();
+// or with manual config:
+import { createRedsys } from '@paykit-sdk/redsys';
+const provider = createRedsys({
+  merchantCode: process.env.REDSYS_MERCHANT_CODE,
+  terminal: process.env.REDSYS_TERMINAL,
+  secretKey: process.env.REDSYS_SECRET_KEY,
+  environment: 'sandbox', // or 'production'
+  transactionType: '0',   // '0' = immediate, '1' = pre-auth
+});
+
+export const paykit = new PayKit(provider);
+export const endpoints = createEndpointHandlers(paykit);
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `REDSYS_MERCHANT_CODE` | Your Redsys merchant code |
+| `REDSYS_TERMINAL` | Terminal number |
+| `REDSYS_SECRET_KEY` | HMAC-SHA256 secret key from Redsys backend |
+| `REDSYS_TRANSACTION_TYPE` | `"0"` (immediate) or `"1"` (pre-authorization) |
+
+## Flow
+
+1. **Create Checkout** → returns merchant parameters + signature for inSite iframe
+2. **Frontend loads inSite** → renders secure card input iframes
+3. **User enters card** → Redsys returns `operationId`
+4. **Create Payment** → pass `operationId` in `provider_metadata.operationId`
+5. **Webhooks** → server-side notifications for payment status
+
+## Frontend Integration
+
+The `createCheckout` response includes inSite parameters in metadata:
+
+```typescript
+const checkout = await paykit.createCheckout(params);
+
+// These fields from checkout.metadata are needed for inSite:
+const { 
+  redsys_merchant_params,
+  redsys_signature,
+  redsys_signature_version,
+  redsys_merchant_code,
+  redsys_terminal,
+} = checkout.metadata;
+```
+
+Load the Redsys inSite script and initialize:
+
+```html
+<script src="https://sis-t.REDsys.es:25443/sis/rest/register/v2/redsysV3.js"></script>
+
+<script>
+  // After checkout is created:
+  getInSiteForm(
+    'card-form',           // container ID
+    {},                    // button styles
+    {},                    // body styles
+    {},                    // box styles
+    {},                    // input styles
+    'Pay now',             // button text (HTML encoded)
+    callbackFunction,       // callback with operationId
+    terminal,
+    orderId
+  );
+</script>
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,7 @@
+import { RedsysOptions, RedsysProvider } from './redsys-provider.mjs';
+import '@paykit-sdk/core';
+
+declare const createRedsys: (config: RedsysOptions) => RedsysProvider;
+declare const redsys: () => RedsysProvider;
+
+export { RedsysOptions, RedsysProvider, createRedsys, redsys };

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import { RedsysOptions, RedsysProvider } from './redsys-provider.js';
+import '@paykit-sdk/core';
+
+declare const createRedsys: (config: RedsysOptions) => RedsysProvider;
+declare const redsys: () => RedsysProvider;
+
+export { RedsysOptions, RedsysProvider, createRedsys, redsys };

package/dist/index.js

@@ -0,0 +1,543 @@
+'use strict';
+
+var core = require('@paykit-sdk/core');
+var crypto = require('crypto');
+
+// src/index.ts
+var RedsysOptionsSchema = core.schema()(
+  core.Schema.object({
+    merchantCode: core.Schema.string().min(1),
+    terminal: core.Schema.string().min(1),
+    secretKey: core.Schema.string().min(1),
+    isSandbox: core.Schema.boolean(),
+    transactionType: core.Schema.enum(["0", "1"]).optional(),
+    redsysUrl: core.Schema.string().optional(),
+    debug: core.Schema.boolean().optional()
+  })
+);
+var PROVIDER_NAME = "redsys";
+var CURRENCY_MAP = {
+  EUR: 978,
+  USD: 840,
+  GBP: 826,
+  JPY: 392
+};
+var RESPONSE_CODES = {
+  "0000": "Transaction approved",
+  "0101": "Card expired",
+  "0102": "Card temporarily blocked",
+  "0106": "Attempts exceeded",
+  "0116": "Insufficient balance",
+  "0129": "Invalid card security code",
+  "0184": "Cardholder authentication failed",
+  "0190": "Card issuer unavailable",
+  "0904": "Merchant not registered"
+};
+var RedsysProvider = class extends core.AbstractPayKitProvider {
+  opts;
+  _client;
+  isSandbox;
+  constructor(opts) {
+    super(RedsysOptionsSchema, opts, PROVIDER_NAME);
+    this.opts = opts;
+    this.isSandbox = opts.isSandbox ?? false;
+    this._client = new core.HTTPClient({
+      baseUrl: this._getRedsysUrl(),
+      headers: { "Content-Type": "application/json" },
+      retryOptions: { max: 3, baseDelay: 1e3, debug: false }
+    });
+  }
+  providerName = PROVIDER_NAME;
+  get _native() {
+    throw new core.NotImplementedError(
+      "Native SDK not available for Redsys. Use inSite iframe.",
+      this.providerName,
+      { futureSupport: true }
+    );
+  }
+  _getRedsysUrl() {
+    if (this.opts.redsysUrl) return this.opts.redsysUrl;
+    return this.opts.isSandbox ? "https://sis.redsys.es/sis/realizarPago" : "https://sis-t.REDsys.es:25443/sis/realizarPago";
+  }
+  _getCurrencyNum(currency) {
+    return CURRENCY_MAP[currency.toUpperCase()] ?? 978;
+  }
+  _generateOrderId() {
+    return crypto.randomBytes(6).toString("hex").toUpperCase();
+  }
+  /**
+   * Build the Base64-encoded merchant parameters for inSite
+   */
+  _buildMerchantParams(orderId, amount, currency) {
+    const currencyNum = this._getCurrencyNum(currency);
+    const params = {
+      DS_MERCHANT_MERCHANTCODE: this.opts.merchantCode,
+      DS_MERCHANT_TERMINAL: this.opts.terminal,
+      DS_MERCHANT_ORDER: orderId,
+      DS_MERCHANT_AMOUNT: String(amount),
+      DS_MERCHANT_CURRENCY: String(currencyNum),
+      DS_MERCHANT_TRANSACTIONTYPE: this.opts.transactionType ?? "0",
+      DS_MERCHANT_CONSUMERLANGUAGE: "1",
+      DS_MERCHANT_PRODUCTDESCRIPTION: "Payment",
+      DS_MERCHANT_TITULAR: ""
+    };
+    const jsonStr = JSON.stringify(params);
+    return Buffer.from(jsonStr).toString("base64");
+  }
+  /**
+   * Generate HMAC-SHA256 signature for inSite
+   *
+   * Signature = HMAC-SHA256(secretKey, base64(params) + orderId)
+   * Order is important: base64Params + orderId (both as-is, no separators)
+   */
+  _sign(orderId, base64Params) {
+    const data = base64Params + orderId;
+    return crypto.createHmac(
+      "sha256",
+      Buffer.from(this.opts.secretKey, "base64")
+    ).update(data).digest("base64").replace(/\+/g, "-").replace(/\//g, "/").replace(/=+$/, "");
+  }
+  /**
+   * Create checkout for inSite
+   *
+   * Returns merchant parameters and signature for the frontend iframe.
+   * The frontend will load redsysV3.js and render the inSite form.
+   */
+  createCheckout = async (params) => {
+    const { error, data } = core.createCheckoutSchema.safeParse(params);
+    if (error) {
+      throw core.ValidationError.fromZodError(
+        error,
+        this.providerName,
+        "createCheckout"
+      );
+    }
+    const { amount: rawAmount, currency = "EUR" } = core.validateRequiredKeys(
+      ["amount", "currency"],
+      data.metadata ?? {},
+      "The following fields must be present in the metadata of createCheckout: {keys}"
+    );
+    const orderId = data.metadata?.orderId ?? this._generateOrderId();
+    const amount = Math.round(Number(rawAmount));
+    const merchantParams = this._buildMerchantParams(
+      orderId,
+      amount,
+      currency
+    );
+    const signature = this._sign(orderId, merchantParams);
+    let customer = null;
+    if (core.isIdCustomer(data.customer)) {
+      customer = { id: data.customer.id };
+    } else if (core.isEmailCustomer(data.customer)) {
+      customer = { email: data.customer.email };
+    }
+    return {
+      id: `redsys_${orderId}`,
+      customer,
+      session_type: "one_time",
+      payment_url: this._getRedsysUrl(),
+      products: [{ id: data.item_id, quantity: data.quantity }],
+      currency,
+      amount,
+      subscription: null,
+      metadata: {
+        ...core.stringifyMetadataValues(data.metadata ?? {}),
+        [core.PAYKIT_METADATA_KEY]: JSON.stringify({ orderId, currency }),
+        // These are passed to frontend for inSite initialization
+        redsys_merchant_params: merchantParams,
+        redsys_signature: signature,
+        redsys_signature_version: "HMAC_SHA256_V1",
+        redsys_merchant_code: this.opts.merchantCode,
+        redsys_terminal: this.opts.terminal
+      }
+    };
+  };
+  retrieveCheckout = async (id) => {
+    throw new core.ResourceNotFoundError(
+      "checkout",
+      id,
+      this.providerName
+    );
+  };
+  updateCheckout = async (id, _params) => {
+    throw new core.NotImplementedError(
+      "updateCheckout",
+      this.providerName,
+      { futureSupport: true }
+    );
+  };
+  deleteCheckout = async (_id) => {
+    return null;
+  };
+  /**
+   * Create payment using operation ID from inSite
+   *
+   * The operation ID is returned by the inSite iframe when the user
+   * completes the card entry. The frontend should pass it in
+   * provider_metadata.operationId.
+   */
+  createPayment = async (params) => {
+    const { error, data } = core.createPaymentSchema.safeParse(params);
+    if (error) {
+      throw core.ValidationError.fromZodError(
+        error,
+        this.providerName,
+        "createPayment"
+      );
+    }
+    const operationId = data.provider_metadata?.operationId;
+    if (!operationId) {
+      throw new core.ValidationError(
+        "operationId is required for Redsys inSite payments. Pass it in provider_metadata.operationId.",
+        {
+          provider: this.providerName,
+          method: "createPayment",
+          field: "operationId"
+        }
+      );
+    }
+    const metadataItem = JSON.parse(
+      data.metadata?.[core.PAYKIT_METADATA_KEY] ?? "{}"
+    );
+    const orderId = metadataItem.orderId;
+    const result = await this._executePayment(
+      orderId,
+      operationId,
+      Number(data.amount),
+      String(data.currency)
+    );
+    if (result.Ds_Response === "0000" || String(result.Ds_Response).startsWith("00")) {
+      return {
+        id: result.Ds_AuthorisationCode ? `${orderId}_${result.Ds_AuthorisationCode}` : operationId,
+        amount: data.amount,
+        currency: data.currency,
+        customer: data.customer ? typeof data.customer === "string" ? { id: data.customer } : data.customer : null,
+        status: "succeeded",
+        metadata: core.stringifyMetadataValues(data.metadata ?? {}),
+        item_id: data.item_id,
+        requires_action: false,
+        payment_url: null
+      };
+    }
+    throw new core.OperationFailedError(
+      `Payment failed: ${RESPONSE_CODES[String(result.Ds_Response)] ?? `Code ${result.Ds_Response}`}`,
+      this.providerName,
+      { cause: new Error(JSON.stringify(result)) }
+    );
+  };
+  /**
+   * Execute payment via Redsys REST API
+   */
+  async _executePayment(orderId, operationId, amount, currency) {
+    const currencyNum = this._getCurrencyNum(currency);
+    const amountStr = String(amount);
+    const params = {
+      DS_MERCHANT_MERCHANTCODE: this.opts.merchantCode,
+      DS_MERCHANT_TERMINAL: this.opts.terminal,
+      DS_MERCHANT_ORDER: orderId,
+      DS_MERCHANT_AMOUNT: amountStr,
+      DS_MERCHANT_CURRENCY: String(currencyNum),
+      DS_MERCHANT_TRANSACTIONTYPE: this.opts.transactionType ?? "0",
+      DS_MERCHANT_IDOPERACION: operationId
+    };
+    const base64Params = Buffer.from(JSON.stringify(params)).toString(
+      "base64"
+    );
+    const signature = this._sign(orderId, base64Params);
+    const { ok, value: result } = await this._client.post("/", {
+      body: JSON.stringify({
+        Ds_SignatureVersion: "HMAC_SHA256_V1",
+        Ds_MerchantParameters: base64Params,
+        Ds_Signature: signature
+      })
+    });
+    if (!ok || !result) {
+      throw new core.OperationFailedError(
+        "Redsys REST API error: request failed",
+        this.providerName
+      );
+    }
+    return result;
+  }
+  retrievePayment = async (id) => {
+    throw new core.NotImplementedError(
+      "retrievePayment",
+      this.providerName,
+      {
+        futureSupport: true
+      }
+    );
+  };
+  updatePayment = async (id, _params) => {
+    throw new core.NotImplementedError(
+      "updatePayment",
+      this.providerName,
+      { futureSupport: true }
+    );
+  };
+  deletePayment = async (_id) => {
+    return null;
+  };
+  capturePayment = async (id, _params) => {
+    if (this.opts.transactionType === "1") {
+      throw new core.NotImplementedError(
+        "capturePayment",
+        this.providerName,
+        { futureSupport: true }
+      );
+    }
+    throw new core.NotImplementedError(
+      "capturePayment only available for pre-authorization (transactionType=1)",
+      this.providerName
+    );
+  };
+  cancelPayment = async (id) => {
+    throw new core.NotImplementedError(
+      "cancelPayment",
+      this.providerName,
+      { futureSupport: true }
+    );
+  };
+  createCustomer = async (params) => {
+    throw new core.ProviderNotSupportedError("createCustomer", "gopay", {
+      reason: "Redsys doesn't support creating customers"
+    });
+  };
+  retrieveCustomer = async (_id) => {
+    return null;
+  };
+  updateCustomer = async (id, _params) => {
+    throw new core.NotImplementedError(
+      "updateCustomer",
+      this.providerName,
+      { futureSupport: true }
+    );
+  };
+  deleteCustomer = async (_id) => {
+    return null;
+  };
+  createSubscription = async (_params) => {
+    return this._notSupported("createSubscription");
+  };
+  retrieveSubscription = async (_id) => {
+    return this._notSupported("retrieveSubscription");
+  };
+  updateSubscription = async (_id, _params) => {
+    return this._notSupported("updateSubscription");
+  };
+  deleteSubscription = async (_id) => {
+    return this._notSupported("deleteSubscription");
+  };
+  cancelSubscription = async (_id) => {
+    return this._notSupported("cancelSubscription");
+  };
+  createRefund = async (params) => {
+    const { error, data } = core.createRefundSchema.safeParse(params);
+    if (error) {
+      throw core.ValidationError.fromZodError(
+        error,
+        this.providerName,
+        "createRefund"
+      );
+    }
+    const { currency = "EUR" } = core.validateRequiredKeys(
+      ["currency"],
+      data.metadata ?? {},
+      "The following fields must be present in the metadata of createRefund: {keys}"
+    );
+    const metadataItem = JSON.parse(
+      data.metadata?.[core.PAYKIT_METADATA_KEY] ?? "{}"
+    );
+    const orderId = metadataItem.orderId;
+    if (!orderId) {
+      throw new core.ValidationError(
+        "orderId not found in payment metadata",
+        {
+          provider: this.providerName,
+          method: "createRefund",
+          field: "orderId"
+        }
+      );
+    }
+    const result = await this._refundPayment(
+      orderId,
+      data.amount,
+      currency
+    );
+    const code = String(result.Ds_Response ?? result.Ds_Restock);
+    if (code === "0000" || code.startsWith("00")) {
+      return {
+        id: `refund_${crypto.randomBytes(4).toString("hex")}`,
+        amount: data.amount,
+        currency,
+        reason: "refund",
+        metadata: {}
+      };
+    }
+    throw new core.OperationFailedError(
+      `Refund failed: ${RESPONSE_CODES[code] ?? `Code ${code}`}`,
+      this.providerName,
+      { cause: new Error(JSON.stringify(result)) }
+    );
+  };
+  async _refundPayment(orderId, amount, currency) {
+    const currencyNum = this._getCurrencyNum(currency);
+    const params = {
+      DS_MERCHANT_MERCHANTCODE: this.opts.merchantCode,
+      DS_MERCHANT_TERMINAL: this.opts.terminal,
+      DS_MERCHANT_ORDER: orderId,
+      DS_MERCHANT_AMOUNT: String(amount),
+      DS_MERCHANT_CURRENCY: String(currencyNum),
+      DS_MERCHANT_TRANSACTIONTYPE: "3"
+      // Refund
+    };
+    const base64Params = Buffer.from(JSON.stringify(params)).toString(
+      "base64"
+    );
+    const signature = this._sign(orderId, base64Params);
+    const { ok, value: result } = await this._client.post("/", {
+      body: JSON.stringify({
+        Ds_SignatureVersion: "HMAC_SHA256_V1",
+        Ds_MerchantParameters: base64Params,
+        Ds_Signature: signature
+      })
+    });
+    if (!ok || !result) {
+      throw new core.OperationFailedError(
+        "Redsys REST API error: refund failed",
+        this.providerName
+      );
+    }
+    return result;
+  }
+  /**
+   * Handle Redsys webhook notifications
+   *
+   * Redsys sends POST to notificationUrl with:
+   * - Ds_MerchantParameters (Base64 encoded response)
+   * - Ds_Signature (HMAC signature)
+   * - Ds_SignatureVersion
+   */
+  handleWebhook = async (payload, _webhookSecret) => {
+    const { body } = payload;
+    const dataAsObject = JSON.parse(body);
+    const paramsBase64 = dataAsObject.Ds_MerchantParameters;
+    if (!paramsBase64) {
+      throw new core.WebhookError("Missing Ds_MerchantParameters", {
+        provider: this.providerName
+      });
+    }
+    const paramsJson = Buffer.from(paramsBase64, "base64").toString(
+      "utf-8"
+    );
+    const params = JSON.parse(paramsJson);
+    const dsResponse = String(params.Ds_Response ?? "");
+    const dsOrder = params.Ds_Order;
+    const dsAmount = params.Ds_Amount;
+    const dsMerchantData = params.Ds_MerchantData;
+    const signature = dataAsObject.Ds_Signature;
+    const expectedSig = this._sign(dsOrder, paramsBase64);
+    const sigOk = signature === expectedSig;
+    if (!sigOk) {
+      throw new core.WebhookError("Invalid Redsys webhook signature", {
+        provider: this.providerName
+      });
+    }
+    const events = [];
+    if (dsResponse === "0000" || dsResponse.startsWith("00")) {
+      const customerId = core.parseJSON(
+        Buffer.from(dsMerchantData, "base64").toString("utf-8"),
+        core.Schema.object({
+          customerId: core.Schema.string().optional()
+        })
+      )?.customerId ?? null;
+      const amountNum = Number(dsAmount) / 100;
+      const paymentId = `${dsOrder}_${params.Ds_AuthorisationCode ?? "unknown"}`;
+      events.push(
+        {
+          event: "redsys.payment.succeeded",
+          data: {
+            order_id: dsOrder,
+            amount: amountNum,
+            response_code: dsResponse,
+            customer_id: customerId
+          }
+        },
+        core.paykitEvent$InboundSchema({
+          type: "payment.succeeded",
+          created: (/* @__PURE__ */ new Date()).getTime(),
+          id: crypto.randomBytes(8).toString("hex").slice(0, 15),
+          data: {
+            id: paymentId,
+            amount: amountNum,
+            currency: "EUR",
+            customer: customerId ? { id: customerId } : null,
+            status: "succeeded",
+            metadata: {},
+            item_id: null,
+            requires_action: false,
+            payment_url: null
+          }
+        })
+      );
+    } else {
+      events.push(
+        {
+          event: "redsys.payment.failed",
+          data: {
+            order_id: dsOrder,
+            response_code: dsResponse,
+            error_message: RESPONSE_CODES[dsResponse] ?? `Code ${dsResponse}`
+          }
+        },
+        core.paykitEvent$InboundSchema({
+          type: "payment.failed",
+          created: (/* @__PURE__ */ new Date()).getTime(),
+          id: crypto.randomBytes(8).toString("hex").slice(0, 15),
+          data: {
+            id: dsOrder,
+            amount: Number(dsAmount) / 100,
+            currency: "EUR",
+            customer: null,
+            status: "failed",
+            metadata: {},
+            item_id: null,
+            requires_action: false,
+            payment_url: null
+          }
+        })
+      );
+    }
+    return events;
+  };
+  _notSupported(method) {
+    throw new core.NotImplementedError(
+      `Redsys doesn't support ${method}`,
+      this.providerName,
+      { futureSupport: true }
+    );
+  }
+};
+
+// src/index.ts
+var createRedsys = (config) => new RedsysProvider(config);
+var redsys = () => {
+  const envVars = core.validateRequiredKeys(
+    ["REDSYS_MERCHANT_CODE", "REDSYS_TERMINAL", "REDSYS_SECRET_KEY"],
+    process.env ?? {},
+    "Missing required environment variables: {keys}"
+  );
+  const isSandbox = process.env.NODE_ENV !== "production";
+  return createRedsys({
+    merchantCode: envVars.REDSYS_MERCHANT_CODE,
+    terminal: envVars.REDSYS_TERMINAL,
+    secretKey: envVars.REDSYS_SECRET_KEY,
+    isSandbox,
+    debug: isSandbox,
+    transactionType: process.env.REDSYS_TRANSACTION_TYPE ?? "0"
+  });
+};
+
+exports.RedsysProvider = RedsysProvider;
+exports.createRedsys = createRedsys;
+exports.redsys = redsys;