feature/INT-1714 - new payout destination types in payments (network token)

lib/checkout_sdk/common/account_holder.rb

@@ -2,37 +2,114 @@
 
 module CheckoutSdk
   module Common
+    # The account holder of a payment source, an instrument, or a payout or unreferenced refund destination.
+    # This class is shared by many positions; the per-position notes below cover the card payout, bank payout
+    # and unreferenced refund destinations. Each position only accepts the keys its schema declares, so leave
+    # the other properties unset.
+    # - Card payout card and network_token destinations: type, first_name, middle_name, last_name,
+    #   billing_address, phone, identification, email, date_of_birth, country_of_birth.
+    # - Card payout id and token destinations: type, first_name, middle_name, last_name, company_name.
+    # - Bank payout bank_account destination: type, first_name, last_name, company_name, tax_id,
+    #   date_of_birth, country_of_birth, residential_status, billing_address, phone, identification.
+    # - Unreferenced refund destinations: as the card payout card and network_token destinations.
+    #
     # @!attribute type
+    #   The type of account holder.
+    #   [Required] for payout and unreferenced refund destinations (when the account holder is sent)
+    #   Enum: "individual" "corporate" "government"
     #   @return [String] {AccountHolderType}
     # @!attribute full_name
+    #   The account holder's full name.
+    #   [Optional]
+    #   @deprecated Not in the request schema of any account holder. Still returned in the PayPal payment
+    #     details source account_holder.
+    #     Retained for backwards compatibility and will be removed in the next major version. There is no
+    #     replacement.
     #   @return [String]
     # @!attribute first_name
+    #   The account holder's legal first name. The combination of first_name, middle_name and last_name
+    #   should exceed 3 letters in length for card payouts. A single character or all non-alphabetic
+    #   characters return a field validation error.
+    #   [Required] for individual account holders in card payouts, bank payouts and the unreferenced refund
+    #   card and network_token destinations; [Optional] for the unreferenced refund id and token
+    #   destinations. In the card payout id and token destinations it is not required if the first name is
+    #   already stored with the token or instrument.
+    #   max 50 characters (card payouts and unreferenced refunds)
     #   @return [String]
     # @!attribute middle_name
+    #   The account holder's middle name.
+    #   [Optional] Card payouts and unreferenced refunds only.
+    #   max 50 characters
     #   @return [String]
     # @!attribute last_name
+    #   The account holder's legal last name. The combination of first_name, middle_name and last_name
+    #   should exceed 3 letters in length for card payouts. A single character or all non-alphabetic
+    #   characters return a field validation error.
+    #   [Required] for individual account holders in card payouts, bank payouts and the unreferenced refund
+    #   card and network_token destinations; [Optional] for the unreferenced refund id and token
+    #   destinations. In the card payout id and token destinations it is not required if the last name is
+    #   already stored with the token or instrument.
+    #   max 50 characters (card payouts and unreferenced refunds)
     #   @return [String]
     # @!attribute email
+    #   The account holder's email address.
+    #   [Optional] Card payout card and network_token destinations and unreferenced refunds only.
+    #   max 255 characters
     #   @return [String]
     # @!attribute gender
+    #   The account holder's gender.
+    #   [Optional]
+    #   @deprecated Not in the request schema of any account holder. Still returned in the Klarna payment
+    #     details source account_holder.
+    #     Retained for backwards compatibility and will be removed in the next major version. There is no
+    #     replacement.
     #   @return [String]
     # @!attribute company_name
+    #   The legal name of the corporate or government account holder. A single character or all
+    #   non-alphabetic characters return a field validation error.
+    #   [Required] for corporate and government payout and unreferenced refund destinations
+    #   max 50 characters (card payouts and unreferenced refunds)
     #   @return [String]
     # @!attribute tax_id
+    #   The legal account holder's tax number or reference.
+    #   [Optional] Bank payouts only.
     #   @return [String]
     # @!attribute date_of_birth
