Overview

@cap-kit/redsys is a Capacitor v8 plugin that bridges the official Redsys InApp SDK for iOS and Android.

It provides:

• A platform-agnostic JavaScript API
• Native SDK orchestration
• Unified response structure across platforms
• Standardized error handling
• Built-in HMAC signature utilities
• Optional UI customization via capacitor.config.ts

The plugin follows a strict layered architecture:

• Bridge Layer → Handles Capacitor calls
• Implementation Layer → Orchestrates native SDK
• Utils Layer → Mapping & crypto utilities
• Config Layer → Immutable runtime configuration

Supported Flows

Direct Payment

Fully native card entry flow handled by the Redsys SDK.

await Redsys.doDirectPayment({
  order: 'ORDER123',
  amount: 25.5,
  transactionType: 'normal',
});

Installation

pnpm add @cap-kit/redsys
# or
npm install @cap-kit/redsys
# or
yarn add @cap-kit/redsys
# then run:
npx cap sync

Native SDK Distribution & Setup

For licensing and compliance reasons, the Redsys SDK binaries are not bundled with this package. You must obtain the official binaries and use the provided orchestrator script to configure your native projects.

1. Prepare the Binaries

Create a folder named sdks/ in your project root (next to package.json) and place the official files inside:

• Android: redsys-sdk-inApp-2.4.5.aar (Download from Redsys Portal)
• iOS: TPVVInLibrary.xcframework (Download from the same portal)

2. Run the Orchestrator Script

Execute the following command to distribute the SDKs to the persistent native directories:

npm run setup-redsys-sdk

This script performs two critical actions:

• Android: Generates a persistent local Maven repository in android/app/libs/.
• iOS: Moves the framework to ios/App/ for manual embedding.

Platform Specific Configuration

🤖 Android

Update your Gradle files to recognize the persistent repository generated by the script:

android/build.gradle (Project Root):

allprojects {
    repositories {
        // ... other repos
        maven { url "${rootProject.projectDir}/app/libs" }
    }
}

android/app/build.gradle (App Module):

dependencies {
    implementation project(':cap-kit-redsys')
    // This resolves the dependency from your persistent local libs folder
    implementation "com.redsys.tpvvinapplibrary:redsys-sdk-inApp:2.4.5"
}

🍎 iOS (Xcode 26)

1. Add to Project: Open Xcode, right-click the App folder, select Add Files to "App"..., and choose ios/App/TPVVInLibrary.xcframework.
2. Embedding: In your App Target settings (General tab), find Frameworks, Libraries, and Embedded Content and ensure the SDK is set to Embed & Sign.

Final Directory Structure

After running the script, your project will follow this professional persistent layout:

my-capacitor-app/
├── sdks/                          <-- Your Source Binaries
│   ├── redsys-sdk-inApp-2.4.5.aar
│   └── TPVVInLibrary.xcframework
├── android/
│   └── app/
│       └── libs/                  <-- Generated Persistent Maven Repo
│           └── com/redsys/tpvvinapplibrary/redsys-sdk-inApp/
│               ├── maven-metadata.xml
│               └── 2.4.5/
│                   ├── redsys-sdk-inApp-2.4.5.aar
│                   └── redsys-sdk-inApp-2.4.5.pom
└── ios/
    └── App/
        └── TPVVInLibrary.xcframework <-- Persistent Binary

Web Payment Workflow (3-D Secure)

The WebView payment flow requires a server-side signature to ensure transaction integrity. The process follows these steps:

1. Initialize: Call initializeWebPayment() to get the base64Data.
2. Sign: Send base64Data to your backend. Your server signs it using your Merchant Secret Key.
3. Process: Call processWebPayment({ signature: '...' }) with the signature from your server.

Signature Generation (HMAC)

The signature must be an HMAC-SHA256 (or SHA512) hash.

⚠️ Security Warning

Never store your Merchant Secret Key inside the mobile application. Doing so exposes your credentials to decompilation. Always generate signatures on a secure backend.

Using computeHash (Testing Only)

For development and rapid prototyping, the plugin provides a native helper to generate signatures locally:

