feat(setups): add klarna and stcpay actions, tamara fields, payment type

checkout_sdk/payments/setups/setups.py

@@ -4,7 +4,10 @@
 
 from checkout_sdk.common.common import Address, Phone
 from checkout_sdk.common.enums import Currency
-from checkout_sdk.payments.payments import PaymentType, PreferredSchema, ShippingDetails
+from checkout_sdk.payments.payments import PreferredSchema, ShippingDetails
+# Deprecated: PaymentType is re-exported here only so existing imports from this module keep
+# working. Payment Setups use PaymentSetupPaymentType. Will be removed in the next major version.
+from checkout_sdk.payments.payments import PaymentType  # noqa: F401
 
 
 # Enums
@@ -14,6 +17,21 @@ class PaymentMethodInitialization(str, Enum):
     ENABLED = 'enabled'
 
 
+class PaymentSetupPaymentType(str, Enum):
+    """The type of payment on a Payment Setup.
+
+    The Payment Setup schema declares these values lowercase. The /payments request uses
+    payments.payments.PaymentType, whose capitalized values (for example PayLater) the Payment
+    Setups API rejects, so the two enums are kept apart.
+    """
+    REGULAR = 'regular'
+    RECURRING = 'recurring'
+    MOTO = 'moto'
+    INSTALLMENT = 'installment'
+    PAY_LATER = 'pay_later'
+    UNSCHEDULED = 'unscheduled'
+
+
 # Shared payment-method enums
 class TerminalType(str, Enum):
     """The client-side terminal type of the wallet payment methods."""
@@ -126,9 +144,10 @@ class MerchantAccount:
     # The total number of orders made by the customer.
     # [Optional]
     total_order_count: int
-    # The payment amount of the customer's most recent transaction.
+    # The payment amount of the customer's most recent transaction. The specification types this
+    # as a number (example 55.99); the API currently stores it as an integer.
     # [Optional]
-    last_payment_amount: int
+    last_payment_amount: float
 
 
 class Customer:
@@ -164,20 +183,28 @@ class Customer:
 
 # Payment Method Common entities
 class PaymentMethodAction:
-    """The next available action for the Klarna, PayPal or instrument payment method.
+    """The next available action for the PayPal or instrument payment method.
 
-    The Cash App and Pay by Bank methods have their own action types (CashAppAction,
-    PayByBankAction), because their actions carry different properties.
+    The Klarna, stc pay, Cash App and Pay by Bank methods have their own action types
+    (KlarnaAction, StcpayAction, CashAppAction, PayByBankAction), because their actions carry
+    different properties. client_token and session_id are not part of the PayPal or instrument
+    action schemas.
     """
     # The type of action.
     # [Optional]
     # readOnly
-    # Enum: "sdk" (Klarna, PayPal) "set_instrument" (instrument)
+    # Enum: "sdk" (PayPal) "set_instrument" (instrument)
     type: str
+    # Deprecated: Not part of the PayPal or instrument action schema in the Payment Setups API
+    # specification; the API ignores it on requests. There is no replacement. Will be removed in
+    # the next major version.
     # The client token for the Klarna SDK.
     # [Optional]
     # readOnly
     client_token: str
+    # Deprecated: Not part of the PayPal or instrument action schema in the Payment Setups API
+    # specification; the API ignores it on requests. There is no replacement. Will be removed in
+    # the next major version.
     # The session ID.
     # [Optional]
     # readOnly
@@ -189,7 +216,12 @@ class PaymentMethodAction:
 
 
 class PaymentMethodOption:
-    """A payment method option. Not present in the current Payment Setup schema."""
+    """A payment method option.
+
+    Deprecated: Not part of any payment method schema in the Payment Setups API specification;
+    the API ignores it on requests. There is no replacement. Will be removed in the next major
+    version.
+    """
     # The identifier of the payment method option.
     # [Optional]
     id: str
@@ -202,7 +234,12 @@ class PaymentMethodOption:
 
 
 class PaymentMethodOptions:
-    """The payment method options. Not present in the current Payment Setup schema."""
+    """The payment method options.
+
+    Deprecated: Not part of any payment method schema in the Payment Setups API specification;
+    the API ignores it on requests. Klarna and stc pay expose action instead; the other methods
+    have no replacement. Will be removed in the next major version.
+    """
     # The SDK payment method option.
     # [Optional]
     sdk: PaymentMethodOption
@@ -230,7 +267,9 @@ class PaymentMethodBase:
     # readOnly
     flags: list  # list of str
     # The initialization state of the payment method. When you create a Payment Setup, this
-    # defaults to disabled.
+    # defaults to disabled. On update the API replaces the payment methods, so send enabled
+    # again to keep the method enabled. The specification does not state this; it is the API's
+    # behaviour.
     # [Optional]
     # Default: "disabled"
     initialization: PaymentMethodInitialization = PaymentMethodInitialization.DISABLED
@@ -245,8 +284,37 @@ class KlarnaAccountHolder:
     name: str
 
 
+class KlarnaActionType(str, Enum):
+    """The type of the Klarna action."""
+    SDK = 'sdk'
+
+
+class KlarnaAction:
+    """The next available action for the Klarna payment method. Response only."""
+    # The type of action.
+    # [Optional]
+    # readOnly
+    type: KlarnaActionType
+    # The client token for the Klarna SDK.
+    # [Optional]
+    # readOnly
+    client_token: str
+    # The session ID.
+    # [Optional]
+    # readOnly
+    session_id: str
+
+
 class Klarna(PaymentMethodBase):
     """The Klarna payment method's details and configuration."""