+    #   The account holder's date of birth, in the format YYYY-MM-DD. Individual account holders only.
+    #   [Optional]
+    #   10 characters (card payouts and unreferenced refunds)
     #   @return [String]
     # @!attribute country_of_birth
-    #   @return [Country]
+    #   The account holder's country of birth, as a two-letter ISO country code. Individual account holders
+    #   only.
+    #   [Optional]
+    #   2 characters
+    #   @return [String] {Country}
     # @!attribute residential_status
+    #   The account holder's residential status.
+    #   [Optional] Bank payouts only.
+    #   Enum: "resident" "non_resident"
     #   @return [String] {ResidentialStatusType}
     # @!attribute billing_address
+    #   The account holder's billing address. For card payouts and unreferenced refunds, it is required if
+    #   your company is incorporated in the United States.
+    #   [Required] for individual bank payout destinations, [Optional] otherwise
     #   @return [Address]
     # @!attribute phone
+    #   The account holder's phone number.
+    #   [Optional] Not part of the card payout id and token destinations, nor of the corporate and
+    #   government bank payout destinations.
     #   @return [Phone]
     # @!attribute identification
+    #   The account holder's identification. Providing identification details for the payout recipient
+    #   increases the likelihood of a successful payout.
+    #   [Optional] Not part of the card payout id and token destinations, nor of the corporate and
+    #   government bank payout destinations.
     #   @return [AccountHolderIdentification]
     # @!attribute account_name_inquiry
+    #   Whether the ANI (account name inquiry) check should be performed with the scheme (Visa or
+    #   Mastercard). Payment sources only.
+    #   [Optional] Not declared by the payout or unreferenced refund destination schemas.
     #   @return [Boolean]
     class AccountHolder
       attr_accessor :type,

lib/checkout_sdk/common/account_holder_identification.rb

@@ -2,13 +2,34 @@
 
 module CheckoutSdk
   module Common
+    # The identification of an account holder or a sender. Shared by the card payout, bank payout,
+    # unreferenced refund and regular payment positions.
+    #
     # @!attribute type
+    #   The type of identification.
+    #   [Required] for card payout and unreferenced refund account holders and card payout senders,
+    #   [Optional] for bank payout and regular payment senders and bank payout account holders
+    #   Enum: "passport" "driving_license" "national_id" "company_registration" "tax_id" (card payouts and
+    #   unreferenced refunds); "passport" "driving_licence" "national_id" (bank payout and regular payment
+    #   senders)
     #   @return [String] {AccountHolderIdentificationType}
     # @!attribute number
+    #   The identification number.
+    #   [Required] for card payout and unreferenced refund account holders and card payout senders,
+    #   [Optional] for bank payout and regular payment senders and bank payout account holders
+    #   max 25 characters (card payout and unreferenced refund account holders)
     #   @return [String]
     # @!attribute issuing_country
+    #   If applicable, the country that issued the identification, as a two-letter ISO country code.
+    #   Providing it increases the likelihood of a successful identity verification.
+    #   [Optional]
+    #   2 characters (card payouts and unreferenced refunds)
     #   @return [String] {Country}
     # @!attribute date_of_expiry
+    #   If applicable, the expiration date of the identification, in the format YYYY-MM-DD.
+    #   Card payouts and unreferenced refunds only.
+    #   [Optional]
+    #   10 characters
     #   @return [String]
     class AccountHolderIdentification
       attr_accessor :type,

lib/checkout_sdk/common/common.rb

@@ -9,6 +9,7 @@
 require 'checkout_sdk/common/country'
 require 'checkout_sdk/common/account_holder_identification_type'
 require 'checkout_sdk/common/account_holder_type'
+require 'checkout_sdk/common/residential_status_type'
 require 'checkout_sdk/common/instrument_type'
 require 'checkout_sdk/common/bank_details'
 require 'checkout_sdk/common/payment_source_type'

lib/checkout_sdk/common/residential_status_type.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Common
+    # The account holder's residential status (bank payout and refund destination account holders).
+    module ResidentialStatusType
+      RESIDENT = 'resident'
+      NON_RESIDENT = 'non_resident'
+    end
+  end
+end

