python-redsys 1.2.2__py3-none-any.whl → 2.1.0__py3-none-any.whl

redsys/api/sca.py

@@ -0,0 +1,23 @@
+"""PSD2 strong customer authentication (SCA) exemption codes for Ds_Merchant_Excep_SCA (REST guide 4.0.1)."""
+
+LWV = 'LWV'
+"""Low-value transaction: up to 30 EUR, with issuer-side counters (5 operations or 100 EUR accumulated)."""
+
+TRA = 'TRA'
+"""Transaction risk analysis performed by the acquirer or the merchant."""
+
+MIT = 'MIT'
+"""Merchant-initiated transaction, no cardholder interaction (stored credentials, subscriptions).
+
+Sent together with direct_payment "true"."""
+
+COR = 'COR'
+"""Secure corporate payment, business-to-business only."""
+
+ATD = 'ATD'
+"""Delegated authentication, a card-scheme program."""
+
+EXEMPTIONS = (LWV, TRA, MIT, COR, ATD)
+
+QUERY = 'Y'
+"""Sent on the 3DS initialization to ask which exemptions the card allows; the answer comes back in Ds_Excep_SCA."""

redsys/api/transactions.py

@@ -0,0 +1,74 @@
+AUTHORIZATION = 0
+"""Authorization."""
+
+PREAUTHORIZATION = 1
+"""Pre-authorization."""
+
+CONFIRMATION = 2
+"""Confirmation."""
+
+REFUND = 3
+"""Refund."""
+
+AUTHENTICATION = 7
+"""Authentication."""
+
+AUTHENTICATION_CONFIRMATION = 8
+"""Authentication confirmation"""
+
+CANCELLATION = 9
+"""Cancellation"""
+
+REPLACEMENT_PREAUTHORIZATION = 11
+"""Replacement preauthorization: extends an existing preauthorization."""
+
+PAY_GOLD = 15
+"""Pay gold"""
+
+AUTHENTICATION_PUCE = 17
+"""PUCE authentication"""
+
+REFUND_WITHOUT_ORIGINAL = 34
+"""Refund without original"""
+
+BETTING_PRICE = 37
+"""Betting price"""
+
+PAY_GOLD_AUTHORIZATION = 38
+"""PayGold authorization: the cardholder completes a PayGold request (type 15); sent by RedSys, not the merchant."""
+
+DELETE_REFERENCE = 44
+"""Delete a stored card reference (token)."""
+
+PAYMENT_CANCELLATION = 45
+"""Payment cancellation, for merchant time-outs or technical errors."""
+
+REFUND_CANCELLATION = 46
+"""Refund cancellation, within 48 hours of the refund."""
+
+AUTHENTICATION_CONFIRMATION_CANCELLATION = 47
+"""Cancellation of an authentication confirmation (type 8)."""
+
+PARTIAL_CONFIRMATION = 48
+"""Partial confirmation of a preauthorization."""
+
+TRANSACTION_TYPES = (
+    AUTHORIZATION,
+    PREAUTHORIZATION,
+    CONFIRMATION,
+    REFUND,
+    AUTHENTICATION,
+    AUTHENTICATION_CONFIRMATION,
+    CANCELLATION,
+    REPLACEMENT_PREAUTHORIZATION,
+    PAY_GOLD,
+    AUTHENTICATION_PUCE,
+    REFUND_WITHOUT_ORIGINAL,
+    BETTING_PRICE,
+    PAY_GOLD_AUTHORIZATION,
+    DELETE_REFERENCE,
+    PAYMENT_CANCELLATION,
+    REFUND_CANCELLATION,
+    AUTHENTICATION_CONFIRMATION_CANCELLATION,
+    PARTIAL_CONFIRMATION,
+)

redsys/clients.py