+    # The next available action for the payment method.
+    # [Optional]
+    # readOnly
+    action: KlarnaAction
+    # The IBAN of the account used to complete Klarna verification.
+    # [Optional]
+    # readOnly
+    iban: str
 
     def __init__(self):
         super().__init__()
@@ -255,21 +323,45 @@ def __init__(self):
         # [Optional]
         # readOnly
         self.account_holder: KlarnaAccountHolder
-        # The payment method options. Not present in the current Klarna schema.
+        # Deprecated: Not part of the Klarna schema in the Payment Setups API specification; the
+        # API ignores it on requests. Use action instead. Will be removed in the next major
+        # version.
+        # The payment method options.
         # [Optional]
         self.payment_method_options: PaymentMethodOptions
 
 
 # Stcpay entities
+class StcpayActionType(str, Enum):
+    """The type of the stc pay action."""
+    OTP = 'otp'
+
+
+class StcpayAction:
+    """The next available action for the stc pay payment method. Response only."""
+    # The type of action.
+    # [Optional]
+    # readOnly
+    type: StcpayActionType
+
+
 class Stcpay(PaymentMethodBase):
     """The stc pay payment method's details and configuration."""
+    # The next available action for the payment method.
+    # [Optional]
+    # readOnly
+    action: StcpayAction
 
     def __init__(self):
         super().__init__()
         # The one-time password (OTP) for stc pay.
         # [Optional]
+        # writeOnly
         self.otp: str
-        # The payment method options. Not present in the current stc pay schema.
+        # Deprecated: Not part of the stc pay schema in the Payment Setups API specification;
+        # the API ignores it on requests. Use action instead. Will be removed in the next major
+        # version.
+        # The payment method options.
         # [Optional]
         self.payment_method_options: PaymentMethodOptions
 
@@ -283,24 +375,42 @@ class Tabby(PaymentMethodBase):
 
     def __init__(self):
         super().__init__()
-        # The payment method options. Not present in the current Tabby schema.
+        # Deprecated: Not part of the Tabby schema in the Payment Setups API specification; the
+        # API ignores it on requests. There is no replacement. Will be removed in the next major
+        # version.
+        # The payment method options.
         # [Optional]
         self.payment_method_options: PaymentMethodOptions
 
 
 # Bizum entities
 class Bizum(PaymentMethodBase):
     """The Bizum payment method's details and configuration."""
+    # Deprecated: Not part of the Bizum schema in the Payment Setups API specification; the API
+    # ignores it on requests. There is no replacement. Will be removed in the next major version.
+    # The initialization state of the payment method.
+    # [Optional]
+    # Default: "disabled"
+    initialization: PaymentMethodInitialization = PaymentMethodInitialization.DISABLED
 
     def __init__(self):
         super().__init__()
-        # The payment method options. Not present in the current Bizum schema.
+        # Deprecated: Not part of the Bizum schema in the Payment Setups API specification; the
+        # API ignores it on requests. There is no replacement. Will be removed in the next major
+        # version.
+        # The payment method options.
         # [Optional]
         self.payment_method_options: PaymentMethodOptions
 
 
 class Blik(PaymentMethodBase):
     """The Blik payment method's details and configuration."""
+    # Deprecated: Not part of the Blik schema in the Payment Setups API specification; the API
+    # ignores it on requests. There is no replacement. Will be removed in the next major version.
+    # The initialization state of the payment method.
+    # [Optional]
+    # Default: "disabled"
+    initialization: PaymentMethodInitialization = PaymentMethodInitialization.DISABLED
     # The 6-digit BLIK code generated by the customer's banking app.
     # [Optional]
     # ^[0-9]{6}$
@@ -403,14 +513,22 @@ class PaymentSetupInstrument(PaymentSetupPaymentMethod):
     # [Optional]
     # readOnly
     type: str
