@paykit-sdk/redsys 1.0.0

package/dist/redsys-provider.d.ts

@@ -0,0 +1,123 @@
+import { AbstractPayKitProvider, PayKitProvider, ProviderMetadataRegistry, PaykitProviderOptions, CreateCheckoutSchema, Checkout, UpdateCheckoutSchema, CreatePaymentSchema, Payment, UpdatePaymentSchema, CapturePaymentSchema, CreateCustomerParams, Customer, UpdateCustomerParams, CreateSubscriptionSchema, UpdateSubscriptionSchema, CreateRefundSchema, Refund, WebhookHandlerConfig, WebhookEventPayload } from '@paykit-sdk/core';
+
+interface RedsysOptions extends PaykitProviderOptions {
+    /**
+     * Redsys merchant code (Ds_Merchant_MerchantCode)
+     */
+    merchantCode: string;
+    /**
+     * Redsys terminal number (Ds_Merchant_Terminal)
+     */
+    terminal: string;
+    /**
+     * Secret key for HMAC-SHA256 signing (from Redsys backend)
+     */
+    secretKey: string;
+    /**
+     * Transaction type: "0" = immediate capture, "1" = pre-authorization
+     * @default "0"
+     */
+    transactionType?: '0' | '1';
+    /**
+     * Sandbox: https://sis-t..redsys.es:25443/sis/realizarPago
+     * Production: https://sis.redsys.es/sis/realizarPago
+     */
+    redsysUrl?: string;
+}
+/**
+ * Redsys inSite integration
+ *
+ * Flow:
+ * 1. createCheckout() → returns merchant parameters + signature for inSite iframe
+ * 2. Frontend loads redsysV3.js, renders inSite iframe with returned params
+ * 3. User enters card details in iframe → Redsys returns operationId
+ * 4. createPayment(operationId) → backend calls Redsys REST API to execute
+ * 5. handleWebhook() → processes server-side notifications from Redsys
+ */
+interface RedsysMetadata extends ProviderMetadataRegistry {
+    checkout: {
+        /** Currency numeric code (e.g., 978 for EUR) */
+        currency?: number;
+        /** Order ID generated by PayKit */
+        orderId?: string;
+    };
+    payment: {
+        /** Operation ID from inSite iframe */
+        operationId?: string;
+    };
+}
+type RedsysRawEvents = {
+    [K in `redsys.${string}`]: Record<string, unknown>;
+};
+declare class RedsysProvider extends AbstractPayKitProvider implements PayKitProvider<RedsysMetadata, never, RedsysRawEvents> {
+    private readonly opts;
+    private readonly _client;
+    readonly isSandbox: boolean;
+    constructor(opts: RedsysOptions);
+    readonly providerName = "redsys";
+    get _native(): never;
+    private _getRedsysUrl;
+    private _getCurrencyNum;
+    private _generateOrderId;
+    /**
+     * Build the Base64-encoded merchant parameters for inSite
+     */
+    private _buildMerchantParams;
+    /**
+     * Generate HMAC-SHA256 signature for inSite
+     *
+     * Signature = HMAC-SHA256(secretKey, base64(params) + orderId)
+     * Order is important: base64Params + orderId (both as-is, no separators)
+     */
+    private _sign;
+    /**
+     * 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: (params: CreateCheckoutSchema<RedsysMetadata["checkout"]>) => Promise<Checkout>;
+    retrieveCheckout: (id: string) => Promise<Checkout>;
+    updateCheckout: (id: string, _params: UpdateCheckoutSchema<RedsysMetadata["checkout"]>) => Promise<Checkout>;
+    deleteCheckout: (_id: string) => Promise<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: (params: CreatePaymentSchema<RedsysMetadata["payment"]>) => Promise<Payment>;
+    /**
+     * Execute payment via Redsys REST API
+     */
+    private _executePayment;
+    retrievePayment: (id: string) => Promise<Payment | null>;
+    updatePayment: (id: string, _params: UpdatePaymentSchema<RedsysMetadata["payment"]>) => Promise<Payment>;
+    deletePayment: (_id: string) => Promise<null>;
+    capturePayment: (id: string, _params: CapturePaymentSchema) => Promise<Payment>;
+    cancelPayment: (id: string) => Promise<Payment>;
+    createCustomer: (params: CreateCustomerParams<RedsysMetadata["customer"]>) => Promise<Customer>;
+    retrieveCustomer: (_id: string) => Promise<Customer | null>;
+    updateCustomer: (id: string, _params: UpdateCustomerParams<RedsysMetadata["customer"]>) => Promise<Customer>;
+    deleteCustomer: (_id: string) => Promise<null>;
+    createSubscription: (_params: CreateSubscriptionSchema<RedsysMetadata["subscription"]>) => Promise<never>;
+    retrieveSubscription: (_id: string) => Promise<never>;
+    updateSubscription: (_id: string, _params: UpdateSubscriptionSchema<RedsysMetadata["subscription"]>) => Promise<never>;
+    deleteSubscription: (_id: string) => Promise<null>;
+    cancelSubscription: (_id: string) => Promise<never>;
+    createRefund: (params: CreateRefundSchema<RedsysMetadata["refund"]>) => Promise<Refund>;
+    private _refundPayment;
+    /**
+     * Handle Redsys webhook notifications
+     *
+     * Redsys sends POST to notificationUrl with:
+     * - Ds_MerchantParameters (Base64 encoded response)
+     * - Ds_Signature (HMAC signature)
+     * - Ds_SignatureVersion
+     */
+    handleWebhook: (payload: WebhookHandlerConfig, _webhookSecret: string) => Promise<Array<WebhookEventPayload<RedsysRawEvents>>>;
+    private _notSupported;
+}
+
+export { type RedsysOptions, RedsysProvider };

package/dist/redsys-provider.js

@@ -0,0 +1,522 @@
+'use strict';
+
+var core = require('@paykit-sdk/core');
+var crypto = require('crypto');
+
+// src/redsys-provider.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 }
+    );
+  }
+};
+
+exports.RedsysProvider = RedsysProvider;