checkout_sdk 2.5.0 → 2.7.0

data/lib/checkout_sdk/accounts/representative.rb

@@ -2,32 +2,93 @@
 
 module CheckoutSdk
   module Accounts
+    # A representative of the sub-entity. One class covers every shape the Accounts API defines: the v3.0
+    # person of interest (individual, roles, company_position, ownership_percentage, documents), the v3.0
+    # controlling company of EEA and GB Company Full (company, ownership_percentage), and the v2.0 company
+    # representative (the flat person fields, roles, documents and, on the US variants, identification).
     # @!attribute id
+    #   The representative's id.
+    #   [Optional]
+    #   ^rep_[a-z0-9]{26}$
+    #   30 characters
     #   @return [String]
     # @!attribute individual
+    #   Information about the individual representing the sub-entity.
+    #   [Required] for every v3.0 person of interest.
     #   @return [RepresentativeIndividual] Personal details (Accounts API v3.0).
     # @!attribute company_position
+    #   The position of the representative within the company (required for the control_person role).
+    #   [Optional] (EEA, GB and US Company Full (3.0) and US ISV Seller Company (3.0))
     #   @return [String] {CompanyPosition}
     # @!attribute ownership_percentage
+    #   The percentage ownership of the UBO or controlling company (required when over 25%).
+    #   [Optional]
+    #   min 25, max 100 on the EEA, GB and US Company Full (3.0) variants; min 0, max 100 on the US ISV
+    #   Seller variants
     #   @return [Integer]
+    # @!attribute roles
+    #   The individual's roles within the company ({EntityRoles} values). For sole traders, must be ubo only.
+    #   [Required] for every variant except EEA and US Company Lite (2.0), where it is [Optional].
+    #   @return [Array(String)] {EntityRoles}
+    # @!attribute documents
+    #   Verification documents for the individual representative. On the EEA, GB and US Company Full (3.0)
+    #   and Sole Trader Full (3.0) variants the API validates this object strictly and rejects any key the
+    #   variant does not define; the US ISV Seller (3.0) and v2.0 variants do not declare it strict. See
+    #   {RepresentativeDocuments} for the keys each variant accepts.
+    #   [Required] for the EEA, GB and US Sole Trader Full (3.0) variants and EEA Company Full (2.0);
+    #   [Optional] otherwise.
+    #   @return [RepresentativeDocuments]
+    # @!attribute company
+    #   The controlling company, when the representative is a company rather than an individual.
+    #   [Required] for a controlling company representative (EEA and GB Company Full (3.0) only).
+    #   The API reads only three attributes here, all [Required]: legal_name, trading_name and
+    #   registered_address. Leave the other {Company} attributes unset.
+    #   @return [Company]
     # @!attribute first_name
+    #   The representative's first name. Accounts API v2.0 only.
+    #   [Required] (v2.0)
+    #   min 2 characters, max 50 characters
+    #   @deprecated Not used by the Accounts API v3.0 schema; use individual.
+    #   @return [String]
+    # @!attribute middle_name
+    #   The representative's middle name. Required if it appears in official documents. Accounts API v2.0
+    #   only.
+    #   [Optional]
+    #   min 2 characters, max 50 characters
+    #   @deprecated Not used by the Accounts API v3.0 schema; use individual.
     #   @return [String]
     # @!attribute last_name
+    #   The representative's last name. Accounts API v2.0 only.
+    #   [Required] (v2.0)
+    #   min 2 characters, max 50 characters
+    #   @deprecated Not used by the Accounts API v3.0 schema; use individual.
     #   @return [String]
     # @!attribute address
+    #   The representative's address. Accounts API v2.0 only.
+    #   [Required] (v2.0)
+    #   @deprecated Not used by the Accounts API v3.0 schema; use individual.
     #   @return [CheckoutSdk::Common::Address]
     # @!attribute identification
+    #   The representative's identification. Accounts API v2.0 US Company variants only.
+    #   [Required] for US Company Full (2.0); [Optional] for US Company Lite (2.0).
+    #   @deprecated Not used by the Accounts API v3.0 schema.
     #   @return [Identification]
     # @!attribute phone