@@ -0,0 +1,277 @@
+"""Client entry points for the RedSys platform.
+
+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``:
+
+    client = DirectClient(secret_key='...', merchant_code='...', terminal=1, sandbox=True)
+    response = client.payment(order='000000001', amount=Decimal('10.56'), currency=978).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)``.
+"""
+
+from hmac import compare_digest
+from logging import getLogger
+from re import sub
+
+from redsys.api import transactions
+from redsys.crypto import (
+    DEFAULT_SIGNATURE_VERSION,
+    HMAC_SHA256_V1,
+    HMAC_SHA512_V1,
+    HMAC_SHA512_V2,
+    SIGNATURE_VERSIONS,
+    get_signer,
+)
+from redsys.exceptions import ResponseError
+from redsys.models import (
+    CancellationMessage,
+    ConfirmationMessage,
+    DirectPaymentMessage,
+    DirectPreauthorizationMessage,
+    RedirectPaymentMessage,
+    RedirectPreauthorizationMessage,
+    RefundMessage,
+    Response,
+)
+from redsys.request import (
+    MERCHANT_PARAMETERS,
+    SIGNATURE,
+    SIGNATURE_VERSION,
+    Request,
+)
+
+logger = getLogger(__name__)
+
+# Default HTTP timeout (seconds) for direct-connection network calls; override per call.
+DEFAULT_TIMEOUT = 30
+
+__all__ = [
+    'Client',
+    'RedirectClient',
+    'DirectClient',
+    'AsyncDirectClient',
+    'Request',
+    'SIGNATURE_VERSION',
+    'MERCHANT_PARAMETERS',
+    'SIGNATURE',
+    'HMAC_SHA256_V1',
+    'HMAC_SHA512_V1',
+    'HMAC_SHA512_V2',
+    'SIGNATURE_VERSIONS',
+    'DEFAULT_SIGNATURE_VERSION',
+]
+
+
+def _normalize_signature(signature) -> str:
+    """Reduce a signature to its alphanumeric core for comparison.
+
+    RedSys returns response signatures in URL-safe Base64 ('-', '_') while
+    standard Base64 uses ('+', '/'). Comparing only the alphanumeric characters
+    makes the two alphabets and any padding compare equal.
+    """
+    if isinstance(signature, bytes):
+        signature = signature.decode('utf-8')
+    return sub(r'[^a-zA-Z0-9]', '', signature)
+
+
+class Client:
+    """Base client: credentials, account identity, request factory, response parsing."""
+
+    REAL_ENDPOINT: str | None = None
+    TEST_ENDPOINT: str | None = None
+
+    #: transaction_type -> request model. Unmapped types fall back to _DEFAULT_MODEL.
+    _DEFAULT_MODEL: type | None = None
+    _MODELS: dict[int, type] = {}
+
+    def __init__(
+        self,
+        secret_key: str,
+        *,
+        merchant_code: str | None = None,
+        terminal: int | None = None,
+        sandbox: bool = False,
+        signature_version: str = DEFAULT_SIGNATURE_VERSION,
+    ):
+        self._secret_key = secret_key
+        self.merchant_code = merchant_code
+        self.terminal = terminal
+        self.sandbox = sandbox
+        self.signature_version = signature_version
+        self.endpoint = self.TEST_ENDPOINT if sandbox else self.REAL_ENDPOINT
+
+    # -- 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)
+        return data
+
+    def _model_for(self, transaction_type: int) -> type:
+        model = self._MODELS.get(transaction_type, self._DEFAULT_MODEL)
+        if model is None:
+            raise NotImplementedError('This client defines no request model; use a concrete subclass.')
+        return model
+
+    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``).
+        """
+        data = self._inject(fields)
+        data.setdefault('transaction_type', transaction_type)
+        model = self._model_for(transaction_type)(**data)
+        return self._prepare(model)
+
+    def _prepare(self, model) -> Request:
+        return self._build_request(model)
+
+    def _build_request(self, model, signature_version: str | None = None, sender=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)
+
+    # -- response ---------------------------------------------------------
+    def parse_response(self, payload: dict) -> Response:
+        """Verify the signature and parse a received payload into a ``Response``.
+
+        Accepts both the redirect callback form fields and the direct REST JSON
+        body. Raises ``ValueError`` if the signature does not match (the payload
+        is not from RedSys or was tampered with), or ``ResponseError`` if RedSys
+        answered with an error code instead of a signed result.
+        """
+        if MERCHANT_PARAMETERS not in payload:
+            error_code = payload.get('errorCode') or payload.get('Ds_ErrorCode')
+            raise ResponseError(error_code, payload)
+        merchant_parameters = payload[MERCHANT_PARAMETERS]
+        if isinstance(merchant_parameters, str):
+            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.
+        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."""
+
+    # 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'
+    _DEFAULT_MODEL = RedirectPaymentMessage
+    _MODELS = {transactions.PREAUTHORIZATION: RedirectPreauthorizationMessage}
+
+    def payment(self, **fields) -> Request:
+        return self.request(transactions.AUTHORIZATION, **fields)
+
+    def preauthorization(self, **fields) -> Request:
+        return self.request(transactions.PREAUTHORIZATION, **fields)
+
+
+def _require_httpx():
+    try:
+        import httpx
+    except ImportError as exc:
+        raise ImportError('Sending requires httpx. Install with: pip install "python-redsys[http]".') from exc
+    return httpx
+
+
+class _DirectBase(Client):
+    """Shared REST direct-connection logic (transport-agnostic)."""
+
+    # 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'
+
+    _DEFAULT_MODEL = DirectPaymentMessage
+    _MODELS = {
+        transactions.PREAUTHORIZATION: DirectPreauthorizationMessage,
+        transactions.CONFIRMATION: ConfirmationMessage,
+        transactions.REFUND: RefundMessage,
+        transactions.CANCELLATION: 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
+
+    def payment(self, **fields) -> Request:
+        return self.request(transactions.AUTHORIZATION, **fields)
+
+    def preauthorization(self, **fields) -> Request:
+        return self.request(transactions.PREAUTHORIZATION, **fields)
+
+    def confirmation(self, **fields) -> Request:
+        return self.request(transactions.CONFIRMATION, **fields)
+
+    def refund(self, **fields) -> Request:
+        return self.request(transactions.REFUND, **fields)
+
+    def cancellation(self, **fields) -> Request:
+        return self.request(transactions.CANCELLATION, **fields)
+
+    def inicia(self, **fields) -> Request:
+        """3-D Secure step 1: build a request bound to the iniciaPeticionREST endpoint."""
+        model = self._DEFAULT_MODEL(**self._inject(fields))
+        return self._prepare(model, endpoint=self.inicia_endpoint)
+
+    def _prepare(self, model, endpoint: str | None = None) -> Request:
+        endpoint = endpoint or self.endpoint
+        return self._build_request(model, sender=self._make_sender(endpoint))
+
+    def _make_sender(self, endpoint):
+        raise NotImplementedError
+
+
+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())
+
+        return sender
+
+
+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

