python-redsys 2.0.0__py3-none-any.whl → 2.2.0__py3-none-any.whl

redsys/clients.py

@@ -1,24 +1,25 @@
-"""Client entry points for the RedSys platform.
+"""Clients for the RedSys redirect and direct connections.
 
-The client is the single entry point: it holds the credentials and account
-identity (secret key, merchant code, terminal, signature version) and acts as
-the factory for every operation. You never build or import a request model --
-call an operation method (``payment``, ``refund``, ...) or the low-level
-``request()`` they all delegate to, and you get back a ``Request``:
+A client holds the credentials and the account (secret key, merchant code, terminal,
+environment, signature version) and builds every operation as a signed ``Request``:
 
-    client = DirectClient(secret_key='...', merchant_code='...', terminal=1, sandbox=True)
-    response = client.payment(order='000000001', amount=Decimal('10.56'), currency=978).send()
+    client = DirectClient(secret_key='...', merchant_code='999008881', terminal=1, sandbox=True)
+    response = client.payment(order=generate_order(), amount=Decimal('10.56')).send()
 
-Redirect requests end in ``.to_dict()`` (the browser submits them); direct
-requests end in ``.send()`` (the library performs the REST call). Both verify
-and parse incoming results through ``client.parse_response(payload)``.
+A redirect request ends in ``to_dict()``, the form the browser posts; a direct request
+ends in ``send()``. ``parse_response()`` verifies and parses a received result.
 """
 
+from base64 import b64decode
 from hmac import compare_digest
+from importlib.metadata import PackageNotFoundError, version
 from logging import getLogger
-from re import sub
+from re import fullmatch, sub
+from urllib.parse import urlsplit
+from warnings import warn
 
-from redsys.api import transactions
+from redsys import threeds
+from redsys.api import environments, transactions
 from redsys.crypto import (
     DEFAULT_SIGNATURE_VERSION,
     HMAC_SHA256_V1,
@@ -27,8 +28,9 @@ from redsys.crypto import (
     SIGNATURE_VERSIONS,
     get_signer,
 )
-from redsys.exceptions import ResponseError
+from redsys.exceptions import ResponseError, ValidationError
 from redsys.models import (
+    BaseRequest,
     CancellationMessage,
     ConfirmationMessage,
     DirectPaymentMessage,
@@ -47,7 +49,18 @@ from redsys.request import (
 
 logger = getLogger(__name__)
 
-# Default HTTP timeout (seconds) for direct-connection network calls; override per call.
+
+def _default_module() -> str:
+    try:
+        return f'python-redsys/{version("python-redsys")}'
+    except PackageNotFoundError:
+        return 'python-redsys'
+
+
+#: Ds_Merchant_Module sent by default: this library and its installed version.
+DEFAULT_MODULE = _default_module()
+
+# Seconds; ``send(timeout=...)`` overrides it.
 DEFAULT_TIMEOUT = 30
 
 __all__ = [
@@ -64,6 +77,7 @@ __all__ = [
     'HMAC_SHA512_V2',
     'SIGNATURE_VERSIONS',
     'DEFAULT_SIGNATURE_VERSION',
+    'DEFAULT_MODULE',
 ]
 
 
@@ -79,15 +93,61 @@ def _normalize_signature(signature) -> str:
     return sub(r'[^a-zA-Z0-9]', '', signature)
 
 
+def _resolve_environment(environment: str | None, sandbox: bool | None) -> str:
+    """The environment a client targets; ``sandbox`` means TEST when true and PROD when false."""
+    implied = None if sandbox is None else environments.TEST if sandbox else environments.PROD
+    if environment is None:
+        return implied or environments.PROD
+    if environment not in environments.HOSTS:
+        raise ValidationError('environment is not valid.')
+    if implied not in (None, environment):
+        raise ValidationError('environment contradicts sandbox.')
+    return environment
+
+
+def _endpoint_option(fields: dict) -> str | None:
+    """Pop a call's ``endpoint``, which is never signed; it must be an HTTPS URL."""
+    endpoint = fields.pop('endpoint', None)
+    if endpoint is None:
+        return None
+    parts = urlsplit(endpoint) if isinstance(endpoint, str) else None
+    if parts is None or parts.scheme != 'https' or not parts.netloc:
+        raise ValidationError('endpoint must be an https:// URL.')
+    return endpoint
+
+
+def _parse_api_key(api_key: str) -> tuple[str, str, int, str]:
+    """Split an API key into (environment, merchant code, terminal, secret key).
+
+    The format is ``<environment>_<Base64URL of merchant_terminal_secret>``, with
+    or without padding. Failures raise outside any ``except`` block and name no
+    detail, so neither the key nor its decoded secret reaches the traceback.
+    """
+    environment, _, payload = api_key.partition('_') if isinstance(api_key, str) else ('', '', '')
+    payload = payload.rstrip('=')
+    try:
+        decoded = b64decode(payload + '=' * (-len(payload) % 4), b'-_', validate=True).decode('utf-8')
+    except ValueError:
+        decoded = ''
+    fields = fullmatch(r'([0-9]{1,9})_([0-9]{1,3})_(.+)', decoded)
+    if environment not in environments.HOSTS or fields is None:
+        raise ValidationError('API key is not valid.')
+    merchant_code, terminal, secret_key = fields.groups()
+    return environment, merchant_code, int(terminal), secret_key
+
+
 class Client:
     """Base client: credentials, account identity, request factory, response parsing."""
 
     REAL_ENDPOINT: str | None = None
     TEST_ENDPOINT: str | None = None