import { Redsys, RedsysTransactionType } from '@cap-kit/redsys';

// 1. Get transaction data
const { base64Data } = await Redsys.initializeWebPayment({
  order: 'ORDER123',
  amount: 25.5,
  transactionType: RedsysTransactionType.Normal,
});

// 2. Generate hash locally (ONLY FOR TESTING)
const { signature } = await Redsys.computeHash({
  data: base64Data,
  keyBase64: 'YOUR_TEST_SECRET_KEY', // Base64 encoded key
  algorithm: 'HMAC_SHA256_V1',
});

// 3. Open the secure WebView
const result = await Redsys.processWebPayment({ signature });

Production Implementation (Recommended)

In production, your backend should perform the signature calculation following the official Redsys logic:

1. Base64 decode your Merchant Key.
2. Generate a derived key using 3DES with the order number.
3. Compute the HMAC-SHA256 of the base64Data using that derived key.
4. Base64 encode the final result.

Configuration

Configuration options for the Redsys plugin.

| Prop | Type | Description | Default | Since | | ------------------------------ | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----- | | verboseLogging | boolean | Enables verbose native logging. When enabled, additional debug information is printed to the native console (Logcat on Android, Xcode on iOS). | false | 8.0.0 | | signature | string | Optional global merchant signature for web payments. If provided, it acts as a default when not passed in the method call. | | 8.0.0 | | license | string | Application license. Alphanumeric code provided by Redsys to validate the application. | | 8.0.0 | | environment | RedsysEnvironment | Transaction environment. Maps to ENVIRONMENT_TEST/REAL (Android) or EnviromentType (iOS). | | 8.0.0 | | fuc | string | Merchant identification code (FUC). | | 8.0.0 | | terminal | string | Terminal identifier associated with the merchant. | | 8.0.0 | | currency | string | ISO-4217 currency code. Default is "978" (EUR). | | 8.0.0 | | merchantName | string | Name of the payment titular. | | | | merchantUrl | string | URL of the commerce. | | 8.0.0 | | merchantData | string | Additional merchant data (internal references, etc.). | | 8.0.0 | | merchantDescription | string | Commerce descriptor or description. | | 8.0.0 | | merchantGroup | string | FUC of the merchant group for inter-merchant references. | | 8.0.0 | | merchantConsumerLanguage | RedsysLanguage | Global merchant language setting. Maps to TPVVConfiguration.setLanguage (Android) or appMerchantConsumerLanguage (iOS). | | 8.0.0 | | transactionType | RedsysTransactionType | Default transaction type for the application. Maps to TransactionType constants. | | 8.0.0 | | paymentMethods | RedsysPaymentMethod[] | Payment method(s) to be displayed in WebView flow. | | 8.0.0 | | enableRedirection | boolean | Enables automatic redirection to the bank's 3DS page when required. If false, the plugin will return a specific error code for 3DS requirements, allowing the application to handle redirection manually. | true | 8.0.0 | | enableResultAlert | boolean | Enables display of result alerts after payment completion. If false, the plugin will return the result data without showing native alerts, allowing the application to handle result presentation. | true | 8.0.0 | | ui | RedsysUIOptions | Native UI customization options. | | 8.0.0 |

Examples

In capacitor.config.json:

{
  "plugins": {
    "Redsys": {
      "verboseLogging": true,
      "license": "your_license_here",
      "environment": "RedsysEnvironment.Test",
      "fuc": "XXXXXXXXXXX",
      "terminal": "XX",
      "currency": "978",
      "merchantUrl": "XXX",
      "merchantData": "XXX",
      "merchantDescription": "XXX",
      "merchantGroup": "XXX",
      "paymentMethods": "XXX",
      "enableRedirection": true,
      "enableResultAlert": true,
      "ui": {}
    }
  }
}

In capacitor.config.ts:

/// <reference types="@cap-kit/redsys" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    Redsys: {
      verboseLogging: true,
      license: 'your_license_here',
      environment: 'RedsysEnvironment.Test',
      fuc: 'XXXXXXXXXXX',
      terminal: 'XX',
      currency: '978',
      merchantUrl: 'XXX',
      merchantData: 'XXX',
      merchantDescription: 'XXX',
      merchantGroup: 'XXX',
      paymentMethods: 'XXX',
      enableRedirection: true,
      enableResultAlert: true,
      ui: {

      },
    },
  },
};

export default config;

UI Customization: Logo & Assets

The logo property in capacitor.config.ts allows you to brand the native payment interface. Since logos cannot be passed as remote URLs for security and performance reasons, you must provide them as native assets.

1. Define the logo name

In your capacitor.config.ts, set the logo property to the resource name (without extension):

Redsys: {
  ui: {
    logo: 'logo_merchant',
    // ...
  }
}

2. Add the assets to Native Projects

🤖 Android Implementation:

• Place your image (e.g., logo_merchant.png) in the android/app/src/main/res/drawable/ folder.
• Use lowercase letters and underscores only (e.g., logo_merchant).

🍎 iOS Implementation:

• Open your project in Xcode and navigate to App/App/Assets.
• Create a new Image Set named exactly logo_merchant.
• Provide the @1x, @2x, and @3x versions of your logo.

Tip: Use a PNG with a transparent background for the best visual result on the Redsys payment screen.

API

• doDirectPayment(...)
• initializeWebPayment(...)
• processWebPayment(...)
• computeHash(...)
• getPluginVersion()
• Interfaces
• Enums

Public JavaScript API for the Redsys Capacitor plugin.

This interface defines a stable, platform-agnostic API. All methods behave consistently across Android, iOS, and Web.

doDirectPayment(...)

doDirectPayment(options: RedsysPaymentRequest) => Promise<RedsysPaymentResponseOK>

Executes a direct payment (Native SDK UI). No 3DS support.

| Param | Type | | ------------- | --------------------------------------------------------------------- | | options | RedsysPaymentRequest |

Returns: Promise<RedsysPaymentResponseOK>

Since: 8.0.0

Example

const result = await Redsys.doDirectPayment({
  order: '12345',
  amount: 1000,
  transactionType: RedsysTransactionType.Normal,
  description: 'Test Product',
  identifier: 'REQUEST_REFERENCE',
  extraParams: { customKey: 'customValue' },
  uiOptions: { confirmButtonText: 'Pay Now' }
});

initializeWebPayment(...)

initializeWebPayment(options: RedsysPaymentRequest) => Promise<RedsysWebPaymentInitResult>

Web Payment: Initializes and returns Base64 data for signing.

| Param | Type | | ------------- | --------------------------------------------------------------------- | | options | RedsysPaymentRequest |

Returns: Promise<RedsysWebPaymentInitResult>

Since: 8.0.0

Example

const initResult = await Redsys.initializeWebPayment({
  order: '12345',
  amount: 1000,
  transactionType: RedsysTransactionType.Normal,
  description: 'Test Product',
  identifier: 'REQUEST_REFERENCE',
  extraParams: { customKey: 'customValue' },
  uiOptions: { confirmButtonText: 'Pay Now' }
});

processWebPayment(...)

processWebPayment(options: RedsysWebPaymentOptions) => Promise<RedsysPaymentResponseOK>

Web Payment: Executes WebView flow with the server-generated signature.

| Param | Type | | ------------- | --------------------------------------------------------------------------- | | options | RedsysWebPaymentOptions |

Returns: Promise<RedsysPaymentResponseOK>

Since: 8.0.0

Example

const result = await Redsys.processWebPayment({
  signature: 'base64-encoded-signature',
});

computeHash(...)

computeHash(options: HashOptions) => Promise<HashResult>

| Param | Type | | ------------- | --------------------------------------------------- | | options | HashOptions |

Returns: Promise<HashResult>

Since: 8.0.0

Example

getPluginVersion()

getPluginVersion() => Promise<PluginVersionResult>

Returns the native plugin version.

The returned version corresponds to the native implementation bundled with the application.

Returns: Promise<PluginVersionResult>

Since: 8.0.0