lib/checkout_sdk/payments/card_payout_item.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Payments
+    # A line item of a card payout.
+    #
+    # @!attribute type
+    #   The item type. For example, physical or digital.
+    #   This field is used to provide item level metadata where applicable.
+    #   [Optional]
+    #   Enum: "digital" "physical"
+    #   @return [String] {ProductItemType}
+    # @!attribute sub_type
+    #   The digital item type.
+    #   If type is set to digital, this field is required.
+    #   [Optional]
+    #   Enum: "blockchain" "cbdc" "cryptocurrency" "nft" "stablecoin"
+    #   @return [String] {ProductSubType}
+    class CardPayoutItem
+      attr_accessor :type,
+                    :sub_type
+    end
+  end
+end

lib/checkout_sdk/payments/card_payout_processing.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Payments
+    # Information related to the processing of a card payout.
+    #
+    # @!attribute affiliate_id
+    #   The unique identifier for Visa-registered ramp providers.
+    #   Must only contain alphanumeric characters.
+    #   If you're a Visa-registered ramp provider operating with affiliates, this field is required.
+    #   [Optional]
+    #   ^[a-zA-Z0-9]{1,15}$
+    #   max 15 characters
+    #   @return [String]
+    # @!attribute affiliate_url
+    #   The affiliate URL.
+    #   If you're a Visa-registered ramp provider operating with affiliates, this field is required.
+    #   [Optional]
+    #   @return [String]
+    # @!attribute processing_speed
+    #   The speed at which the payout is processed.
+    #   Only applicable for unreferenced refunds.
+    #   [Optional]
+    #   Enum: "fast"
+    #   @return [String]
+    # @!attribute purchase_country
+    #   The two-letter ISO country code of the purchase country.
+    #   If you're a Visa-registered ramp provider operating with affiliates, this field is required.
+    #   [Optional]
+    #   max 2 characters
+    #   @return [String] {CheckoutSdk::Common::Country}
+    class CardPayoutProcessing
+      attr_accessor :affiliate_id,
+                    :affiliate_url,
+                    :processing_speed,
+                    :purchase_country
+    end
+  end
+end

lib/checkout_sdk/payments/destination/bank_account_destination.rb

@@ -2,25 +2,54 @@
 
 module CheckoutSdk
   module Payments
+    # A bank account payout destination (bank payout, type bank_account).
+    #
     # @!attribute account_type
+    #   The type of the bank account. Note that some beneficiary banks do not accept payouts to
+    #   savings accounts.
+    #   [Required]
+    #   Enum: "savings" "current" "cash"
     #   @return [String] {CheckoutSdk::Common::AccountType}
     # @!attribute account_number
+    #   Number (which can contain letters) that identifies the local account.
+    #   [Optional]
     #   @return [String]
     # @!attribute bank_code
+    #   Code that identifies the bank. Also referred as Routing Number in the United States.
+    #   [Optional]
     #   @return [String]
     # @!attribute branch_code
+    #   Code that identifies the bank branch.
+    #   [Optional]
     #   @return [String]
     # @!attribute iban
+    #   Internationally agreed standard for identifying bank accounts. Lengths vary per destination_country.
+    #   [Optional]
     #   @return [String]
     # @!attribute bban
+    #   The combination of bank code and/or branch code and account number.
+    #   [Optional]
     #   @return [String]
     # @!attribute swift_bic
+    #   8 or 11 character code which identifies the bank or bank branch.
+    #   [Optional]
     #   @return [String]
     # @!attribute country
+    #   The two-letter ISO country code of where the account is based. Note that not all countries
+    #   are available.
+    #   [Required]
+    #   2 characters
     #   @return [String] {CheckoutSdk::Common::Country}
     # @!attribute account_holder
+    #   The account holder details.
+    #   [Optional]
     #   @return [CheckoutSdk::Common::AccountHolder]
     # @!attribute bank