+    _PATH: str | None = None
 
-    #: transaction_type -> request model. Unmapped types fall back to _DEFAULT_MODEL.
+    #: Request model per transaction type; other types use ``_DEFAULT_MODEL``.
     _DEFAULT_MODEL: type | None = None
     _MODELS: dict[int, type] = {}
+    #: The transaction types the connection accepts; ``None`` leaves the check to the model.
+    _TRANSACTION_TYPES: tuple[int, ...] | None = None
 
     def __init__(
         self,
@@ -95,25 +155,52 @@ class Client:
         *,
         merchant_code: str | None = None,
         terminal: int | None = None,
-        sandbox: bool = False,
+        currency: int | None = None,
+        sandbox: bool | None = None,
+        environment: str | None = None,
         signature_version: str = DEFAULT_SIGNATURE_VERSION,
+        module: str | None = DEFAULT_MODULE,
     ):
         self._secret_key = secret_key
+        self.module = module
         self.merchant_code = merchant_code
         self.terminal = terminal
-        self.sandbox = sandbox
+        self.currency = currency
+        self.environment = _resolve_environment(environment, sandbox)
+        self.sandbox = self.environment != environments.PROD
         self.signature_version = signature_version
-        self.endpoint = self.TEST_ENDPOINT if sandbox else self.REAL_ENDPOINT
+        self.endpoint = self.url(self._PATH) if self._PATH else None
+
+    @classmethod
+    def from_api_key(cls, api_key: str, **options):
+        """Build a client from a RedSys API key, which carries the environment and the credentials.
 
-    # -- request building -------------------------------------------------
+        ``options`` are the remaining constructor options (``signature_version``, ``currency``, ``module``).
+        Raises ``ValidationError`` if the key is not valid.
+        """
+        environment, merchant_code, terminal, secret_key = _parse_api_key(api_key)
+        return cls(secret_key, merchant_code=merchant_code, terminal=terminal, environment=environment, **options)
+
+    def __repr__(self) -> str:
+        return (
+            f'{type(self).__name__}(merchant_code={self.merchant_code!r}, terminal={self.terminal!r}, '
+            f'environment={self.environment!r}, signature_version={self.signature_version!r})'
+        )
+
+    def url(self, path: str) -> str:
+        """The client's environment host followed by ``path``, e.g. ``environments.RTP_TRATA_PATH``."""
+        if not isinstance(path, str) or not path.startswith('/'):
+            raise ValidationError('path must start with "/".')
+        return f'{environments.HOSTS[self.environment]}{path}'
+
+    # == Request building ==
     def _inject(self, fields: dict) -> dict:
-        """Merge the client's account identity into a call's fields (call wins)."""
-        data: dict = {}
-        if self.merchant_code is not None:
-            data['merchant_code'] = self.merchant_code
-        if self.terminal is not None:
-            data['terminal'] = self.terminal
-        data.update(fields)
+        """Merge the client's account defaults into a call's fields (call wins, by either name)."""
+        data = dict(fields)
+        for name in ('merchant_code', 'terminal', 'currency', 'module'):
+            value = getattr(self, name)
+            if value is not None and name not in data and BaseRequest.model_fields[name].alias not in data:
+                data[name] = value
         return data
 
     def _model_for(self, transaction_type: int) -> type:
@@ -125,25 +212,41 @@ class Client:
     def request(self, transaction_type: int, **fields) -> Request:
         """Build, validate and sign any operation by its transaction type.
 
-        The single funnel every named operation delegates to. Use it directly
-        for transaction types without a dedicated method (e.g. ``PAY_GOLD``).
+        For the types without a method, such as ``transactions.REFUND_CANCELLATION``.
+        Raises ``ValidationError`` if ``fields`` name a different transaction type, or if
+        the connection does not accept it (the redirect connection takes
+        ``transactions.REDIRECT_TRANSACTION_TYPES``). Every operation takes ``endpoint=``,
+        an HTTPS URL that replaces the client's for that request only; it is not signed.
         """
+        return self._operation(transaction_type, fields)
+
+    def _operation(self, transaction_type: int, fields: dict, endpoint: str | None = None) -> Request:
+        fields = dict(fields)
+        override = _endpoint_option(fields)
+        return self._prepare(self._message(transaction_type, fields), endpoint=override or endpoint)
+
+    def _message(self, transaction_type: int, fields: dict):
+        if self._TRANSACTION_TYPES is not None and transaction_type not in self._TRANSACTION_TYPES:
+            raise ValidationError(f'transaction type {transaction_type} is not accepted by {type(self).__name__}.')
         data = self._inject(fields)
-        data.setdefault('transaction_type', transaction_type)
-        model = self._model_for(transaction_type)(**data)
-        return self._prepare(model)
+        for name in ('transaction_type', BaseRequest.model_fields['transaction_type'].alias):
+            if str(data.pop(name, transaction_type)) != str(transaction_type):
+                raise ValidationError(f'{name} contradicts the operation, transaction type {transaction_type}.')
+        return self._model_for(transaction_type)(**data, transaction_type=transaction_type)
 
-    def _prepare(self, model) -> Request:
-        return self._build_request(model)
+    def _prepare(self, model, endpoint: str | None = None) -> Request:
+        return self._build_request(model, endpoint=endpoint or self.endpoint)
 
-    def _build_request(self, model, signature_version: str | None = None, sender=None) -> Request:
+    def _build_request(
+        self, model, signature_version: str | None = None, sender=None, endpoint: str | None = None
+    ) -> Request:
         version = signature_version or self.signature_version
         signer = get_signer(self._secret_key, version)
         merchant_parameters = signer.encode_parameters(model.prepare_parameters())
         signature = signer.sign(model.get_order(), merchant_parameters)
-        return Request(merchant_parameters, signature, version, sender=sender)
+        return Request(merchant_parameters, signature, version, sender=sender, endpoint=endpoint)
 
