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

redsys/models.py

@@ -9,9 +9,13 @@ dict with ``model_validate``. Field constraints follow these RedSys documents:
 - TPV Virtual, Manual de Integración REST, RS.TE.CEL.MAN.0037, version 4.0.1 (2025-10-17),
   https://pagosonline.redsys.es/download/1738/
 - Guía de integración de Bizum, version 2.6 (2026-08-25), https://pagosonline.redsys.es/download/2053/
+- inSite guide, version 4.1 (2026-01-05), https://pagosonline.redsys.es/download/1751/
+- Pago por e-mail/SMS (PayGold), RS.TE.CEL.MAN.0026, version 1.8.2 (2026-04-20),
+  https://pagosonline.redsys.es/download/2056/
+- Integración de Google Pay, version 1.9 (2025-05-21), https://pagosonline.redsys.es/download/2045/
+- Apple Pay, guía de instalación, version 3.2 (2023-03-28), https://pagosonline.redsys.es/download/2050/
 - Developer portal pages "Firmar una operación", "Parámetros de entrada y salida" and "Operativa DCC".
-- Librería de integración en PHP 2.0.1 (https://pagosonline.redsys.es/download/3214/), the reference
-  for the response fields the guides omit.
+- Responses of the RedSys test environment, for the response fields the guides omit.
 """
 
 from base64 import b64decode, b64encode
@@ -20,17 +24,27 @@ from json import dumps, loads
 from typing import Any
 from warnings import warn
 
-from pydantic import AliasChoices, BaseModel, ConfigDict, Field, field_serializer, field_validator, model_validator
-
-from redsys.api.currencies import CURRENCIES, CURRENCY_DECIMALS
+from pydantic import (
+    AliasChoices,
+    BaseModel,
+    ConfigDict,
+    Field,
+    PrivateAttr,
+    field_serializer,
+    field_validator,
+    model_validator,
+)
+
+from redsys.api import emv3ds, options, paygold, responses, transactions, xpay
+from redsys.api.currencies import CURRENCIES, CURRENCY_DECIMALS, EUR
 from redsys.api.transactions import TRANSACTION_TYPES
+from redsys.codes import describe
 from redsys.exceptions import UnknownParameterWarning
 
-# 1.x request names that changed or went away in 2.0; the error names the replacement.
-_LEGACY_FIELDS: dict[str, str | None] = {
+# 1.x request names that changed in 2.0; the error names the replacement.
+_LEGACY_FIELDS: dict[str, str] = {
     'payment_method': 'pay_methods',
     'mobile_number': 'bizum_mobile_number',
-    'transaction_date': None,
 }
 
 
@@ -56,26 +70,22 @@ def minor_units_factor(currency: int | None) -> int:
 class BaseRequest(BaseModel):
     """Fields common to every operation message, with validation and wire serialization."""
 
-    # Construct with the snake_case names or the wire names; unknown names are screened below.
+    # extra='allow' keeps the unmodeled wire names that _screen_unknown_fields lets through.
     model_config = ConfigDict(populate_by_name=True, extra='allow')
 
     merchant_code: str = Field(alias='Ds_Merchant_MerchantCode', max_length=9)
     terminal: int = Field(alias='Ds_Merchant_Terminal', ge=1, le=999)
     transaction_type: int = Field(0, alias='Ds_Merchant_TransactionType')
     amount: Decimal = Field(alias='Ds_Merchant_Amount', description='Major units; scaled to minor units on the wire.')
-    currency: int = Field(alias='Ds_Merchant_Currency')
+    currency: int = Field(EUR, alias='Ds_Merchant_Currency')
     order: str = Field(alias='Ds_Merchant_Order', min_length=4, max_length=12, pattern=r'^[0-9]{4}[a-zA-Z0-9]{0,8}$')
     merchant_data: str | None = Field(None, alias='Ds_Merchant_MerchantData', max_length=1024)
+    module: str | None = Field(None, alias='Ds_Merchant_Module', description='Integration that sends the request.')
 
     @model_validator(mode='before')
     @classmethod
     def _screen_unknown_fields(cls, data: Any) -> Any:
-        """Reject typos and 1.x names; let unmodeled RedSys wire names through with a warning.
-
-        A parameter the library does not model yet is accepted under its wire
-        name (``Ds_Merchant_*``) and sent as given, so a RedSys addition does not
-        wait for a library release. Any other unknown name is a mistake and fails.
-        """
+        """Reject unknown and 1.x names; let unmodeled wire names (``Ds_Merchant_*``) through with a warning."""
         if not isinstance(data, dict):
             return data
         known = {name for name in cls.model_fields} | {f.alias for f in cls.model_fields.values() if f.alias}
@@ -83,9 +93,7 @@ class BaseRequest(BaseModel):
             if key in known:
                 continue
             if key in _LEGACY_FIELDS:
-                replacement = _LEGACY_FIELDS[key]
-                hint = f'use {replacement!r}' if replacement else 'it has no 2.x equivalent'
-                raise ValueError(f'{key!r} is a 1.x field name; {hint}.')
+                raise ValueError(f'{key!r} is a 1.x field name; use {_LEGACY_FIELDS[key]!r}.')
             if key.lower().startswith('ds_merchant_'):
                 warn(f'{key!r} is not modeled by this library; sent as given.', UnknownParameterWarning, stacklevel=2)
                 continue
@@ -127,13 +135,40 @@ class _StoredCredentialFields(BaseModel):
     identifier: str | None = Field(
         None, alias='Ds_Merchant_Identifier', max_length=40, description='Stored-card token; see redsys.api.cof.'
     )
-    direct_payment: str | None = Field(None, alias='Ds_Merchant_DirectPayment', description='"true" or "moto".')
+    direct_payment: str | None = Field(
+        None, alias='Ds_Merchant_DirectPayment', description='options.DIRECT_PAYMENT or options.MOTO.'
+    )
     cof_ini: str | None = Field(None, alias='Ds_Merchant_Cof_Ini', max_length=1, description='See redsys.api.cof.')
     cof_type: str | None = Field(None, alias='Ds_Merchant_Cof_Type', max_length=1, description='See redsys.api.cof.')
     cof_txnid: str | None = Field(None, alias='Ds_Merchant_Cof_Txnid', max_length=15)
+    group: str | None = Field(
+        None, alias='Ds_Merchant_Group', pattern=r'^[0-9]{1,9}$', description='Group that shares card references.'
+    )
+    email_titular: str | None = Field(
+        None, alias='Ds_Merchant_Email_Titular', max_length=100, description='Cardholder e-mail; gets a summary.'
+    )
+
+
+class _CardFields(BaseModel):
+    """Card data, inSite token and 3-D Secure data, accepted by both connections."""
+
+    pan: str | None = Field(None, alias='Ds_Merchant_Pan', max_length=19, pattern=r'^[0-9]{12,19}$')
+    expiry_date: str | None = Field(None, alias='Ds_Merchant_ExpiryDate', pattern=r'^[0-9]{4}$', description='YYMM.')
+    cvv2: str | None = Field(None, alias='Ds_Merchant_Cvv2', pattern=r'^[0-9]{3,4}$')
+    idoper: str | None = Field(None, alias='Ds_Merchant_Idoper', max_length=40, description='inSite operation token.')
+    emv3ds: dict[str, Any] | None = Field(None, alias='Ds_Merchant_EMV3DS', description='Build with redsys.threeds.')
+
+
+class _DirectOperationFields(BaseModel):
+    """Fields of every direct-connection operation."""
+
+    merchant_descriptor: str | None = Field(
+        None, alias='Ds_Merchant_MerchantDescriptor', max_length=25, description='Soft descriptor; bank activation.'
+    )
+    client_ip: str | None = Field(None, alias='Ds_Merchant_ClientIP', max_length=15, description='Customer IP.')
 
 
-class _RedirectFields(_StoredCredentialFields):
+class _RedirectFields(_StoredCredentialFields, _CardFields):
     """Fields of the redirect connection (browser form)."""
 
     merchant_url: str | None = Field(None, alias='Ds_Merchant_MerchantURL', max_length=250)
@@ -143,7 +178,7 @@ class _RedirectFields(_StoredCredentialFields):
     product_description: str | None = Field(None, alias='Ds_Merchant_ProductDescription', max_length=125)
     titular: str | None = Field(None, alias='Ds_Merchant_Titular', max_length=60)
     consumer_language: int | None = Field(None, alias='Ds_Merchant_ConsumerLanguage')
-    pay_methods: str | None = Field(None, alias='Ds_Merchant_PayMethods', description='"z" selects Bizum.')
+    pay_methods: str | None = Field(None, alias='Ds_Merchant_PayMethods', description='See redsys.api.pay_methods.')
     bizum_mobile_number: str | None = Field(None, alias='Ds_Merchant_Bizum_MobileNumber', max_length=19)
     excep_sca: str | None = Field(
         None,
@@ -151,32 +186,105 @@ class _RedirectFields(_StoredCredentialFields):
         max_length=3,
         description='PSD2 SCA exemption requested; codes in redsys.api.sca.',
     )
+    merchant_descriptor: str | None = Field(
+        None, alias='Ds_Merchant_MerchantDescriptor', max_length=25, description='Soft descriptor; bank activation.'
+    )
+    shipping_address_pyp: str | None = Field(
+        None, alias='Ds_Merchant_ShippingAddressPyP', pattern=r'^[SN]$', description='See redsys.api.options.'
+    )
+    perso_code: int | None = Field(
+        None, alias='Ds_Merchant_PersoCode', ge=0, le=9, description='Payment page personalization.'
+    )
+
+
+class _XPayFields(BaseModel):
+    """Google Pay and Apple Pay data; the wire names have no MERCHANT infix."""
+
+    xpay_data: str | None = Field(
+        None, alias='DS_XPAYDATA', max_length=10000, description='Encrypted wallet payload, as the wallet guide says.'
+    )
+    xpay_decoded_data: dict[str, Any] | None = Field(
+        None, alias='DS_XPAYDECODEDDATA', description='Wallet payload decrypted by the merchant.'
+    )
+    xpay_type: str | None = Field(None, alias='DS_XPAYTYPE', description='See redsys.api.xpay.')
+    xpay_origen: str | None = Field(None, alias='DS_XPAYORIGEN', description='See redsys.api.xpay.')
+
+    @field_validator('xpay_type')
+    @classmethod
+    def _validate_xpay_type(cls, value: str | None) -> str | None:
+        if value is not None and value not in xpay.TYPES:
+            raise ValueError('xpay_type is not valid.')
+        return value
+
+    @field_validator('xpay_origen')
+    @classmethod
+    def _validate_xpay_origen(cls, value: str | None) -> str | None:
+        if value is not None and value not in xpay.ORIGINS:
+            raise ValueError('xpay_origen is not valid.')
+        return value
+
+    @model_validator(mode='after')
+    def _one_wallet_payload_with_its_type_and_origin(self):
+        payloads = (self.xpay_data is not None) + (self.xpay_decoded_data is not None)
+        described = (self.xpay_type is not None) + (self.xpay_origen is not None)
+        if payloads > 1:
+            raise ValueError('xpay_data and xpay_decoded_data are mutually exclusive.')
+        if (payloads, described) not in ((0, 0), (1, 2)):
+            raise ValueError('a wallet payload goes with xpay_type and xpay_origen.')
+        return self
 
 
-class _DirectFields(_StoredCredentialFields):
+class _DirectFields(_StoredCredentialFields, _CardFields, _DirectOperationFields, _XPayFields):
     """Fields of the direct connection (server-to-server card data, 3DS, stored credentials)."""
 
-    pan: str | None = Field(None, alias='Ds_Merchant_Pan', max_length=19, pattern=r'^[0-9]{12,19}$')
-    expiry_date: str | None = Field(None, alias='Ds_Merchant_ExpiryDate', pattern=r'^[0-9]{4}$', description='YYMM.')
-    cvv2: str | None = Field(None, alias='Ds_Merchant_Cvv2', pattern=r'^[0-9]{3,4}$')
-    idoper: str | None = Field(None, alias='Ds_Merchant_Idoper', max_length=40, description='inSite operation token.')
-    emv3ds: dict[str, Any] | None = Field(None, alias='Ds_Merchant_EMV3DS', description='Build with redsys.threeds.')
+    mpi_external: dict[str, Any] | None = Field(
+        None, alias='Ds_Merchant_MpiExternal', description='Results of an external 3DS server.'
+    )
+    token_data: dict[str, Any] | None = Field(
+        None, alias='Ds_Merchant_TokenData', description='Network token cryptogram data.'
+    )
     # RedSys spells the wire name "Frecuency".
     date_frequency: str | None = Field(None, alias='Ds_Merchant_DateFrecuency', description='Days between charges.')
     charge_expiry_date: str | None = Field(None, alias='Ds_Merchant_ChargeExpiryDate', description='yyyy-MM-dd.')
     dcc: str | dict[str, Any] | None = Field(
-        None, alias='Ds_Merchant_DCC', description='"Y" on the 3DS initialization; then the accepted offer.'
+        None,
+        alias='Ds_Merchant_DCC',
+        description='options.DCC_QUERY on the 3DS initialization; then the accepted offer.',
     )
     excep_sca: str | None = Field(
         None,
         alias='Ds_Merchant_Excep_SCA',
         max_length=3,
-        description='PSD2 SCA exemption requested; codes in redsys.api.sca. "Y" on the 3DS initialization asks.',
+        description='PSD2 SCA exemption requested; codes in redsys.api.sca. sca.QUERY on the 3DS initialization asks.',
+    )
+
+
+class _PaymentFields(BaseModel):
+    """Fields of payments (type 0) and authentications (type 7) on both connections."""
+
+    tax_reference: str | None = Field(
+        None, alias='Ds_Merchant_Tax_Reference', max_length=100, description='Tax payment barcode; bank activation.'
     )
+    ota: str | None = Field(None, alias='Ds_Merchant_OTA', pattern=r'^S$', description='See redsys.api.options.')
+
 
+class _BizumFields(BaseModel):
+    """Bizum fields of payments on both connections."""
+
+    bizum_mrt_amount_variation: str | None = Field(
+        None,
+        alias='Ds_Merchant_Bizum_MrtAmountVariation',
+        pattern=r'^[0-9]+$',
+        description='Ceiling for later MIT amounts, in minor units; on the operation that creates the TID.',
+    )
 
-class RedirectPaymentMessage(BaseRequest, _RedirectFields):
-    """Redirect-connection payment (transaction type 0)."""
+
+class RedirectPaymentMessage(BaseRequest, _RedirectFields, _PaymentFields, _BizumFields):
+    """Redirect-connection payment (transaction type 0), authentication (7) or refund without original (34)."""
+
+    bizum_id_oper: str | None = Field(
+        None, alias='Ds_Merchant_Bizum_IdOper', description='Response.bizum_id_oper; asks RedSys for the backup.'
+    )
 
 
 class RedirectPreauthorizationMessage(BaseRequest, _RedirectFields):
@@ -185,12 +293,90 @@ class RedirectPreauthorizationMessage(BaseRequest, _RedirectFields):
     transaction_type: int = Field(1, alias='Ds_Merchant_TransactionType')
 
 
-class DirectPaymentMessage(BaseRequest, _DirectFields):
-    """Direct-connection card payment (transaction type 0)."""
+class _PayGoldFields(BaseModel):
+    """Fields of a PayGold link (types 15 and 51)."""
+
+    customer_mobile: str | None = Field(None, alias='Ds_Merchant_Customer_Mobile', max_length=19)
+    customer_mail: str | None = Field(None, alias='Ds_Merchant_Customer_Mail', max_length=100)
+    customer_sms_text: str | None = Field(
+        None, alias='Ds_Merchant_Customer_Sms_Text', max_length=160, description='Must contain paygold.SMS_URL.'
+    )
+    p2f_expiry_date: str | None = Field(
+        None,
+        alias='Ds_Merchant_P2f_ExpiryDate',
+        pattern=r'^([0-9]{1,23}|[0-9]{4}-[0-9]{2}-[0-9]{2}-[0-9]{2}\.[0-9]{2}\.[0-9]{2}\.[0-9]{3})$',
+        description='Minutes from now, or yyyy-mm-dd-HH.MM.ss.sss.',
+    )
+    p2f_xml_data: str | None = Field(
+        None, alias='Ds_Merchant_P2f_XmlData', max_length=1000, description='E-mail tags; see redsys.api.paygold.'
+    )
+    alt_transaction_type: int | None = Field(
+        None,
+        alias='Ds_Merchant_AltTransType',
+        description='transactions.REFUND_WITHOUT_ORIGINAL turns the link into a refund without original.',
+    )
+    pay_methods: str | None = Field(None, alias='Ds_Merchant_PayMethods', description='See redsys.api.pay_methods.')
+    merchant_url: str | None = Field(None, alias='Ds_Merchant_MerchantURL', max_length=250)
+
+    @field_validator('customer_sms_text')
+    @classmethod
+    def _sms_text_holds_the_link(cls, value: str | None) -> str | None:
+        if value is not None and paygold.SMS_URL not in value:
+            raise ValueError(f'customer_sms_text must contain {paygold.SMS_URL}.')
+        return value
+
+    @field_validator('p2f_expiry_date', mode='before')
+    @classmethod
+    def _minutes_as_text(cls, value):
+        return str(value) if isinstance(value, int) and not isinstance(value, bool) else value
+
+    @field_validator('alt_transaction_type')
+    @classmethod
+    def _validate_alt_transaction_type(cls, value: int | None) -> int | None:
+        if value is not None and value != transactions.REFUND_WITHOUT_ORIGINAL:
+            raise ValueError('alt_transaction_type is 34, refund without original.')
+        return value
+
+
+class DirectPaymentMessage(BaseRequest, _DirectFields, _PaymentFields, _PayGoldFields, _BizumFields):
+    """Direct-connection card payment (transaction type 0), and the types without their own message."""
 
     sum_total: Decimal | None = Field(
         None, alias='Ds_Merchant_SumTotal', description='Recurring series total; scaled like amount.'
     )
+    financing: str | dict[str, Any] | None = Field(
+        None,
+        alias='Ds_Merchant_Financing',
+        description='options.FINANCING_QUERY on the 3DS initialization; then the chosen option.',
+    )
+    matching_data: str | None = Field(
+        None, alias='Ds_Merchant_MatchingData', max_length=21, description='Unique; type 17, with acquirer_identifier.'
+    )
+    acquirer_identifier: str | None = Field(
+        None, alias='Ds_Acquirer_Identifier', pattern=r'^[0-9]{1,6}$', description='Type 17, with matching_data.'
+    )
+    bizum_mobile_number: str | None = Field(None, alias='Ds_Merchant_Bizum_MobileNumber', max_length=19)
+    otp: str | None = Field(
+        None, alias='Ds_Merchant_Otp', pattern=r'^[0-9]+$', description='Bizum backup one-time password.'
+    )
+
+    @field_validator('otp', mode='before')
+    @classmethod
+    def _otp_as_text(cls, value):
+        return str(value) if isinstance(value, int) and not isinstance(value, bool) else value
+
+    @field_validator('financing')
+    @classmethod
+    def _validate_financing(cls, value):
+        if isinstance(value, str) and value != options.FINANCING_QUERY:
+            raise ValueError('financing is "Y" or the chosen option.')
+        return value
+
+    @model_validator(mode='after')
+    def _matching_data_with_acquirer(self):
+        if (self.matching_data is None) != (self.acquirer_identifier is None):
+            raise ValueError('matching_data and acquirer_identifier go together.')
+        return self
 
     @field_serializer('sum_total')
     def _serialize_sum_total(self, value: Decimal | None) -> int | None:
@@ -203,21 +389,30 @@ class DirectPreauthorizationMessage(BaseRequest, _DirectFields):
     transaction_type: int = Field(1, alias='Ds_Merchant_TransactionType')
 
 
-class ConfirmationMessage(BaseRequest):
+class ConfirmationMessage(BaseRequest, _DirectOperationFields):
     """Capture of a previous preauthorization (transaction type 2)."""
 
     transaction_type: int = Field(2, alias='Ds_Merchant_TransactionType')
 
 
-class RefundMessage(BaseRequest):
+class RefundMessage(BaseRequest, _DirectOperationFields):
     """Refund of a previous payment (transaction type 3)."""
 
     transaction_type: int = Field(3, alias='Ds_Merchant_TransactionType')
     authorization_code: str | None = Field(None, alias='Ds_Merchant_AuthorisationCode', max_length=6)
+    transaction_date: str | None = Field(
+        None,
+        alias='Ds_Merchant_TransactionDate',
+        pattern=r'^[0-9]{4}-[0-9]{2}-[0-9]{2}$',
+        description='yyyy-mm-dd of the original operation.',
+    )
+    rts: str | None = Field(
+        None, alias='Ds_Merchant_RTS', pattern=r'^[0-9]{1,24}$', description='Response.rts of a partial confirmation.'
+    )
 
 
-class CancellationMessage(BaseRequest):
-    """Cancellation of a preauthorization (transaction type 9)."""
+class CancellationMessage(BaseRequest, _DirectOperationFields):
+    """Void of a preauthorization (transaction type 9) or another cancellation (types 45 to 47)."""
 
     transaction_type: int = Field(9, alias='Ds_Merchant_TransactionType')
 
@@ -247,8 +442,7 @@ class Response(BaseModel):
     card_country: str | None = Field(None, alias='Ds_Card_Country')
     card_type: str | None = Field(None, alias='Ds_Card_Type')
     card_brand: str | None = Field(None, alias='Ds_Card_Brand')
-    # Not in the integration guides: returned by the test environment (verified 2026-10-25)
-    # and modeled by the official PHP library 2.0.1.
+    # Not in the integration guides; returned by the test environment.
     card_typology: str | None = Field(None, alias='Ds_Card_Typology', description='For example CONSUMO.')
     eci: str | None = Field(None, alias='Ds_ECI', description='E-commerce indicator of the authentication.')
     response_description: str | None = Field(None, alias='Ds_Response_Description')
@@ -268,11 +462,26 @@ class Response(BaseModel):
     dcc: dict[str, Any] | None = Field(None, alias='Ds_DCC', description='Offer from the 3DS initialization.')
     identifier: str | None = Field(None, alias='Ds_Merchant_Identifier', description='Token returned on request.')
     cof_txnid: str | None = Field(None, alias='Ds_Merchant_Cof_Txnid')
-    processed_pay_method: str | None = Field(None, alias='Ds_ProcessedPayMethod', description='68 = Bizum.')
+    processed_pay_method: str | None = Field(
+        None, alias='Ds_ProcessedPayMethod', description='See redsys.api.processed_pay_methods.'
+    )
     bizum_id_oper: str | None = Field(None, alias='Ds_Bizum_IdOper')
     bizum_cuenta_truncada: str | None = Field(None, alias='Ds_Bizum_CuentaTruncada')
     currency_dcc: str | None = Field(None, alias='Ds_Currency_DCC', description='Dynamic currency conversion.')
     amount_dcc: str | None = Field(None, alias='Ds_Amount_DCC', description='Minor units in Ds_Currency_DCC.')
+    rts: str | None = Field(None, alias='rts', description='Partial confirmation reference; refund it with rts=.')
+    rtp_status: str | None = Field(None, alias='Ds_RtpStatus', description='Bizum Request-to-Pay: OK or KO.')
+    rtp_response: str | None = Field(None, alias='Ds_RtpResponse', description='BIZnnnnn; see redsys.api.bizum.')
+    rtp_description: str | None = Field(None, alias='Ds_RtpDescription')
+    rtp_backup_html: str | None = Field(None, alias='Ds_RtpBackupHtml', description='Base64 HTML backup form.')
+    rtp_backup_template: str | None = Field(
+        None, alias='Ds_RtpBackupTemplate', description='Base64 JSON pieces of a backup form.'
+    )
+    url_pago_2_fases: str | None = Field(None, alias='Ds_UrlPago2Fases', description='PayGold payment link.')
+
+    _http_status: int | None = PrivateAttr(None)
+    _http_headers: dict[str, str] | None = PrivateAttr(None)
+    _raw_body: str | None = PrivateAttr(None)
 
     @field_validator('amount', mode='before')
     @classmethod
@@ -292,25 +501,50 @@ class Response(BaseModel):
     def get_order(self) -> str | None:
         return self.order
 
+    def _with_transport(self, http_status: int, http_headers: dict[str, str], raw_body: str) -> 'Response':
+        self._http_status, self._http_headers, self._raw_body = http_status, http_headers, raw_body
+        return self
+
+    @property
+    def http_status(self) -> int | None:
+        """HTTP status of the direct call; ``None`` when parsed from a received payload."""
+        return self._http_status
+
+    @property
+    def http_headers(self) -> dict[str, str] | None:
+        """HTTP headers of the direct call; ``None`` when parsed from a received payload."""
+        return self._http_headers
+
+    @property
+    def raw_body(self) -> str | None:
+        """Unprocessed HTTP body of the direct call; ``None`` when parsed from a received payload."""
+        return self._raw_body
+
     @property
     def response_code(self):
-        # A 3DS challenge response may carry no Ds_Response. The code is returned
-        # as-is; see docs/response-codes.md for the English meanings.
+        # A 3DS challenge response may carry no Ds_Response.
         return int(self.response) if self.response not in (None, '') else None
 
+    def describe(self, language='es') -> str:
+        """Meaning of ``Ds_Response``, or of ``Ds_ErrorCode`` without it; see ``redsys.codes.describe``."""
+        code = self.response if self.response not in (None, '') else self.error_code
+        return describe(code, language) if code else ''
+
     def is_paid(self) -> bool:
-        return self.response_code is not None and 0 <= self.response_code <= 99
+        return (
+            self.response_code is not None and responses.AUTHORIZED <= self.response_code <= responses.AUTHORIZED_LAST
+        )
 
     def is_refunded(self) -> bool:
-        return self.response_code == 900
+        return self.response_code == responses.REFUND_OR_CONFIRMATION_AUTHORIZED
 
     def is_canceled(self) -> bool:
-        return self.response_code == 400
+        return self.response_code == responses.CANCELLATION_AUTHORIZED
 
     def is_authorized(self) -> bool:
         return self.is_paid() or self.is_refunded() or self.is_canceled()
 
-    # 3-D Secure (EMV 3DS) accessors over the Ds_EMV3DS response object.
+    # == EMV 3DS accessors over Ds_EMV3DS ==
     @property
     def _emv3ds(self) -> dict:
         return self.emv3ds or {}
@@ -336,10 +570,10 @@ class Response(BaseModel):
         return self._emv3ds.get('creq')
 
     def is_no_3ds(self) -> bool:
-        return self.protocol_version == 'NO_3DS_V2'
+        return self.protocol_version == emv3ds.NO_3DS_V2
 
     def requires_challenge(self) -> bool:
-        return self._emv3ds.get('threeDSInfo') == 'ChallengeRequest'
+        return self._emv3ds.get('threeDSInfo') == emv3ds.CHALLENGE_REQUEST
 
 
 __all__ = [

redsys/orders.py

@@ -0,0 +1,20 @@
+"""Order numbers for ``Ds_Merchant_Order``."""
+
+from secrets import choice
+from string import ascii_letters, digits
+
+_ALPHANUMERIC = ascii_letters + digits
+
+
+def generate_order(length: int = 12) -> str:
+    """A random order number of ``length`` characters (4 to 12): 4 digits, then letters and digits.
+
+    RedSys recommends the 4 leading digits. A random draw makes a repeated order (SIS0051)
+    unlikely, not impossible. Raises ``ValueError`` for a length outside 4 to 12.
+    """
+    if isinstance(length, bool) or not isinstance(length, int) or not 4 <= length <= 12:
+        raise ValueError('length must be an integer from 4 to 12.')
+    return ''.join(choice(digits) for _ in range(4)) + ''.join(choice(_ALPHANUMERIC) for _ in range(length - 4))
+
+
+__all__ = ['generate_order']

redsys/request.py

@@ -9,26 +9,32 @@ def _as_text(value):
 
 
 class Request:
-    """A signed request, ready to serialize or send -- the return of every operation.
+    """A signed request, the return of every operation.
 
-    Holds the three fields RedSys exchanges (the Base64 merchant parameters, the
-    signature over them, and the signature version) and the two ways to hand it
-    off:
-
-    - ``to_dict()`` -- the three ``Ds_*`` fields to POST (redirect form fields or
-      REST JSON body). Always available.
-    - ``send()`` -- performs the REST call and returns the parsed ``Response``.
-      Only direct-connection clients bind a sender; for redirect requests (the
-      browser submits them) it raises ``TypeError`` -- use ``to_dict()``.
-
-    Async clients bind an awaitable sender, so ``await request.send()`` works.
+    ``to_dict()`` gives the three ``Ds_*`` fields to post: the redirect form fields or the
+    REST JSON body. ``send()`` performs the REST call and returns the parsed ``Response``;
+    it is awaitable on ``AsyncDirectClient`` and raises ``TypeError`` on a redirect request.
     """
 
-    def __init__(self, merchant_parameters: bytes, signature: bytes, signature_version: str, *, sender=None):
+    def __init__(
+        self,
+        merchant_parameters: bytes,
+        signature: bytes,
+        signature_version: str,
+        *,
+        sender=None,
+        endpoint: str | None = None,
+    ):
         self._merchant_parameters = merchant_parameters
         self._signature = signature
         self._signature_version = signature_version
         self._sender = sender
+        self._endpoint = endpoint
+
+    @property
+    def endpoint(self) -> str | None:
+        """The URL this request goes to: the form ``action`` on redirect, the REST URL on direct."""
+        return self._endpoint
 
     @property
     def merchant_parameters(self) -> bytes:

redsys/threeds.py

@@ -1,20 +1,25 @@
-"""Builders for the Ds_Merchant_EMV3DS object used in 3-D Secure v2 (REST direct connection).
+"""Builders for the ``Ds_Merchant_EMV3DS`` object of 3-D Secure v2 on the direct connection.
 
-Flow: inicia (`card_data`) -> authorize (`authentication_data`) -> [challenge] ->
-finalize (`challenge_response`). See docs/direct-connection.md. The
-EMV3DS sub-field names are case-sensitive and passed through verbatim.
+The step numbers follow docs/direct-connection.md. The sub-field names are case-sensitive.
 
-Each function returns the dict to assign to a request's `emv3ds` field, e.g.
+    client.payment(emv3ds=threeds.authentication_data(..., three_ds_comp_ind=emv3ds.METHOD_COMPLETED), ...)
+"""
 
-    from redsys import threeds
+from base64 import urlsafe_b64encode
+from json import dumps
 
-    response = client.inicia(..., emv3ds=threeds.card_data()).send()
-"""
+from redsys.api import emv3ds
 
 
 def card_data() -> dict:
-    """EMV3DS payload for the iniciaPeticionREST call (step 1)."""
-    return {'threeDSInfo': 'CardData'}
+    """``emv3ds`` of the 3-D Secure initialization, iniciaPeticionREST (step 1)."""
+    return {'threeDSInfo': emv3ds.CARD_DATA}
+
+
+def method_data(*, three_ds_server_trans_id, notification_url) -> str:
+    """Value of the ``threeDSMethodData`` form field the browser posts to ``threeDSMethodURL`` (step 2)."""
+    payload = {'threeDSServerTransID': three_ds_server_trans_id, 'threeDSMethodNotificationURL': notification_url}
+    return urlsafe_b64encode(dumps(payload, separators=(',', ':')).encode('utf-8')).decode('ascii').rstrip('=')
 
 
 def browser_info(
@@ -30,7 +35,7 @@ def browser_info(
     javascript_enabled=True,
     ip=None,
 ) -> dict:
-    """Cardholder browser data the merchant page collects for the authorization."""
+    """Cardholder browser data, collected by the merchant page, for ``authentication_data()``."""
     data = {
         'browserAcceptHeader': accept_header,
         'browserUserAgent': user_agent,
@@ -48,11 +53,11 @@ def browser_info(
 
 
 def authentication_data(
-    *, three_ds_server_trans_id, notification_url, protocol_version, browser, three_ds_comp_ind='Y'
+    *, three_ds_server_trans_id, notification_url, protocol_version, browser, three_ds_comp_ind=emv3ds.METHOD_COMPLETED
 ) -> dict:
-    """EMV3DS payload for the authorization call (step 3). `browser` is `browser_info(...)`."""
+    """``emv3ds`` of the authentication (step 3); ``browser`` is ``browser_info(...)``."""
     data = {
-        'threeDSInfo': 'AuthenticationData',
+        'threeDSInfo': emv3ds.AUTHENTICATION_DATA,
         'protocolVersion': protocol_version,
         'threeDSServerTransID': three_ds_server_trans_id,
         'notificationURL': notification_url,
@@ -63,5 +68,5 @@ def authentication_data(
 
 
 def challenge_response(*, cres, protocol_version) -> dict:
-    """EMV3DS payload to finalize the authorization after the challenge (step 5)."""
-    return {'threeDSInfo': 'ChallengeResponse', 'protocolVersion': protocol_version, 'cres': cres}
+    """``emv3ds`` of the operation after the challenge (step 5)."""
+    return {'threeDSInfo': emv3ds.CHALLENGE_RESPONSE, 'protocolVersion': protocol_version, 'cres': cres}