+    #   The representative's phone number. Accounts API v2.0 only.
+    #   [Optional]
+    #   @deprecated Not used by the Accounts API v3.0 schema; use individual.
     #   @return [Phone]
     # @!attribute date_of_birth
+    #   The date of birth of the person according to the Gregorian calendar. Accounts API v2.0 only.
+    #   [Required] for the v2.0 Full variants; [Optional] for the v2.0 Lite variants.
+    #   @deprecated Not used by the Accounts API v3.0 schema; use individual.
     #   @return [DateOfBirth]
     # @!attribute place_of_birth
+    #   The place of birth of the person. Accounts API v2.0 only.
+    #   [Required] for EEA Company Full (2.0); [Optional] for EEA Company Lite (2.0). Not part of the other
+    #   v2.0 variants.
+    #   @deprecated Not used by the Accounts API v3.0 schema; use individual.
     #   @return [PlaceOfBirth]
-    # @!attribute roles
-    #   @return [Array(String)]
-    # @!attribute documents
-    #   @return [OnboardSubEntityDocuments]
     class Representative
       attr_accessor :id,
                     :individual,
@@ -35,8 +96,10 @@ module CheckoutSdk
                     :ownership_percentage,
                     :roles,
                     :documents,
+                    :company,
                     # v2.0 only — deprecated; use `individual` for v3.0
                     :first_name,
+                    :middle_name,
                     :last_name,
                     :address,
                     :identification,

data/lib/checkout_sdk/accounts/representative_documents.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Accounts
+    # Verification documents for an individual representative, sent as company.representatives[].documents.
+    #
+    # On the EEA, GB and US Company Full (3.0) and the EEA, GB and US Sole Trader Full (3.0) variants the
+    # API validates this object strictly: a key it does not recognise is rejected, not ignored. The US ISV
+    # Seller variants (3.0) and the v2.0 variants do not declare it strict. These four are the only keys
+    # any variant defines, and which apply depends on the variant: EEA Sole Trader Full (3.0) requires
+    # identity_verification, proof_of_residential_address and proof_of_registration; GB and US Sole Trader
+    # Full (3.0) require identity_verification; the EEA, GB and US Company Full (3.0) variants and US ISV
+    # Seller Company (3.0) accept identity_verification and certified_authorised_signatory, both optional;
+    # US ISV Seller Sole Trader (3.0) accepts identity_verification, optional. The v2.0 company
+    # representatives use identity_verification only.
+    #
+    # Leave an attribute unset rather than assigning nil: an attribute set to nil is sent as null.
+    # Company-level documents such as bank_verification belong on {OnboardSubEntityDocuments}.
+    # @!attribute identity_verification
+    #   The document to use to confirm the individual's identity.
+    #   [Optional] (required for the sole trader full variants)
+    #   @return [Document]
+    # @!attribute certified_authorised_signatory
+    #   Certified authorised signatory document. Required when the legal representative or other role
+    #   owner is not registered on the certificate of incorporation.
+    #   [Optional] (EEA, GB and US Company Full (3.0) and US ISV Seller Company (3.0) only)
+    #   @return [CertifiedAuthorisedSignatory]
+    # @!attribute proof_of_residential_address
+    #   Proof of residential address of the representative.
+    #   [Optional] (required for EEA Sole Trader Full (3.0), and only valid there)
+    #   @return [ProofOfResidentialAddress]
+    # @!attribute proof_of_registration
+    #   Proof of the sole trader's registration, for example an extract from a trade register.
+    #   [Optional] (required for EEA Sole Trader Full (3.0), and only valid there)
+    #   @return [ProofOfRegistration]
+    class RepresentativeDocuments
+      attr_accessor :identity_verification,
+                    :certified_authorised_signatory,
+                    :proof_of_residential_address,
+                    :proof_of_registration
+    end
+  end
+end

data/lib/checkout_sdk/accounts/representative_individual.rb