Example

const { version } = await Redsys.getPluginVersion();

Interfaces

RedsysPaymentResponseOK

Standardized success response object for Redsys operations. This interface merges data from Android's ResultResponse and iOS's WebViewPaymentResponseOK.

| Prop | Type | Description | | ------------------------ | ----------------------------------------- | ------------------------------------ | | code | number | Internal SDK result code | | desc | string | Human-readable description | | amount | string | Transaction amount | | currency | string | Currency code (ISO-4217) | | order | string | Order identifier | | merchantCode | string | Merchant FUC code | | terminal | string | Terminal identifier | | responseCode | string | TPV response code | | authorisationCode | string | Authorization code | | transactionType | string | Transaction type | | securePayment | string | Indicates secure payment (1/0) | | signature | string | Digital signature | | cardNumber | string | Masked card number | | cardBrand | string | Card brand (e.g. VISA) | | cardCountry | string | Card issuing country | | cardType | string | Card type (D/C) | | expiryDate | string | Expiry date (MMYY) | | merchantIdentifier | string | Recurring / reference identifier | | consumerLanguage | string | Consumer language code | | date | string | Operation date (WebView only) | | hour | string | Operation hour (WebView only) | | merchantData | string | Merchant-specific data | | extraParams | Record<string, string> | Extra parameters returned by backend |

RedsysPaymentRequest

| Prop | Type | Description | | --------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | order | string | Unique merchant order identifier. | | amount | number | Amount in the smallest currency unit. | | description | string | Optional product description for display in the payment UI. | | transactionType | RedsysTransactionType | ISO-4217 currency code (e.g., "978" for EUR). | | identifier | string | Token handling: undefined (normal), 'REQUEST_REFERENCE' (new token), or existing token string. | | extraParams | Record<string, string> | Optional additional parameters to be sent to the backend and returned in the response. | | uiOptions | RedsysUIOptions | Runtime UI overrides for this specific transaction. |

RedsysUIOptions

Abstract, platform-agnostic UI customization options for Redsys payment screens. Some properties may only be supported on specific platforms due to SDK limitations.

| Prop | Type | Description | | ------------------------------------ | ------------------- | ------------------------------------------------------------------------------------------- | | logo | string | Top logo image reference. (Supported: Android & iOS) | | backgroundColor | string | Payment screen background color (Hex string). (Supported: Android & iOS) | | iosBackgroundImage | string | Payment screen background image. (Supported: iOS Only) | | androidProgressBarColor | string | Color of the progress bar during network operations. (Supported: Android Only) | | androidTopBarColor | string | Background color of the top action bar. (Supported: Android Only) | | confirmButtonText | string | Text for the main action/payment button. (Supported: Android & iOS) | | androidConfirmButtonColor | string | Background color of the main action button. (Supported: Android Only) | | androidConfirmButtonTextColor | string | Text color of the main action button. (Supported: Android Only) | | iosCancelButtonText | string | Text for the cancel/back button. (Supported: iOS Only) | | cardNumberLabel | string | Label text for the card number field. (Supported: Android & iOS) | | expirationLabel | string | Label text for the expiration date field. (Supported: Android & iOS) | | cvvLabel | string | Label text for the CVV/security code field. (Supported: Android & iOS) | | infoLabel | string | Descriptive text or payment instructions displayed on screen. (Supported: Android & iOS) | | labelTextColor | string | Text color for general labels (Card Number, Expiry, CVV). (Supported: Android & iOS) | | androidExpirationErrorText | string | Error message text displayed when the expiration date is invalid. (Supported: Android Only) | | androidCvvErrorText | string | Error message text displayed when the CVV is invalid. (Supported: Android Only) | | cardHeaderBackgroundColor | string | Background color of the card header area. (Supported: Android Only) | | androidCardHeaderText | string | Text for the card header. (Supported: Android Only) | | androidCardHeaderTextColor | string | Text color for the card header. (Supported: Android Only) | | androidResultAlertTextOk | string | Custom text for the success alert message. (Supported: Android Only) | | androidResultAlertTextKo | string | Custom text for the error alert message. (Supported: Android Only) | | androidResultAlertButtonTextOk | string | Custom text for the success alert button. (Supported: Android Only) | | androidResultAlertButtonTextKo | string | Custom text for the error alert button. (Supported: Android Only) |