+    #   The bank details.
+    #   [Optional]
+    #   @deprecated Not in the request schema of the bank account payout destination; bank only exists on the
+    #     Instruments bank account schemas. Retained for backwards compatibility and will be removed in the
+    #     next major version. There is no replacement.
     #   @return [CheckoutSdk::Common::BankDetails]
     class BankAccountDestination < Destination
       attr_accessor :account_type,

lib/checkout_sdk/payments/destination/card_destination.rb

@@ -2,13 +2,33 @@
 
 module CheckoutSdk
   module Payments
+    # A card payout destination. Also the card destination of an unreferenced refund.
+    #
     # @!attribute number
+    #   The card number.
+    #   You can encrypt this field by using the Cko-Encryption-Key-Id and Cko-Encrypted-Properties headers.
+    #   [Required]
+    #   max 19 characters
     #   @return [String]
     # @!attribute expiry_month
+    #   The card's expiration month.
+    #   [Required]
+    #   1 to 2 digits
     #   @return [Integer]
     # @!attribute expiry_year
+    #   The card's expiration year.
+    #   [Required]
+    #   4 digits
     #   @return [Integer]
     # @!attribute account_holder
+    #   The payout or unreferenced refund destination account holder.
+    #   [Required]
+    #   The type discriminates the accepted keys:
+    #   - individual: type, first_name, middle_name, last_name, billing_address, phone,
+    #     identification, email, date_of_birth, country_of_birth
+    #   - corporate, government: type, company_name, billing_address, phone, identification, email
+    #   Other AccountHolder properties (full_name, gender, tax_id, residential_status,
+    #   account_name_inquiry) are not part of this position.
     #   @return [CheckoutSdk::Common::AccountHolder]
     class CardDestination < Destination
       attr_accessor :number,

lib/checkout_sdk/payments/destination/destination.rb

@@ -2,7 +2,12 @@
 
 module CheckoutSdk
   module Payments
+    # The destination of the payout, or of the unreferenced refund.
+    # You can encrypt this field by using the Cko-Encryption-Key-Id and Cko-Encrypted-Properties headers.
+    #
     # @!attribute type
+    #   The payout or unreferenced refund destination type. Set by each subclass.
+    #   [Required]
     #   @return [String] {DestinationType}
     class Destination
       attr_reader :type

lib/checkout_sdk/payments/destination/destination_type.rb

@@ -2,11 +2,18 @@
 
 module CheckoutSdk
   module Payments
+    # The payout destination type.
+    #
+    # Three destination discriminators share these values:
+    # - card payout destination: card, network_token, id, token
+    # - unreferenced refund destination: card, network_token, id, token
+    # - bank payout destination: id, bank_account
     module DestinationType
       CARD = 'card'
       ID = 'id'
       TOKEN = 'token'
       BANK_ACCOUNT = 'bank_account'
+      NETWORK_TOKEN = 'network_token'
     end
   end
 end

lib/checkout_sdk/payments/destination/id_destination.rb

@@ -2,9 +2,25 @@
 
 module CheckoutSdk
   module Payments
+    # A payment instrument payout destination. Used by card payouts, bank payouts and unreferenced refunds.
+    #
     # @!attribute id
+    #   The payment source ID. This will be an ID with the prefix `src_`.
+    #   [Required]
+    #   ^(src)_(\w{26})$
+    #   30 characters (card payout and unreferenced refund)
     #   @return [String]
     # @!attribute account_holder
+    #   The payout or unreferenced refund destination account holder.
+    #   [Required] for card payouts, [Optional] for unreferenced refunds.
+    #   Not declared by the bank payout id destination.
+    #   The type discriminates the accepted keys. For card payouts:
+    #   - individual: type, first_name, middle_name, last_name
+    #   - corporate, government: type, company_name
+    #   For unreferenced refunds, where no name is required:
+    #   - individual: type, first_name, middle_name, last_name, billing_address, phone,
+    #     identification, email, date_of_birth, country_of_birth
+    #   - corporate, government: type, company_name, billing_address, phone, identification, email
     #   @return [CheckoutSdk::Common::AccountHolder]
     class IdDestination < Destination
       attr_accessor :id,