@@ -2,29 +2,62 @@
 
 module CheckoutSdk
   module Accounts
-    # The personal details of a company representative ("person of interest"), as required by the
-    # Accounts API v3.0 schema.
+    # The personal details of a company representative (company.representatives[].individual), Accounts
+    # API v3.0.
     # @!attribute first_name
+    #   The representative's first name.
+    #   [Required]
+    #   min 2 characters, max 50 characters
     #   @return [String]
     # @!attribute middle_name
+    #   The representative's middle name. Required if it appears in official documents.
+    #   [Optional]
+    #   min 2 characters, max 50 characters
     #   @return [String]
     # @!attribute last_name
+    #   The representative's last name.
+    #   [Required]
+    #   min 2 characters, max 50 characters
     #   @return [String]
     # @!attribute date_of_birth
+    #   The date of birth of the person according to the Gregorian calendar.
+    #   [Required]
     #   @return [DateOfBirth]
     # @!attribute place_of_birth
+    #   The place of birth of the person.
+    #   [Required]
     #   @return [PlaceOfBirth]
     # @!attribute citizenships
+    #   The list of citizenships or legal statuses for the representative.
+    #   [Required] for the US ISV Seller variants only; not part of the other v3.0 schemas, leave unset for
+    #   them.
     #   @return [Array(Citizenship)]
     # @!attribute national_id_type
+    #   The classification of the national identification number provided.
+    #   [Required] for the US ISV Seller variants only; not part of the other v3.0 schemas, leave unset for
+    #   them.
     #   @return [String] {NationalIdType}
     # @!attribute national_id_number
+    #   The representative's national identification number.
+    #   [Required] for the US ISV Seller variants; [Optional] for the other v3.0 variants.
+    #   The format depends on the variant:
+    #     US ISV Seller: the number for the national_id_type given. ^[a-zA-Z0-9\-]+$, min 5 characters, max
+    #     16 characters.
+    #     Other v3.0 variants: a Social Security Number (SSN) or Individual Taxpayer Identification Number
+    #     (ITIN), US residents only. ^\d{9}$, 9 characters.
     #   @return [String]
     # @!attribute email_address
+    #   The representative's personal email address.
+    #   [Required] for the US ISV Seller variants; [Optional] for the other v3.0 variants.
+    #   Format: email
     #   @return [String]
     # @!attribute phone
+    #   The representative's phone number.
+    #   [Required] for the US ISV Seller variants; [Optional] for the other v3.0 variants.
     #   @return [Phone]
     # @!attribute address
+    #   The representative's address.
+    #   [Required]
     #   @return [CheckoutSdk::Common::Address]
     class RepresentativeIndividual
       attr_accessor :first_name,

data/lib/checkout_sdk/accounts/shareholder_structure.rb

@@ -2,9 +2,17 @@
 
 module CheckoutSdk
   module Accounts
+    # Shareholder structure chart (including % of shares) certified by a competent authority individual and
+    # dated within the last 3 months.
     # @!attribute type
-    #   @return [ShareholderStructureType]
+    #   The type of document.
+    #   [Required]
+    #   @return [String] {ShareholderStructureType}
     # @!attribute front
+    #   The ID of the front side of the document as represented within Checkout.com systems.
+    #   [Required]
+    #   ^file_[a-z2-7]{26}$
+    #   31 characters
     #   @return [String]
     class ShareholderStructure
       attr_accessor :type,

data/lib/checkout_sdk/accounts/shareholder_structure_type.rb

@@ -2,6 +2,7 @@
 
 module CheckoutSdk
   module Accounts
+    # The document type accepted as a certified shareholder structure.
     module ShareholderStructureType
       CERTIFIED_SHAREHOLDER_STRUCTURE = 'certified_shareholder_structure'
     end

data/lib/checkout_sdk/accounts/submitter.rb

@@ -2,10 +2,11 @@
 
 module CheckoutSdk
   module Accounts