RedsysWebPaymentInitResult

| Prop | Type | Description | | ---------------- | ------------------- | --------------------------------------------------------------- | | base64Data | string | Base64 data from native SDK that must be signed by the backend. | | signature | string | The signature if pre-calculated or available from config. |

RedsysWebPaymentOptions

| Prop | Type | Description | | ---------------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | signature | string | Server-generated signature. If omitted, the plugin will attempt to use the 'signature' defined in RedsysConfig. | | signatureVersion | 'HMAC_SHA256_V1' | 'HMAC_SHA512_V1' | Defaults to HMAC_SHA256_V1 if omitted. |

HashResult

| Prop | Type | Description | | --------------- | ------------------- | ------------------------ | | signature | string | Firma generata in Base64 |

HashOptions

| Prop | Type | Description | | --------------- | ------------------------------------------------- | -------------------------------------------------------------------------------- | | data | string | Dati da firmare (solitamente la stringa Base64 ricevuta da initializeWebPayment) | | keyBase64 | string | Chiave segreta in formato Base64 | | algorithm | 'HMAC_SHA256_V1' | 'HMAC_SHA512_V1' | Algorithm: 'HMAC_SHA256_V1' | 'HMAC_SHA512_V1' |

PluginVersionResult

Result object returned by the getPluginVersion() method.

| Prop | Type | Description | | ------------- | ------------------- | --------------------------------- | | version | string | The native plugin version string. |

Enums

RedsysTransactionType

| Members | Value | Description | | ---------------------- | ---------------------------------------- | ----------------------------------- | | Normal | 'normal' | Normal payment (Standard) | | Preauthorization | 'preauthorization' | Pre-authorization for later capture | | Traditional | 'traditional' | Traditional transaction flow | | Authentication | 'paymentTypeAuthentication' | Authentication-only flow |

Error Handling

The plugin uses standardized error codes across platforms:

| Code | Description | | ------------------- | ----------------------------------- | | UNAVAILABLE | Native SDK unavailable | | PERMISSION_DENIED | Required permission missing | | INIT_FAILED | SDK initialization failure | | UNKNOWN_TYPE | Invalid transaction type | | CRYPTO_ERROR | Signature computation failure | | SDK_ERROR | Native Redsys SDK returned an error |

SDK errors include additional metadata when available.

Response Structure

All successful payment responses return a normalized structure:

{
  code: number,
  amount: string,
  currency: string,
  order: string,
  merchantCode: string,
  terminal: string,
  responseCode: string,
  authorisationCode: string,
  transactionType: string,
  securePayment: string,
  signature: string,
  cardNumber: string,
  cardBrand: string,
  cardCountry: string,
  cardType: string,
  expiryDate: string,
  merchantIdentifier: string,
  consumerLanguage: string,
  date: string,
  hour: string,
  merchantData: string
}

Card numbers are automatically masked before being returned to JavaScript.

Security Notes

• The plugin never exposes full card numbers.
• HMAC signature computation is performed natively.
• Sensitive configuration should never be hardcoded in production builds.
• Always validate server-side responses before fulfilling orders.

Platform Requirements

• Capacitor v8
• iOS: Xcode 26 (Swift Package Manager)
• Android: Manual integration of Redsys InApp SDK 2.4.5 via local Maven repository (persistent)

Contributing

Contributions are welcome! Please read the contributing guide before submitting a pull request.

Legal Notice

The Redsys SDK is developed and owned by Redsys Servicios de Procesamiento S.L.

This plugin does not modify the original SDK and only provides integration and distribution mechanisms.

Official Documentation

For technical details on the underlying native SDKs, refer to the official guides:

• 🤖 In-App Integration for Android devices
• 🍎 In-App Integration for iOS devices

Official portal: https://pagosonline.redsys.es/

License

MIT