PHPackages                             sermepa/sermepa - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Payment Processing](/categories/payments)
4. /
5. sermepa/sermepa

ActiveLibrary[Payment Processing](/categories/payments)

sermepa/sermepa
===============

Pasarela de pago Redsys, Sermepa

1.5.3(2mo ago)207395.1k↓12%59[1 issues](https://github.com/ssheduardo/sermepa/issues)[1 PRs](https://github.com/ssheduardo/sermepa/pulls)6MITPHPPHP ^7.1.3|^7.2.5|^8.0|^8.1|^8.2|^8.3|^8.4|^8.5CI passing

Since Jun 23Pushed 2mo ago11 watchersCompare

[ Source](https://github.com/ssheduardo/sermepa)[ Packagist](https://packagist.org/packages/sermepa/sermepa)[ Docs](https://github.com/ssheduardo/sermepa)[ RSS](/packages/sermepa-sermepa/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (1)Versions (42)Used By (6)

Redsys - Biblioteca PHP para Pasarela de Pagos
==============================================

[](#redsys---biblioteca-php-para-pasarela-de-pagos)

[![Latest Version on Packagist](https://camo.githubusercontent.com/44a2bc52407d813f9ea8e19fb9c7ebd11fe46d1f9b4a5a6bf9e081e0403689a1/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7365726d6570612f7365726d6570612e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/sermepa/sermepa)[![Software License](https://camo.githubusercontent.com/55c0218c8f8009f06ad4ddae837ddd05301481fcf0dff8e0ed9dadda8780713e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](LICENSE.md)[![Total Downloads](https://camo.githubusercontent.com/3740784e7e2b3e2a0a20e91f5c15e58491ea4dc9e3c5bef6b1ff82fc68247d27/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7365726d6570612f7365726d6570612e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/sermepa/sermepa)[![Run Tests](https://github.com/ssheduardo/sermepa/actions/workflows/ci.yml/badge.svg)](https://github.com/ssheduardo/sermepa/actions/workflows/ci.yml)

Biblioteca PHP para integrar la pasarela de pagos Redsys/Sermepa (Santander, Sabadell, LaCaixa, BBVA, etc.)

Requisitos
----------

[](#requisitos)

- PHP 7.1.3+ a 8.2
- ext-curl
- ext-openssl
- ext-json

Instalación
-----------

[](#instalación)

```
composer require sermepa/sermepa
```

Inicio Rápido
-------------

[](#inicio-rápido)

```
use Sermepa\Tpv\Tpv;

$redsys = new Tpv();
$redsys->setAmount(2500)           // 25.00€
    ->setOrder('1234AB')
    ->setMerchantcode('999008881')
    ->setCurrency('978')           // Euros
    ->setTransactiontype('0')       // Autorización
    ->setTerminal('1')
    ->setMethod('C')                // Solo tarjeta
    ->setNotification('https://tusitio.com/notificacion')
    ->setUrlOk('https://tusitio.com/ok')
    ->setUrlKo('https://tusitio.com/ko')
    ->setEnvironment('test');       // Entorno de pruebas

$signature = $redsys->generateMerchantSignature('TU_CLAVE_SECRETA');
$redsys->setMerchantSignature($signature);

echo $redsys->createForm();
```

Entornos Disponibles
--------------------

[](#entornos-disponibles)

EntornoDescripción`test`Pruebas (SIS Sandbox)`live`Producción`restTest`API REST Pruebas`restLive`API REST Producción`insiteSandbox`InSite Pruebas (JS + REST)`insiteLive`InSite Producción (JS + REST)`insiteRestSandbox`InSite REST Pruebas (solo pago)`insiteRestLive`InSite REST Producción (solo pago)Métodos de Pago
---------------

[](#métodos-de-pago)

CódigoDescripción`C` o `T`Tarjeta`R`Transferencia`D`Domiciliación`z`Bizum`p`PayPal`N`Masterpass`xpay`GooglePay / ApplePayTipos de Transacción
--------------------

[](#tipos-de-transacción)

CódigoDescripción`0`Autorización`1`Preautorización`2`Confirmación de preautorización`3`Anulación de preautorización`4`Devolución`5`Cancelación`7`Preautorización extendida`8`Confirmación preautorización extendida`9`Baja de preautorización extendidaCódigos de Respuesta
--------------------

[](#códigos-de-respuesta)

El banco devuelve un código en `Ds_Response`. Los principales:

CódigoSignificado`0000` a `0099`Pago aprobado`0100` a `0199`Operatoria OK, verificación CVV obligatoria`0200`Error de formato`0201`Error de firma`0204`Error de datos`0209`Error de tajeta`0214`Fecha de caducidad errónea`0215`Error en importe mínimo (no usado)`0290`Tarjeta no autorizada`0401`Error en posición de tarjeta`0404`Error de configuración de comercio`0501`Operaciones pendientes`0904`Comercio no operativo`0912`Emisor no disponible`9912`Emisor no disponible`9913`Error en comunicación`9914`Fallo al conectar con CA`9919`Error de cryptograma`9929`Error de deslinde`9932`Error de bin`9933`Error de BS. Cambio de dinámico a estático`9934`Error de BS. Cambio de estático a dinámico`9951`Operación de ingreso OK`9952`Operación de ingreso NO OK`9953`Devolución OK`9954`Devolución NO OK`9955`Anulación OK`9956`Anulación NO OK`9957`Ajuste OK`9958`Ajuste NO OK`9961`Error en cierre batch`9962`Error en apertura batch`9963`Error de operativa`9992`Petición cancelada`9993`Operatoria abandonada por el usuario`9995`Operatoria abandonada - tiempo excedido`9996`Error de conexión`9997`Error de timeout`9998`Error de validación`9999`Error general> **Nota:** Para pagos exitosos, el código debe estar entre `0000` y `0099`. Convertir a entero para comparar: `$DsResponse = (int) $parameters['Ds_Response'];`

Validar Respuesta del Banco
---------------------------

[](#validar-respuesta-del-banco)

En tu URL de notificación (`setNotification`), debes validar la respuesta del banco:

```
use Sermepa\Tpv\Tpv;
use Sermepa\Tpv\TpvException;

try {
    $redsys = new Tpv();
    $key = 'TU_CLAVE_SECRETA';

    // Decodificar parámetros recibidos
    $parameters = $redsys->getMerchantParameters($_POST['Ds_MerchantParameters']);
    $DsResponse = (int) $parameters['Ds_Response'];

    // Validar firma y respuesta
    if ($redsys->check($key, $_POST) && $DsResponse getMessage());
}
```

Pago con Tarjeta Guardada (Token)
---------------------------------

[](#pago-con-tarjeta-guardada-token)

Guardar la tarjeta del cliente para pagos futuros:

```
// 1. Crear referencia (primer pago)
$redsys->setIdentifier();  // Sin parámetros - indica "REQUIRED"

// Respuesta del banco contendrá:
// $parameters['Ds_Merchant_Identifier']
// $parameters['Ds_ExpiryDate']
```

```
// 2. Usar referencia (pagos recurrentes)
$redsys->setIdentifier('IDENTIFICADOR_GUARDADO');
$redsys->setMerchantDirectPayment(true);  // Pago directo sin autenticación 3D Secure
```

Enviar Datos de Tarjeta Directamente
------------------------------------

[](#enviar-datos-de-tarjeta-directamente)

Puedes enviar los datos de la tarjeta para que el usuario no tenga que introducirlos en la pasarela:

```
$redsys->setPan('4548812049400004');     // Número de tarjeta
$redsys->setExpiryDate('1228');          // Caducidad (AAMM)
$redsys->setCVV2('123');                 // CVV2
```

> **Nota:** Esta opción requiere que tu comercio tenga autorización del banco para enviar datos de tarjeta directamente.

API REST (Cobros sin formulario)
--------------------------------

[](#api-rest-cobros-sin-formulario)

Para cobros directos sin redirección del usuario:

```
use Sermepa\Tpv\Tpv;
use Sermepa\Tpv\TpvException;

try {
    $key = 'TU_CLAVE_SECRETA';

    $redsys = new Tpv();
    $redsys->setAmount(2500)
        ->setOrder('1234AB')
        ->setMerchantcode('999008881')
        ->setCurrency('978')
        ->setTransactiontype('0')
        ->setTerminal('1')
        ->setIdentifier('IDENTIFICADOR_GUARDADO')
        ->setMerchantDirectPayment(true)
        ->setVersion('HMAC_SHA256_V1')
        ->setEnvironment('restTest')
        ->setMerchantCofIni('N');

    $signature = $redsys->generateMerchantSignature($key);
    $redsys->setMerchantSignature($signature);

    $response = json_decode($redsys->send(), true);

    // Verificar error en respuesta
    if (isset($response['errorCode'])) {
        throw new Exception("Error: " . $response['errorCode']);
    }

    // Decodificar respuesta
    $parameters = $redsys->getMerchantParameters($response['Ds_MerchantParameters']);
    $DsResponse = (int) $parameters['Ds_Response'];

    if ($redsys->check($key, $response) && $DsResponse getMessage();
}
```

InSite (Pago Embebido)
----------------------

[](#insite-pago-embebido)

InSite permite incrustar el formulario de pago directamente en tu página web mediante un **iframe**, sin redirigir al usuario a la pasarela de Redsys. Los datos de tarjeta nunca pasan por tu servidor (cumplimiento PCI DSS).

> **Nota:** Tu dominio debe estar registrado en Redsys para usar InSite. Configura los dominios permitidos en el Portal de Administración del TPV Virtual. Contacta con tu banco o soporte de Redsys.

### Flujo de Integración

[](#flujo-de-integración)

1. **Generar formulario InSite** - Renderiza el iframe en tu página
2. **Usuario completa pago** - Introduce datos en el iframe de Redsys
3. **Obtener ID de operación** - Redsys retorna un `idOper` (válido por 30 minutos)
4. **Ejecutar pago** - Envía el `idOper` mediante REST API

### Paso 1: Generar Formulario InSite (Modo Unificado)

[](#paso-1-generar-formulario-insite-modo-unificado)

El modo unificado genera un iframe completo con todos los campos de pago:

```
use Sermepa\Tpv\Tpv;
use Redsys\Merchant\MerchantInsiteLanguage;

$redsys = new Tpv();
$redsys->setEnvironment('insiteSandbox')  // o 'insiteLive' para producción
    ->setOrder('1234AB')
    ->setMerchantcode('999008881')        // Tu código de comercio (FUC)
    ->setTerminal('1');

// Generar HTML del formulario InSite
$htmlForm = $redsys->createInSiteForm(
    'card-form',              // ID del contenedor
    'background: #007bff;',   // Estilo del botón
    'color: white;',          // Estilo del cuerpo
    'padding: 10px;',         // Estilo de la caja de datos
    'font-size: 14px;',       // Estilo de los inputs
    'Pagar',                  // Texto del botón (HTML encoded: 'Botón' para Botón)
    MerchantInsiteLanguage::ISO_ES, // Idioma: 'ES', '1', etc.
    true,                     // Mostrar logo de entidad
    false,                    // Estilo reducido
    'inline'                  // Estilo InSite: 'inline' o 'twoRows'
);

echo $htmlForm;
```

### Modo JSON (Recomendado)

[](#modo-json-recomendado)

Para mayor flexibilidad, usa el método JSON:

```
$htmlForm = $redsys->createInSiteFormJSON([
    'id' => 'card-form',
    'fuc' => '999008881',
    'terminal' => '1',
    'order' => '1234AB',
    'styleButton' => 'background: #007bff; color: white;',
    'styleBody' => 'font-family: Arial;',
    'styleBox' => 'padding: 10px;',
    'buttonValue' => 'Pagar ahora',
    'idiomaInsite' => 'ES',
    'mostrarLogoInsite' => true,
    'estiloReducidoInsite' => false,
    'estiloInsite' => 'inline'  // o 'twoRows'
]);
```

### Parámetros del Formulario

[](#parámetros-del-formulario)

ParámetroObligatorioDescripción`id` / `$containerId`SíID del contenedor div`fuc` / merchantCodeSíCódigo de comercio (FUC)`terminal`SíNúmero de terminal`order`SíNúmero de pedido (4-12 caracteres)`styleButton`NoCSS para el botón de pago`styleBody`NoCSS para el cuerpo del formulario`styleBox`NoCSS para la caja de datos`styleBoxText`NoCSS para el texto de los inputs`buttonValue`NoTexto del botón (HTML encoded)`idiomaInsite`NoCódigo de idioma (ver tabla)`mostrarLogoInsite`NoMostrar logo de entidad (default: true)`estiloReducidoInsite`NoUsar estilo reducido (default: false)`estiloInsite`No'inline' o 'twoRows' (default: 'inline')### Catálogo de Idiomas InSite

[](#catálogo-de-idiomas-insite)

IdiomaCódigo SISISO 639-1Español1ESInglés2ENCatalán3CAFrancés4FRAlemán5DEItaliano7ITPortugués9PT.........Usa las constantes de `MerchantInsiteLanguage`:

```
use Redsys\Merchant\MerchantInsiteLanguage;

$redsys->createInSiteForm(..., MerchantInsiteLanguage::SPANISH, ...);
// o
$redsys->createInSiteForm(..., MerchantInsiteLanguage::ISO_ES, ...);
```

### Paso 2: Recibir ID de Operación

[](#paso-2-recibir-id-de-operación)

El formulario incluye automáticamente un listener que almacena el `idOper` en un campo hidden:

```

```

Puedes personalizar la validación:

```
function merchantValidation() {
    // Tu validación personalizada
    return true;  // true para continuar, false para cancelar
}

window.addEventListener("message", function receiveMessage(event) {
    storeIdOper(event, "token", "errorCode", merchantValidation);
});
```

### Códigos de Error InSite

[](#códigos-de-error-insite)

CódigoDescripciónmsg1Ha de rellenar los datos de la tarjetamsg2La tarjeta es obligatoriamsg3La tarjeta ha de ser numéricamsg15La longitud de la tarjeta no es correctamsg16Debe introducir un número de tarjeta válidomsg17Validación incorrecta por parte del comerciomsg18Error de inicialización de dominioUsa `MerchantInsiteError` para obtener descripciones:

```
use Redsys\Merchant\MerchantInsiteError;

$errorDescription = MerchantInsiteError::getDescription('msg1');
```

### Paso 3: Ejecutar Pago con ID de Operación

[](#paso-3-ejecutar-pago-con-id-de-operación)

```
use Sermepa\Tpv\Tpv;
use Sermepa\Tpv\TpvException;

try {
    $key = 'TU_CLAVE_SECRETA';
    $idOper = $_POST['token'];    // ID recibido del iframe
    $order = '1234AB';             // Mismo pedido usado en el formulario

    $redsys = new Tpv();
    $redsys->setEnvironment('insiteRestLive')  // o 'insiteRestSandbox'
        ->setAmount(2500)
        ->setOrder($order)          // DEBE ser el mismo que en createInSiteForm
        ->setMerchantcode('999008881')
        ->setCurrency('978')
        ->setTransactiontype('0')
        ->setTerminal('1');

    // Ejecutar pago con el ID de operación
    $response = json_decode($redsys->sendInSite($idOper, $key), true);

    // Decodificar respuesta
    $parameters = $redsys->getMerchantParameters($response['Ds_MerchantParameters']);
    $DsResponse = (int) $parameters['Ds_Response'];

    if ($DsResponse >= 0 && $DsResponse getMessage();
}
```

### Métodos InSite

[](#métodos-insite)

MétodoDescripción`setInSite(bool)`Habilitar/deshabilitar modo InSite`getInSiteMode()`Obtener estado del modo InSite`getInSiteJsUrl()`Obtener URL del JavaScript de InSite`createInSiteForm(string $containerId, string $buttonStyle, string $bodyStyle)`Generar HTML del formulario embebido`sendInSite(string $idOper, string $key)`Ejecutar pago con ID de operación### Personalización del Formulario

[](#personalización-del-formulario)

```
// Generar formulario con estilos personalizados
$html = $redsys->createInSiteForm(
    'card-form',                                    // ID del contenedor
    'background-color: #28a745; color: white; padding: 15px; border: none; border-radius: 5px;',  // Estilo botón
    'font-family: Arial, sans-serif;'               // Estilo cuerpo
);
```

Redirección Automática
----------------------

[](#redirección-automática)

Para redirección automática sin mostrar el botón:

```
$redsys->executeRedirection();
// Opcional: obtener HTML
$html = $redsys->executeRedirection(true);
```

Integración con JavaScript de Redsys
------------------------------------

[](#integración-con-javascript-de-redsys)

La biblioteca incluye un método estático para obtener la ruta del JavaScript de Redsys:

```
use Sermepa\Tpv\Tpv;

// Obtener URL del script
$jsUrl = Tpv::getJsPath('test', '3');  // Entorno test, versión 3
// https://sis-t.redsys.es:25443/sis/NC/sandbox/redsysV3.js
```

VersiónDescripción`2`Redsys Classic`3`Redsys API (soporte NFC, Apple Pay, Google Pay)Constantes Disponibles
----------------------

[](#constantes-disponibles)

Usa las constantes predefinidas para evitar errores de transcripción:

```
use Redsys\Merchant\MerchantCurrencies;
use Redsys\Merchant\MerchantTransactionTypes;
use Redsys\Merchant\MerchantConsumerLanguages;
use Redsys\Merchant\MerchantPaymethods;

// Monedas
$redsys->setCurrency(MerchantCurrencies::EUR);      // 978
$redsys->setCurrency(MerchantCurrencies::USD);      // 840
$redsys->setCurrency(MerchantCurrencies::GBP);     // 826

// Tipos de transacción
$redsys->setTransactiontype(MerchantTransactionTypes::AUTHORIZATION);  // 0
$redsys->setTransactiontype(MerchantTransactionTypes::PREAUTHORIZATION);  // 1

// Idiomas
$redsys->setLanguage(MerchantConsumerLanguages::SPANISH);   // 001
$redsys->setLanguage(MerchantConsumerLanguages::ENGLISH);   // 002
$redsys->setLanguage(MerchantConsumerLanguages::CATALAN);    // 003

// Métodos de pago
$redsys->setMethod(MerchantPaymethods::CARD);    // C
$redsys->setMethod(MerchantPaymethods::BIZUM);   // z
```

### Códigos de Moneda

[](#códigos-de-moneda)

Los códigos ISO 4217. Los más comunes:

- `978` - Euro (EUR)
- `840` - Dólar estadounidense (USD)
- `826` - Libra esterlina (GBP)
- `392` - Yen japonés (JPY)

### Códigos de Idioma

[](#códigos-de-idioma)

CódigoIdioma001Castellano002Inglés003Catalán004Francés005Alemán006Holandés007Italiano008Sueco009Portugués010Valenciano011Polaco012Gallego013EuskeraAPI Reference
-------------

[](#api-reference)

### Métodos de Configuración

[](#métodos-de-configuración)

MétodoDescripciónRequerido`setAmount(float)`Importe (se convierte a céntimos)Sí`setOrder(string)`Número de pedido (4-12 caracteres, primeros 4 numéricos)Sí`setMerchantcode(string)`Código de comercio (FUC)Sí`setCurrency(string)`Código de moneda ISOSí`setTransactiontype(string)`Tipo de transacciónSí`setTerminal(string)`Número de terminalSí`setMethod(string)`Método de pagoNo`setNotification(string)`URL de notificación (callback)Recomendado`setUrlOk(string)`URL si pago exitosoRecomendado`setUrlKo(string)`URL si pago fallidoRecomendado`setEnvironment(string)`Entorno de conexiónNo`setVersion(string)`Versión de firmaNo`setTradeName(string)`Nombre del comercioNo`setTitular(string)`Titular del pagoNo`setProductDescription(string)`Descripción del productoNo### Métodos de Firma y Envío

[](#métodos-de-firma-y-envío)

MétodoDescripción`generateMerchantSignature(string $key)`Genera firma HMAC-SHA256`setMerchantSignature(string)`Asigna la firma calculada`createForm()`Genera formulario HTML`send()`Envía petición REST (devuelve JSON)`executeRedirection()`Redirección automática con JavaScript### Métodos de Validación

[](#métodos-de-validación)

MétodoDescripción`check(string $key, array $postData)`Valida firma de respuesta del banco`getMerchantParameters(string)`Decodifica `Ds_MerchantParameters`### Métodos InSite

[](#métodos-insite-1)

MétodoDescripción`setInSite(bool)`Habilitar modo InSite`getInSiteMode()`Obtener estado del modo InSite`getInSiteJsUrl()`Obtener URL del JavaScript de InSite`createInSiteForm(...)`Genera formulario embebido (modo unificado)`createInSiteFormJSON(array)`Genera formulario embebido (modo JSON)`sendInSite(string $idOper, string $key)`Ejecuta pago con ID de operación#### Parámetros de createInSiteForm()

[](#parámetros-de-createinsiteform)

ParámetroTipoObligatorioDescripción`$containerId`stringNoID del contenedor div (default: 'card-form')`$buttonStyle`stringNoCSS para el botón de pago`$bodyStyle`stringNoCSS para el cuerpo del formulario`$boxStyle`stringNoCSS para la caja de datos`$inputStyle`stringNoCSS para los inputs`$buttonText`stringNoTexto del botón (HTML encoded)`$language`stringNoCódigo de idioma (default: 'ES')`$showLogo`boolNoMostrar logo de entidad (default: true)`$reducedStyle`boolNoUsar estilo reducido (default: false)`$insiteStyle`stringNo'inline' o 'twoRows' (default: 'inline')### Métodos Auxiliares

[](#métodos-auxiliares)

MétodoDescripción`setNameForm(string)`Nombre del formulario`setIdForm(string)`ID del formulario`setAttributesSubmit(...)`Personalizar botón submit`setLanguage(string)`Idioma de la pasarela`setParameters(array)`Parámetros adicionales`setIdentifier(string)`Referencia de tarjeta guardada`setMerchantDirectPayment(bool)`Pago directo sin autenticación`setPan(string)`Número de tarjeta`setExpiryDate(string)`Caducidad (AAMM)`setCVV2(string)`Código CVV2`setMerchantData(string)`Datos adicionales del comercio`getOrder()`Obtener número de pedido`getParameters()`Obtener todos los parámetros`getVersion()`Obtener versión de firma`getMerchantSignature()`Obtener firma actual`getEnvironment()`Obtener URL del entorno`getJsPath(string, string)`Obtener ruta JS para integración moderna`createOrderNumber(int)`Generar número de pedido válidoParámetros Avanzados
--------------------

[](#parámetros-avanzados)

### Pagos Recurrentes

[](#pagos-recurrentes)

```
$redsys->setMerchantCofIni('S');           // Inicio de COF
$redsys->setMerchantCofType('R');          // Tipo: R=Recurrente, I=Cuotas
$redsys->setMerchantCofTxnid('123456789'); // ID de transacción
$redsys->setSumtotal(50000);               // Importe total
$redsys->setChargeExpiryDate('2025-12-31'); // Fecha expiración
$redsys->setDateFrecuency(30);             // Frecuencia en días
```

### Excepción SCA (Strong Customer Authentication)

[](#excepción-sca-strong-customer-authentication)

Algunos bancos requieren parámetros adicionales:

```
$parameters = ['DS_MERCHANT_EXCEP_SCA' => 'MIT'];
$redsys->setParameters($parameters);
```

Ejemplos Completos
------------------

[](#ejemplos-completos)

### Ejemplo Completo: Pago Simple

[](#ejemplo-completo-pago-simple)

```