-    # -- response ---------------------------------------------------------
+    # == Response parsing ==
     def parse_response(self, payload: dict) -> Response:
         """Verify the signature and parse a received payload into a ``Response``.
 
@@ -160,30 +263,37 @@ class Client:
             merchant_parameters = merchant_parameters.encode('utf-8')
         version = payload.get(SIGNATURE_VERSION, DEFAULT_SIGNATURE_VERSION)
         response = Response.from_merchant_parameters(merchant_parameters)
-        # A signed result always carries Ds_Order; '' can never match, so a
-        # missing order simply fails verification below.
+        # A signed result always carries Ds_Order; without it, '' makes verification fail.
         expected = get_signer(self._secret_key, version).sign(response.get_order() or '', merchant_parameters)
-        # Constant-time comparison to avoid leaking the signature via timing.
         if not compare_digest(_normalize_signature(payload[SIGNATURE]), _normalize_signature(expected)):
             raise ValueError('Signature is not valid.')
         return response
 
 
 class RedirectClient(Client):
-    """Redirect connection (secure method): builds the signed POST parameters the
-    browser submits to RedSys. The library performs no HTTP and no redirect."""
+    """Redirect connection: builds the signed form fields the browser posts to RedSys; performs no HTTP."""
 
     # Endpoints per the redirection guide 4.2 (RS.TE.CEL.MAN.0039).
-    REAL_ENDPOINT = 'https://sis.redsys.es/sis/realizarPago'
-    TEST_ENDPOINT = 'https://sis-t.redsys.es:25443/sis/realizarPago'
+    _PATH = environments.REDIRECT_PATH
+    REAL_ENDPOINT = environments.HOSTS[environments.PROD] + _PATH
+    TEST_ENDPOINT = environments.HOSTS[environments.TEST] + _PATH
     _DEFAULT_MODEL = RedirectPaymentMessage
     _MODELS = {transactions.PREAUTHORIZATION: RedirectPreauthorizationMessage}
+    _TRANSACTION_TYPES = transactions.REDIRECT_TRANSACTION_TYPES
 
     def payment(self, **fields) -> Request:
-        return self.request(transactions.AUTHORIZATION, **fields)
+        return self._operation(transactions.AUTHORIZATION, fields)
 
     def preauthorization(self, **fields) -> Request:
-        return self.request(transactions.PREAUTHORIZATION, **fields)
+        return self._operation(transactions.PREAUTHORIZATION, fields)
+
+    def authentication(self, **fields) -> Request:
+        """Authenticate the cardholder and validate the card, with no hold (transaction type 7)."""
+        return self._operation(transactions.AUTHENTICATION, fields)
+
+    def refund_without_original(self, **fields) -> Request:
+        """Credit the cardholder with no previous sale (transaction type 34)."""
+        return self._operation(transactions.REFUND_WITHOUT_ORIGINAL, fields)
 
 
 def _require_httpx():
@@ -194,79 +304,154 @@ def _require_httpx():
     return httpx
 
 
+_EMV3DS_WIRE_NAME = 'Ds_Merchant_EMV3DS'
+
+
 class _DirectBase(Client):
-    """Shared REST direct-connection logic (transport-agnostic)."""
+    """Operations of the REST direct connection, independent of the HTTP transport."""
 
     # Endpoints per the REST guide 4.0.1 (RS.TE.CEL.MAN.0037).
-    REAL_ENDPOINT = 'https://sis.redsys.es/sis/rest/trataPeticionREST'
-    TEST_ENDPOINT = 'https://sis-t.redsys.es:25443/sis/rest/trataPeticionREST'
-    INICIA_REAL_ENDPOINT = 'https://sis.redsys.es/sis/rest/iniciaPeticionREST'
-    INICIA_TEST_ENDPOINT = 'https://sis-t.redsys.es:25443/sis/rest/iniciaPeticionREST'
+    _PATH = environments.TRATA_PATH
+    REAL_ENDPOINT = environments.HOSTS[environments.PROD] + _PATH
+    TEST_ENDPOINT = environments.HOSTS[environments.TEST] + _PATH
+    INICIA_REAL_ENDPOINT = environments.HOSTS[environments.PROD] + environments.INICIA_PATH
+    INICIA_TEST_ENDPOINT = environments.HOSTS[environments.TEST] + environments.INICIA_PATH
 
     _DEFAULT_MODEL = DirectPaymentMessage
     _MODELS = {
         transactions.PREAUTHORIZATION: DirectPreauthorizationMessage,
         transactions.CONFIRMATION: ConfirmationMessage,
         transactions.REFUND: RefundMessage,
-        transactions.CANCELLATION: CancellationMessage,
+        transactions.VOID: CancellationMessage,
+        transactions.REPLACEMENT_PREAUTHORIZATION: DirectPreauthorizationMessage,
+        transactions.PARTIAL_CONFIRMATION: ConfirmationMessage,
+        transactions.PAYMENT_CANCELLATION: CancellationMessage,
+        transactions.REFUND_CANCELLATION: CancellationMessage,
+        transactions.AUTHENTICATION_CONFIRMATION_CANCELLATION: CancellationMessage,
     }
 
     @property
     def inicia_endpoint(self) -> str:
-        return self.INICIA_TEST_ENDPOINT if self.sandbox else self.INICIA_REAL_ENDPOINT
+        return self.url(environments.INICIA_PATH)
 
     def payment(self, **fields) -> Request:
-        return self.request(transactions.AUTHORIZATION, **fields)
+        return self._operation(transactions.AUTHORIZATION, fields)
 
     def preauthorization(self, **fields) -> Request:
-        return self.request(transactions.PREAUTHORIZATION, **fields)
+        return self._operation(transactions.PREAUTHORIZATION, fields)
 
     def confirmation(self, **fields) -> Request:
-        return self.request(transactions.CONFIRMATION, **fields)
+        return self._operation(transactions.CONFIRMATION, fields)
+
+    def partial_confirmation(self, **fields) -> Request:
+        return self._operation(transactions.PARTIAL_CONFIRMATION, fields)
+
+    def authentication(self, **fields) -> Request:
+        return self._operation(transactions.AUTHENTICATION, fields)
+
+    def authentication_confirmation(self, **fields) -> Request:
+        return self._operation(transactions.AUTHENTICATION_CONFIRMATION, fields)
+
+    def authentication_confirmation_cancellation(self, **fields) -> Request:
+        return self._operation(transactions.AUTHENTICATION_CONFIRMATION_CANCELLATION, fields)
+
+    def pay_gold(self, **fields) -> Request:
+        return self._operation(transactions.PAY_GOLD, fields)
+
+    def pay_gold_expiry_change(self, **fields) -> Request:
+        """Change the expiry of a PayGold link (transaction type 51); RedSys requires ``amount``."""
+        return self._operation(transactions.PAY_GOLD_EXPIRY_CHANGE, fields)
+
+    def refund_without_original(self, **fields) -> Request:
+        """Credit the cardholder with no previous sale (transaction type 34)."""
+        return self._operation(transactions.REFUND_WITHOUT_ORIGINAL, fields)
 
     def refund(self, **fields) -> Request:
-        return self.request(transactions.REFUND, **fields)
+        return self._operation(transactions.REFUND, fields)
+
+    def void(self, **fields) -> Request:
+        """Void a preauthorization (transaction type 9)."""
+        return self._operation(transactions.VOID, fields)
+
+    def payment_cancellation(self, **fields) -> Request:
+        """Cancel a payment after a merchant time-out or technical error (transaction type 45)."""
+        return self._operation(transactions.PAYMENT_CANCELLATION, fields)
 
     def cancellation(self, **fields) -> Request:
-        return self.request(transactions.CANCELLATION, **fields)
+        """Deprecated: sends type 9; use ``void()``, or ``payment_cancellation()`` for type 45."""
+        warn(
+            'cancellation() is deprecated and goes away in 3.0: use void() for type 9, the type it sends, '
+            'or payment_cancellation() for type 45.',
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.void(**fields)
 
     def inicia(self, **fields) -> Request:
-        """3-D Secure step 1: build a request bound to the iniciaPeticionREST endpoint."""
+        """3-D Secure initialization (iniciaPeticionREST) from the given fields, ``emv3ds`` included."""
+        fields = dict(fields)
+        endpoint = _endpoint_option(fields)
         model = self._DEFAULT_MODEL(**self._inject(fields))
-        return self._prepare(model, endpoint=self.inicia_endpoint)
+        return self._prepare(model, endpoint=endpoint or self.inicia_endpoint)
+
+    def inicia_payment(self, **fields) -> Request:
+        """3-D Secure step 1 for a payment; ``emv3ds`` defaults to ``threeds.card_data()``."""
+        return self._inicia(transactions.AUTHORIZATION, fields)
+
+    def inicia_preauthorization(self, **fields) -> Request:
+        """3-D Secure step 1 for a preauthorization; ``emv3ds`` defaults to ``threeds.card_data()``."""
+        return self._inicia(transactions.PREAUTHORIZATION, fields)
+
+    def inicia_authentication(self, **fields) -> Request:
+        """3-D Secure step 1 for an authentication; ``emv3ds`` defaults to ``threeds.card_data()``."""
+        return self._inicia(transactions.AUTHENTICATION, fields)
+
+    def _inicia(self, transaction_type: int, fields: dict) -> Request:
+        if 'emv3ds' not in fields and _EMV3DS_WIRE_NAME not in fields:
+            fields['emv3ds'] = threeds.card_data()
+        return self._operation(transaction_type, fields, endpoint=self.inicia_endpoint)
+
+    def challenge_response(
+        self, *, cres: str, protocol_version: str, transaction_type: int = transactions.AUTHORIZATION, **fields
+    ) -> Request:
+        """3-D Secure final step after the challenge; ``transaction_type`` is the one authenticated."""
+        if 'emv3ds' in fields or _EMV3DS_WIRE_NAME in fields:
+            raise ValidationError('challenge_response() builds emv3ds from cres and protocol_version.')
+        emv3ds = threeds.challenge_response(cres=cres, protocol_version=protocol_version)
+        return self._operation(transaction_type, {**fields, 'emv3ds': emv3ds})
 
     def _prepare(self, model, endpoint: str | None = None) -> Request:
-        endpoint = endpoint or self.endpoint
-        return self._build_request(model, sender=self._make_sender(endpoint))
+        return self._build_request(model, sender=self._send, endpoint=endpoint or self.endpoint)
 
-    def _make_sender(self, endpoint):
+    def _send(self, request, **httpx_kwargs):
         raise NotImplementedError
 
+    def _parse_http_response(self, http_response) -> Response:
+        http_response.raise_for_status()
+        transport = (http_response.status_code, dict(http_response.headers), http_response.text)
+        try:
+            response = self.parse_response(http_response.json())
+        except ResponseError as error:
+            error.http_status, error.http_headers, error.raw_body = transport
+            raise
+        return response._with_transport(*transport)
 
-class DirectClient(_DirectBase):
-    """Synchronous REST direct-connection client. Requires the httpx extra."""
 
-    def _make_sender(self, endpoint):
-        def sender(request, **httpx_kwargs):
-            httpx = _require_httpx()
-            httpx_kwargs.setdefault('timeout', DEFAULT_TIMEOUT)
-            http_response = httpx.post(endpoint, json=request.to_dict(), **httpx_kwargs)
-            http_response.raise_for_status()
-            return self.parse_response(http_response.json())
+class DirectClient(_DirectBase):
+    """Synchronous REST direct-connection client; ``send()`` requires the ``http`` extra (httpx)."""
 
-        return sender
+    def _send(self, request, **httpx_kwargs):
+        httpx = _require_httpx()
+        httpx_kwargs.setdefault('timeout', DEFAULT_TIMEOUT)
+        return self._parse_http_response(httpx.post(request.endpoint, json=request.to_dict(), **httpx_kwargs))
 
 
 class AsyncDirectClient(_DirectBase):
-    """Asynchronous REST direct-connection client (httpx.AsyncClient). Requires the httpx extra."""
-
-    def _make_sender(self, endpoint):
-        async def sender(request, **httpx_kwargs):
-            httpx = _require_httpx()
-            httpx_kwargs.setdefault('timeout', DEFAULT_TIMEOUT)
-            async with httpx.AsyncClient() as client:
-                http_response = await client.post(endpoint, json=request.to_dict(), **httpx_kwargs)
-            http_response.raise_for_status()
-            return self.parse_response(http_response.json())
-
-        return sender
+    """Asynchronous REST direct-connection client; ``await send()`` requires the ``http`` extra (httpx)."""
+
+    async def _send(self, request, **httpx_kwargs):
+        httpx = _require_httpx()
+        httpx_kwargs.setdefault('timeout', DEFAULT_TIMEOUT)
+        async with httpx.AsyncClient() as client:
+            http_response = await client.post(request.endpoint, json=request.to_dict(), **httpx_kwargs)
+        return self._parse_http_response(http_response)

redsys/codes.py

@@ -0,0 +1,76 @@
+"""Meanings of RedSys result and error codes, in Spanish, Catalan, Galician, Basque or English.
+
+from redsys.codes import describe
+
+describe('0195', 'en')    # Ds_Response
+describe('SIS0051')       # SIS error code
+describe('BIZ00009')      # Bizum Request-to-Pay code
+"""
+
+from re import fullmatch
+
+from redsys import _code_texts
+from redsys.api import languages, responses
+
+# Position of each language in the (Spanish, Catalan, Galician, Basque, English) texts; Valencian reads the Catalan.
+_TEXT_INDEX = {
+    'es': 0,
+    'ca': 1,
+    'va': 1,
+    'gl': 2,
+    'eu': 3,
+    'en': 4,
+    languages.SPANISH: 0,
+    languages.CATALAN: 1,
+    languages.VALENCIAN: 1,
+    languages.GALICIAN: 2,
+    languages.EUSKERA: 3,
+    languages.ENGLISH: 4,
+}
+
+
+def _language_index(language) -> int | None:
+    if isinstance(language, str):
+        language = int(language) if language.isdigit() else language.lower()
+    return _TEXT_INDEX.get(language)
+
+
+def _texts(code) -> tuple[str, ...] | None:
+    if isinstance(code, bool):
+        return None
+    if isinstance(code, int):
+        code = str(code)
+    if not isinstance(code, str):
+        return None
+    code = code.strip().upper()
+    if match := fullmatch(r'SIS([0-9]{4})', code):
+        return _code_texts.SIS.get(int(match.group(1)))
+    if match := fullmatch(r'BIZ([0-9]{5})', code):
+        return _code_texts.BIZ.get(int(match.group(1)))
+    if not fullmatch(r'[0-9]{1,4}', code):
+        return None
+    number = int(code)
+    if number <= responses.AUTHORIZED_LAST:
+        return _code_texts.AUTHORIZED
+    if number in _code_texts.DS_RESPONSE:
+        return _code_texts.DS_RESPONSE[number]
+    # Every SIS0nnn error has a numeric twin 9nnn that can arrive in Ds_Response.
+    return _code_texts.SIS.get(number - 9000) if number >= 9000 else None
+
+
+def describe(code, language='es') -> str:
+    """The meaning of a ``Ds_Response`` code, an ``SISnnnn`` error code or a Bizum ``BIZnnnnn`` code.
+
+    ``code`` is an ``int`` or a ``str`` (``0``, ``'0000'``, ``'SIS0051'``, ``'BIZ00009'``). ``language``
+    is an ISO code (``'es'``, ``'en'``, ``'ca'``, ``'gl'``, ``'eu'``; ``'va'`` reads the Catalan) or RedSys's numeric
+    one (``languages.SPANISH``, ``ENGLISH``, ``CATALAN``, ``VALENCIAN``, ``GALICIAN``, ``EUSKERA``).
+    Returns ``''`` for an unknown code or language.
+    """
+    texts = _texts(code)
+    index = _language_index(language)
+    if texts is None or index is None:
+        return ''
+    return texts[index]
+
+
+__all__ = ['describe']

redsys/crypto.py

@@ -14,13 +14,13 @@ HMAC_SHA512_V2 also sends Ds_MerchantParameters as unpadded Base64URL; the other
 versions send standard Base64. Responses are decoded tolerantly in either form.
 
 The SHA-512 versions key their HMAC with the Base64 text of the derived key and differ
-only in the padding of the signature (RedSys PHP library 2.0.1, Signature.php);
-HMAC_SHA256_V1 uses the raw derived bytes.
+only in the padding of the signature (verified against signed responses of the RedSys
+test environment); HMAC_SHA256_V1 uses the raw derived bytes.
 
 HMAC_SHA512_V1 is the REST guide 4.0.1 scheme; HMAC_SHA512_V2 (the default) is the one the
-redirection guide 4.1 and later and RedSys's own libraries use; HMAC_SHA256_V1 is
-still accepted (REST guide 4.0.1, Anexo 2). The cipher parameters are pinned by a
-known-answer test against RedSys's official worked example (see tests/test_crypto.py).
+redirection guide 4.1 and later uses; HMAC_SHA256_V1 is still accepted (REST guide 4.0.1,
+Anexo 2). The cipher parameters are pinned by a known-answer test against RedSys's official
+worked example (see tests/test_crypto.py).
 """
 
 from base64 import b64decode, b64encode, urlsafe_b64encode