-    # Captures evidence of the end-user's consent to onboarding.
-    #
+    # Not defined by any Accounts API onboarding schema.
+    # @deprecated Not part of any Accounts API onboarding schema; the API does not read it.
     # @!attribute ip_address
-    #   @return [String] IP address of the end-user submitting the onboarding request.
+    #   @deprecated Not defined by any Accounts API onboarding schema.
+    #   @return [String]
     class Submitter
       attr_accessor :ip_address
     end

data/lib/checkout_sdk/accounts/tax_verification.rb

@@ -2,9 +2,17 @@
 
 module CheckoutSdk
   module Accounts
+    # IRS-issued Employer Identification Number document used to verify the entity's tax identification
+    # (US variants).
     # @!attribute type
+    #   The type of IRS-issued document used for tax verification.
+    #   [Required]
     #   @return [String] {TaxVerificationType}
     # @!attribute front
+    #   The ID of the front side of the document as represented within Checkout.com systems.
+    #   [Required]
+    #   ^file_[a-z2-7]{26}$
+    #   31 characters
     #   @return [String]
     class TaxVerification
       attr_accessor :type,

data/lib/checkout_sdk/accounts/tax_verification_type.rb

@@ -2,6 +2,7 @@
 
 module CheckoutSdk
   module Accounts
+    # The document type accepted as tax verification: an IRS-issued Employer Identification Number letter.
     module TaxVerificationType
       EIN_LETTER = 'ein_letter'
     end

data/lib/checkout_sdk/accounts/update_payment_instrument_request.rb

@@ -2,12 +2,24 @@
 
 module CheckoutSdk
   module Accounts
+    # Request for PATCH /accounts/entities/{entityId}/payment-instruments/{id}
+    # (PlatformsPaymentInstrumentUpdate).
     # @!attribute label
+    #   A reference that you can use to identify the payment instrument.
+    #   [Optional]
+    #   min 1 character, max 50 characters
     #   @return [String]
     # @!attribute default
+    #   Deprecated by the API: for scheduled payouts the first payment instrument created for a currency
+    #   is used; to change it, update the payout schedule.
+    #   [Optional]
     #   @return [TrueClass, FalseClass]
     # @!attribute headers
-    #   @return [Headers]
+    #   The payment instrument ETag, as returned in the ETag header of the GET, in headers.if_match.
+    #   {AccountsClient#update_payment_instrument} sends it as the If-Match HTTP header; the API
+    #   answers 428 without it and 412 when it does not match.
+    #   [Required] by the API.
+    #   @return [CheckoutSdk::Common::Headers]
     class UpdatePaymentInstrumentRequest
       attr_accessor :label,
                     :default,

data/lib/checkout_sdk/payments/payments.rb

@@ -233,6 +233,12 @@ require 'checkout_sdk/payments/setups/blik_payment_method'
 require 'checkout_sdk/payments/setups/bacs_payment_method'
 require 'checkout_sdk/payments/setups/card_present_payment_method'
 require 'checkout_sdk/payments/setups/pay_by_bank_payment_method'
+require 'checkout_sdk/payments/setups/cash_app_action_type'
+require 'checkout_sdk/payments/setups/cash_app_payment_method'
+require 'checkout_sdk/payments/setups/payment_setup_device_client'
+require 'checkout_sdk/payments/setups/payment_setup_device_os'
+require 'checkout_sdk/payments/setups/payment_setup_payment_method_initialization'
+require 'checkout_sdk/payments/setups/payment_setup_payment_method_status'
 require 'checkout_sdk/payments/setups/stablecoin_payment_method'
 require 'checkout_sdk/payments/setups/payment_setups_client'
 

data/lib/checkout_sdk/payments/sessions/payment_methods_type.rb

@@ -2,19 +2,55 @@
 
 module CheckoutSdk
   module Payments
+    # The type of payment method that can be enabled or disabled for a payment session.
+    #
+    # This is a consolidated list covering every payment method the Flow API accepts for
+    # enabled_payment_methods / disabled_payment_methods. Constants marked deprecated are no
+    # longer part of the specification but are kept for backward compatibility.
     module PaymentMethodsType