redsys/crypto.py

@@ -0,0 +1,123 @@
+"""Signature computation for the RedSys message envelope.
+
+Every version derives a per-operation key by encrypting the order number under
+the merchant secret, then HMACs the Base64 merchant parameters with that key.
+They differ in cipher, padding, hash, and output encoding:
+
+| Version          | Cipher  | Key                       | Order padding | HMAC    | Signature encoding      |
+|------------------|---------|---------------------------|---------------|---------|-------------------------|
+| HMAC_SHA256_V1   | 3DES    | Base64-decoded secret     | zero          | SHA-256 | Base64                  |
+| HMAC_SHA512_V1   | AES-128 | first 16 chars of secret  | PKCS7         | SHA-512 | Base64URL, '=' kept     |
+| HMAC_SHA512_V2   | AES-128 | first 16 chars of secret  | PKCS7         | SHA-512 | Base64URL, '=' stripped |
+
+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.
+
+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).
+"""
+
+from base64 import b64decode, b64encode, urlsafe_b64encode
+from hashlib import sha256, sha512
+from hmac import HMAC
+from json import dumps
+
+from cryptography.hazmat.decrepit.ciphers.algorithms import TripleDES  # 3DES, in decrepit since cryptography 43
+from cryptography.hazmat.primitives import padding
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+
+HMAC_SHA256_V1 = 'HMAC_SHA256_V1'
+HMAC_SHA512_V1 = 'HMAC_SHA512_V1'
+HMAC_SHA512_V2 = 'HMAC_SHA512_V2'
+
+
+class Signer:
+    """Computes the signature for a single signature version."""
+
+    version: str
+
+    def __init__(self, secret_key: str):
+        self._secret_key = secret_key
+
+    def encode_parameters(self, parameters: dict) -> bytes:
+        """Encode the wire dict as the Ds_MerchantParameters string this version expects."""
+        return b64encode(dumps(parameters, sort_keys=True).encode('utf-8'))
+
+    def _derive_key(self, order: str) -> bytes:
+        raise NotImplementedError
+
+    def sign(self, order: str, merchant_parameters: bytes) -> bytes:
+        raise NotImplementedError
+
+
+class Sha256V1Signer(Signer):
+    version = HMAC_SHA256_V1
+
+    def _derive_key(self, order: str) -> bytes:
+        key = b64decode(self._secret_key)
+        data = order.encode('utf-8')
+        data += b'\x00' * (-len(data) % 8)  # zero-pad to the 3DES block
+        encryptor = Cipher(TripleDES(key), modes.CBC(b'\x00' * 8)).encryptor()
+        return encryptor.update(data) + encryptor.finalize()
+
+    def sign(self, order: str, merchant_parameters: bytes) -> bytes:
+        derived = self._derive_key(order)
+        return b64encode(HMAC(derived, merchant_parameters, sha256).digest())
+
+
+class Sha512V1Signer(Signer):
+    version = HMAC_SHA512_V1
+
+    def _derive_key(self, order: str) -> bytes:
+        # Secret truncated to 16 chars, right-padded with '0' if shorter (REST manual v4.0.1).
+        key = self._secret_key[:16].ljust(16, '0').encode('utf-8')
+        padder = padding.PKCS7(128).padder()  # AES block size in bits
+        data = padder.update(order.encode('utf-8')) + padder.finalize()
+        encryptor = Cipher(algorithms.AES(key), modes.CBC(b'\x00' * 16)).encryptor()
+        return encryptor.update(data) + encryptor.finalize()
+
+    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).
+        derived = b64encode(self._derive_key(order))
+        # REST manual: Base64URL with the '=' padding kept.
+        return urlsafe_b64encode(HMAC(derived, merchant_parameters, sha512).digest())
+
+
+class Sha512V2Signer(Sha512V1Signer):
+    version = HMAC_SHA512_V2
+
+    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.
+        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).
+        return super().sign(order, merchant_parameters).rstrip(b'=')
+
+
+_SIGNERS = {
+    HMAC_SHA256_V1: Sha256V1Signer,
+    HMAC_SHA512_V1: Sha512V1Signer,
+    HMAC_SHA512_V2: Sha512V2Signer,
+}
+
+SIGNATURE_VERSIONS = tuple(_SIGNERS)
+DEFAULT_SIGNATURE_VERSION = HMAC_SHA512_V2
+
+
+def get_signer(secret_key: str, signature_version: str = DEFAULT_SIGNATURE_VERSION) -> Signer:
+    try:
+        signer_class = _SIGNERS[signature_version]
+    except KeyError:
+        raise ValueError(f'Unsupported signature version: {signature_version!r}') from None
+    return signer_class(secret_key)

redsys/exceptions.py

@@ -0,0 +1,19 @@
+class RedsysError(Exception):
+    """Base class for redsys errors."""
+
+
+class ResponseError(RedsysError):
+    """RedSys returned an error payload instead of a signed result."""
+
+    def __init__(self, error_code, payload=None):
+        self.error_code = error_code
+        self.payload = payload
+        super().__init__(f'RedSys returned error: {error_code}')
+
+
+class ValidationError(RedsysError):
+    """A parameter failed validation."""
+
+
+class UnknownParameterWarning(UserWarning):
+    """A request carries a RedSys wire-name parameter this library version does not model; it is sent as given."""