-    # The customer's phone number. Not present in the current instrument schema.
+    # Deprecated: Not part of the instrument schema in the Payment Setups API
+    # specification; the API ignores it on requests. There is no replacement. Will be removed in
+    # the next major version.
+    # The customer's phone number.
     # [Optional]
     phone: Phone
-    # Account holder details for the payment. Not present in the current instrument schema.
+    # Deprecated: Not part of the instrument schema in the Payment Setups API
+    # specification; the API ignores it on requests. There is no replacement. Will be removed in
+    # the next major version.
+    # Account holder details for the payment.
     # [Optional]
     account_holder: PaymentSetupAccountHolder
+    # Deprecated: Not part of the instrument schema in the Payment Setups API
+    # specification; the API ignores it on requests. There is no replacement. Will be removed in
+    # the next major version.
     # Indicates whether to use the Real-Time Account Updater to update the card information.
-    # Not present in the current instrument schema.
     # [Optional]
     allow_update: bool
     # The next available action for the payment method. Its type is set_instrument.
@@ -450,9 +568,34 @@ class MobilePay(PaymentSetupPaymentMethod):
     pass
 
 
+class TamaraRiskAssessment:
+    """Risk signals about the customer, forwarded to Tamara with the payment."""
+    # Specifies whether the customer is a premium customer.
+    # [Optional]
+    premium_customer: bool
+    # The customer's risk score.
+    # [Optional]
+    risk_score: int
+    # The number of orders the customer has made in the last 24 hours.
+    # [Optional]
+    order_count_last24h: int
+    # The number of devices linked to the customer.
+    # [Optional]
+    linked_device_count: int
+
+
 class Tamara(PaymentSetupPaymentMethod):
     """The Tamara payment method's details and configuration."""
-    pass
+    # The initialization state of the payment method. When you create a Payment Setup, this
+    # defaults to disabled. On update the API replaces the payment methods, so send enabled
+    # again to keep the method enabled. The specification does not state this; it is the API's
+    # behaviour.
+    # [Optional]
+    # Default: "disabled"
+    initialization: PaymentMethodInitialization = PaymentMethodInitialization.DISABLED
+    # Risk signals about the customer, forwarded to Tamara with the payment.
+    # [Optional]
+    risk_assessment: TamaraRiskAssessment
 
 
 class MBWay(PaymentSetupPaymentMethod):
@@ -542,7 +685,8 @@ class Qpay(PaymentSetupPaymentMethod):
 class Ideal(PaymentSetupPaymentMethod):
     """The iDEAL payment method's details and configuration."""
     # A description of the products or services being paid for. Do not include HTML tags or
-    # special characters, as these are rejected by iDEAL.
+    # special characters, as these are rejected by iDEAL. The specification marks this
+    # optional, but the API keeps the method invalid until it is sent.
     # [Optional]
     # max 35 characters
     description: str
@@ -551,14 +695,16 @@ class Ideal(PaymentSetupPaymentMethod):
 class Knet(PaymentSetupPaymentMethod):
     """The KNET payment method's details and configuration."""
     # The customer's preferred language, as an ISO 639-1 code. For example, the language
-    # selected on your site, if the issuer's site supports it.
+    # selected on your site, if the issuer's site supports it. The specification marks this
+    # optional, but the API keeps the method invalid until it is sent.
     # [Optional]
     language: KnetLanguage
 
 
 class Bancontact(PaymentSetupPaymentMethod):
     """The Bancontact payment method's details and configuration."""
-    # The account holder's name.
+    # The account holder's name. The specification marks this optional, but the API keeps the
+    # method invalid until it is sent.
     # [Optional]
     # min 3 characters, max 100 characters
     account_holder_name: str
@@ -1912,10 +2058,11 @@ class PaymentSetupTerminal:
     # [Optional]
     # min 8 characters, max 8 characters
     id: str
-    # The local date and time on the terminal, in ISO 8601 format.
+    # The local date and time on the terminal, in ISO 8601 format. Pass a timezone-aware
+    # datetime so the offset is sent; microseconds are not sent.
     # [Optional]
-    # Format: date-time
-    local_date_time: str
+    # Format: date-time (RFC 3339)
+    local_date_time: datetime
 
 
 class AccountFundingTransactionIdentificationType(str, Enum):
@@ -2033,9 +2180,10 @@ class PaymentSetupsRequest:
     currency: Currency
     # The type of payment. You must provide this field for card payments in which the
     # cardholder is not present. For example, if the transaction is a recurring payment, or a
-    # mail order/telephone order (MOTO) payment. Defaults to regular.
+    # mail order/telephone order (MOTO) payment.
     # [Optional]
-    payment_type: PaymentType
+    # Default: "regular"
+    payment_type: PaymentSetupPaymentType
     # A reference you can use to identify the payment. For example, an order number.
     # [Optional]
     # max 80 characters