+      ALIPAY_CN = 'alipay_cn'
+      ALIPAY_HK = 'alipay_hk'
+      ALMA = 'alma'
       APPLEPAY = 'applepay'
       BANCONTACT = 'bancontact'
+      BENEFIT = 'benefit'
+      BIZUM = 'bizum'
       CARD = 'card'
+      DANA = 'dana'
       EPS = 'eps'
+      # @deprecated No longer part of the specification.
       GIROPAY = 'giropay'
+      GCASH = 'gcash'
       GOOGLEPAY = 'googlepay'
       IDEAL = 'ideal'
+      KAKAOPAY = 'kakaopay'
+      KLARNA = 'klarna'
       KNET = 'knet'
+      MBWAY = 'mbway'
+      MOBILEPAY = 'mobilepay'
       MULTIBANCO = 'multibanco'
+      OCTOPUS = 'octopus'
       PRZELEWY24 = 'p24'
+      PAYNOW = 'paynow'
       PAYPAL = 'paypal'
+      PLAID = 'plaid'
+      QPAY = 'qpay'
+      # Fully supported by the API but deliberately unlisted in the public specification, so
+      # that merchants do not disable Remember Me en masse. Do not remove it as an unspecified
+      # value.
+      REMEMBER_ME = 'remember_me'
+      SEPA = 'sepa'
+      # @deprecated No longer part of the specification.
       SOFORT = 'sofort'
+      STCPAY = 'stcpay'
+      STORED_CARD = 'stored_card'
+      TABBY = 'tabby'
+      TAMARA = 'tamara'
+      TNG = 'tng'
+      TRUEMONEY = 'truemoney'
+      TWINT = 'twint'
+      VIPPS = 'vipps'
+      WECHATPAY = 'wechatpay'
     end
   end
 end

data/lib/checkout_sdk/payments/setups/cash_app_action_type.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Payments
+    # The type of the next available action for the Cash App Pay payment method on a
+    # Payment Setup. Maps swagger `CashApp.action.type`.
+    module CashAppActionType
+      REDIRECT = 'redirect'
+    end
+  end
+end