@@ -84,7 +84,7 @@ class Sha512V1Signer(Signer):
 
     def sign(self, order: str, merchant_parameters: bytes) -> bytes:
         # The HMAC key is the Base64 text of the derived key, not its raw bytes
-        # (confirmed live against the RedSys test environment; raw bytes -> SIS0042).
+        # (confirmed against the RedSys test environment, where raw bytes give SIS0042).
         derived = b64encode(self._derive_key(order))
         # REST manual: Base64URL with the '=' padding kept.
         return urlsafe_b64encode(HMAC(derived, merchant_parameters, sha512).digest())
@@ -96,12 +96,12 @@ class Sha512V2Signer(Sha512V1Signer):
     def encode_parameters(self, parameters: dict) -> bytes:
         # V2 endpoints decode Ds_MerchantParameters as unpadded Base64URL: the 3DS
         # initialization rejects standard or padded Base64 with SIS0430 (verified
-        # live 2026-10-25), and the RedSys PHP library sends it this way.
+        # against the test environment).
         return urlsafe_b64encode(dumps(parameters, sort_keys=True).encode('utf-8')).rstrip(b'=')
 
     def sign(self, order: str, merchant_parameters: bytes) -> bytes:
         # Same derived key and HMAC as HMAC_SHA512_V1; only the '=' padding goes
-        # (RedSys PHP library 2.0.1, base64_url_encode_safe).
+        # (verified against the test environment).
         return super().sign(order, merchant_parameters).rstrip(b'=')
 
 

redsys/exceptions.py

@@ -8,11 +8,14 @@ class ResponseError(RedsysError):
     def __init__(self, error_code, payload=None):
         self.error_code = error_code
         self.payload = payload
+        self.http_status = None
+        self.http_headers = None
+        self.raw_body = None
         super().__init__(f'RedSys returned error: {error_code}')
 
 
-class ValidationError(RedsysError):
-    """A parameter failed validation."""
+class ValidationError(RedsysError, ValueError):
+    """A client option or an operation's fields contradict each other or what RedSys accepts."""
 
 
 class UnknownParameterWarning(UserWarning):