data/lib/checkout_sdk/payments/setups/cash_app_payment_method.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Payments
+    # The Cash App payment method's details and configuration on a Payment Setup.
+    # Maps swagger `CashApp`. Sent under the `payment_methods.cashapp` key (one lowercase word,
+    # not `cash_app`).
+    #
+    # The Payment Setup request is a Hash, and a Hash request is sent as is, so do not nest an
+    # instance of this class in it directly: it would not be serialized. Pass a Hash with these keys,
+    # or convert an instance first:
+    #   cash_app = CheckoutSdk::Payments::CashAppPaymentMethod.new
+    #   cash_app.initialization = 'enabled'
+    #   cash_app.customer_profile_sharing = true
+    #   request[:payment_methods] = { cashapp: CheckoutSdk::JsonSerializer.to_custom_hash(cash_app) }
+    # Responses are read with dot access, for example response.payment_methods.cashapp.action.redirect_url.
+    class CashAppPaymentMethod
+      # The payment method status.
+      # [Optional]
+      # Read only.
+      # Enum: "unavailable" "action_required" "ready" "initialization_required" "invalid"
+      # @return [String] One of {PaymentSetupPaymentMethodStatus}.
+      attr_accessor :status
+
+      # The list of error codes or indicators that highlight missing or invalid information.
+      # [Optional]
+      # Read only.
+      # @return [Array(String)]
+      attr_accessor :flags
+
+      # The initialization state of the payment method.
+      # When you create a Payment Setup, this defaults to `disabled`.
+      # [Optional]
+      # Default: "disabled"
+      # Enum: "disabled" "enabled"
+      # @return [String] One of {PaymentSetupPaymentMethodInitialization}.
+      attr_accessor :initialization
+
+      # Indicates whether the customer consents to share their Cash App customer profile with Checkout.com.
+      # [Optional]
+      # @return [TrueClass, FalseClass]
+      attr_accessor :customer_profile_sharing
+
+      # The customer's Cash App profile that they consented to share. Included in the response when
+      # `customer_profile_sharing` is enabled.
+      # Cash App releases this profile only once. It's present in the first successful response when you
+      # get the Payment Setup after the customer authorizes the payment. Every subsequent response omits it.
+      # [Optional]
+      # Read only.
+      # Keys (all strings, all optional):
+      # - `customer_id`: Cash App's identifier for the customer. This is not a Checkout.com customer identifier.
+      # - `cashtag`: The customer's $Cashtag.
+      # - `reference_id`: Cash App's reference for the customer profile.
+      # - `full_name`: The customer's full name.
+      # - `given_name`: The customer's given name.
+      # - `middle_name`: The customer's middle name.
+      # - `family_name`: The customer's family name.
+      # - `suffix`: The suffix of the customer's name.
+      # - `birth_date`: The customer's date of birth. Format: date (the API example carries a time part,
+      #   so the value is kept as a string).
+      # - `address` (Hash): The customer's address, with Cash App's own key names (not the Checkout.com
+      #   common address): `address_line_1` (the first line of the address), `address_line_2` (the second
+      #   line of the address), `address_line_3` (the third line of the address), `locality` (the address
+      #   locality, such as the city or town), `sublocality` (the address sublocality, such as the district
+      #   or neighborhood), `administrative_district_level_1` (the address's top-level administrative
+      #   district, such as the state or province), `postal_code` (the postal or zip code) and `country`
+      #   (the address country, in ISO 3166-1 alpha-2 format, max 2 characters).
+      # - `phone_number`: The customer's phone number.
+      # - `email_address`: The customer's email address.
+      # - `customer_since`: The date and time the customer's Cash App account was created.
+      #   Format: date-time (kept as a string).
+      # @return [Hash]
+      attr_accessor :customer_profile
+
+      # A reference for the Cash App Pay transaction, returned by the provider.
+      # [Optional]
+      # Read only.
+      # max 80 characters
+      # @return [String]
+      attr_accessor :reference
+
+      # The next available action for the payment method.
+      # [Optional]
+      # Read only.
+      # Keys:
+      # - `type` (String): The type of action. One of {CashAppActionType}.
+      # - `redirect_url` (String): The URL to redirect the customer to so they can authorize the payment
+      #   with Cash App. Format: uri
+      # @return [Hash]
+      attr_accessor :action
+    end
+  end
+end

data/lib/checkout_sdk/payments/setups/payment_setup_device_client.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Payments
+    # The type of client the customer uses to initiate the payment.
+    # Maps swagger `PaymentSetup.customer.device.client`.
+    module PaymentSetupDeviceClient
+      WEB = 'web'
+      MOBILE_WEB = 'mobile_web'
+      APP = 'app'
+    end
+  end
+end

data/lib/checkout_sdk/payments/setups/payment_setup_device_os.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Payments
+    # The operating system of the customer's device.
+    # Maps swagger `PaymentSetup.customer.device.os`.
+    module PaymentSetupDeviceOs
+      ANDROID = 'android'
+      IOS = 'ios'
+    end
+  end
+end

data/lib/checkout_sdk/payments/setups/payment_setup_payment_method_initialization.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Payments
+    # The initialization state of a payment method on a Payment Setup.
+    # Maps swagger `PaymentMethodInitialization.initialization`.
+    module PaymentSetupPaymentMethodInitialization
+      DISABLED = 'disabled'
+      ENABLED = 'enabled'
+    end
+  end
+end

data/lib/checkout_sdk/payments/setups/payment_setup_payment_method_status.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Payments
+    # The payment method status on a Payment Setup.
+    # Maps swagger `PaymentMethodStatus`.
+    module PaymentSetupPaymentMethodStatus
+      UNAVAILABLE = 'unavailable'
+      ACTION_REQUIRED = 'action_required'
+      READY = 'ready'
+      INITIALIZATION_REQUIRED = 'initialization_required'
+      INVALID = 'invalid'
+    end
+  end
+end