feature/INT-1675 - BACS Direct Debit notifications + refactor

lib/checkout_sdk/apm/apm.rb

@@ -9,3 +9,8 @@
 require 'checkout_sdk/apm/previous/klarna/klarna_client'
 require 'checkout_sdk/apm/previous/sepa/sepa_client'
 require 'checkout_sdk/apm/ideal/ideal_client'
+
+# Bacs
+require 'checkout_sdk/apm/bacs/bacs_notification_type'
+require 'checkout_sdk/apm/bacs/bacs_notification_request'
+require 'checkout_sdk/apm/bacs/bacs_client'

lib/checkout_sdk/apm/bacs/bacs_client.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Apm
+    # Bacs Direct Debit client.
+    class BacsClient < Client
+      APMS = 'apms'
+      BACS_NOTIFICATIONS = 'bacs/notifications'
+      private_constant :APMS, :BACS_NOTIFICATIONS
+
+      # @param [ApiClient] api_client
+      # @param [CheckoutConfiguration] configuration
+      def initialize(api_client, configuration)
+        super(api_client, configuration, CheckoutSdk::AuthorizationType::SECRET_KEY)
+      end
+
+      # Sends a Bacs Direct Debit pre-notification (advance notice) to a payer ahead
+      # of collecting funds from their account.
+      #
+      # @param [Hash, BacsNotificationRequest] bacs_notification_request
+      # @return [Hash] the BacsNotificationResponse, carrying event_id.
+      def send_notification(bacs_notification_request)
+        api_client.invoke_post(build_path(APMS, BACS_NOTIFICATIONS),
+                               sdk_authorization,
+                               bacs_notification_request)
+      end
+    end
+  end
+end

lib/checkout_sdk/apm/bacs/bacs_notification_request.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Apm
+    # Bacs Direct Debit notification request.
+    #
+    # @!attribute source_id
+    #   @return [String] The ID of the Bacs Direct Debit instrument to notify
+    #     against. [Required] Pattern: ^(src)_(\w{26})$
+    # @!attribute notification_type
+    #   @return [String] {BacsNotificationType} The type of pre-notification being
+    #     sent to the payer. [Required]
+    # @!attribute collection_date
+    #   @return [String] The date the funds will be collected from the payer's
+    #     account, in the format yyyy-MM-dd. [Required]
+    #     Format: date - pass a yyyy-MM-dd String, not a DateTime.
+    # @!attribute amount
+    #   @return [Integer] The amount to be collected, in the currency's minor unit.
+    #     [Required] min 1
+    # @!attribute currency
+    #   @return [String] {CheckoutSdk::Common::Currency} The three-letter ISO 4217
+    #     currency code of the collection. [Required] min 3 characters,
+    #     max 3 characters.
+    # @!attribute billing_descriptor
+    #   @return [String] The billing descriptor that appears on the payer's bank
+    #     statement. [Required] max 25 characters.
+    # @!attribute customer_email
+    #   @return [String] The email address of the payer that the pre-notification is
+    #     sent to. [Required] Format: email
+    # @!attribute support_email
+    #   @return [String] The support email address included in the pre-notification.
+    #     [Required] Format: email
+    # @!attribute reference
+    #   @return [String] A reference you can use to identify the collection.
+    #     [Optional] max 50 characters.
+    # @!attribute support_phone
+    #   @return [String] The support phone number included in the pre-notification,
+    #     in E.164 format. [Optional]
+    class BacsNotificationRequest
+      attr_accessor :source_id,
+                    :notification_type,
+                    :collection_date,
+                    :amount,
+                    :currency,
+                    :billing_descriptor,
+                    :customer_email,
+                    :support_email,
+                    :reference,
+                    :support_phone
+    end
+  end
+end

lib/checkout_sdk/apm/bacs/bacs_notification_type.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Apm
+    # The type of pre-notification being sent to the payer.
+    module BacsNotificationType
+      ADVANCE_NOTICE = 'advance_notice'
+    end
+  end
+end

lib/checkout_sdk/checkout_api.rb

@@ -73,6 +73,8 @@ module CheckoutSdk
   #   @return [CheckoutSdk::Identities::IdentityVerification::IdentityVerificationClient]
   # @!attribute face_authentication
   #   @return [CheckoutSdk::Identities::FaceAuthentication::FaceAuthenticationClient]
+  # @!attribute bacs
+  #   @return [CheckoutSdk::Apm::BacsClient]
   # @!attribute apple_pay
   #   @return [CheckoutSdk::Payments::ApplePayClient]
   # @!attribute google_pay
@@ -91,6 +93,7 @@ class CheckoutApi
                 :sessions,
                 :tokens,
                 :ideal,
+                :bacs,
                 :accounts,
                 :workflows,
                 :risk,
@@ -131,6 +134,7 @@ def initialize(configuration)
       @sessions = CheckoutSdk::Sessions::SessionsClient.new api_client, configuration
       @tokens = CheckoutSdk::Tokens::TokensClient.new api_client, configuration
       @ideal = CheckoutSdk::Apm::IdealClient.new api_client, configuration
+      @bacs = CheckoutSdk::Apm::BacsClient.new api_client, configuration
       @workflows = CheckoutSdk::Workflows::WorkflowsClient.new api_client, configuration
       @accounts = CheckoutSdk::Accounts::AccountsClient.new(api_client, files_client(configuration), configuration)
       @risk = CheckoutSdk::Risk::RiskClient.new api_client, configuration

lib/checkout_sdk/common/account_holder_type.rb

@@ -2,9 +2,25 @@
 
 module CheckoutSdk
   module Common
+    # The type of account holder.
+    #
+    # For stored instruments use {CheckoutSdk::Instruments::InstrumentAccountHolderType},
+    # whose schemas declare individual and corporate only.
     module AccountHolderType
       INDIVIDUAL = 'individual'
       CORPORATE = 'corporate'
+
+      # Declared by the account-holder positions (AccountHolder, AccountHolderAch,
+      # PaymentSetupAccountHolder, RefundDestinationAccountHolder and the card-payout
+      # destination and sender) but **not** by any sender schema -
+      # PaymentRequestSender, PayoutSender, PaymentDetailsResponseSender and
+      # PaymentInterfacesSender all omit it. Do not send it as a sender type.
+      GOVERNMENT = 'government'
+
+      # Declared only by the payment and payout *sender* schemas
+      # (PaymentRequestSender, PayoutSender, PaymentDetailsResponseSender), never by
+      # an account-holder position. Retained rather than removed because removal is
+      # breaking; prefer the sender-specific type where one exists.
       INSTRUMENT = 'instrument'
     end
   end

lib/checkout_sdk/common/customer_request.rb

@@ -2,18 +2,30 @@
 
 module CheckoutSdk
   module Common
+    # The customer's details.
+    #
+    # This type serves two positions with different property sets. The payments
+    # position (swagger `CustomerRequest`) declares all six properties below. The
+    # instrument position (swagger `StoreCustomerInstrumentRequest`, used by
+    # {CheckoutSdk::Instruments::InstrumentBacs}, {CheckoutSdk::Instruments::InstrumentSepa}
+    # and {CheckoutSdk::Instruments::InstrumentAch}) declares every property except
+    # tax_number - do not send tax_number when storing an instrument.
+    #
     # @!attribute id
     #   @return [String]
     # @!attribute email
     #   @return [String]
     # @!attribute name
-    #   @return [String]
+    #   @return [String] Only sets the name for *new* customers.
     # @!attribute tax_number
-    #   @return [String]
+    #   @return [String] Payments position only. Not declared by
+    #     StoreCustomerInstrumentRequest.
     # @!attribute phone
     #   @return [Phone]
     # @!attribute default
-    #   @return [TrueClass, FalseClass]
+    #   @return [TrueClass, FalseClass] If true, this instrument becomes the default
+    #     for the customer. An instrument is automatically the default when the
+    #     request creates a new customer.
     class CustomerRequest
       attr_accessor :id,
                     :email,

lib/checkout_sdk/common/instrument_type.rb

@@ -2,11 +2,19 @@
 
 module CheckoutSdk
   module Common
+    # The type of a payment instrument.
     module InstrumentType
       BANK_ACCOUNT = 'bank_account'
       TOKEN = 'token'
       CARD = 'card'
       SEPA = 'sepa'
+
+      # Current API (NAS) only. The previous API (ABC) instrument schemas declare
+      # neither of these, so do not use them with a previous-platform client.
+      ACH = 'ach'
+      BACS = 'bacs'
+
+      # Previous API (ABC) only. Not declared by any current-API instrument schema.
       CARD_TOKEN = 'card_token'
     end
   end

lib/checkout_sdk/common/payment_source_type.rb

@@ -2,6 +2,19 @@
 
 module CheckoutSdk
   module Common
+    # The type of a payment source or destination.
+    #
+    # This module is shared by the current API (NAS) and the previous API (ABC),
+    # which is still actively maintained. These 22 values are declared by neither
+    # `PaymentRequestSourceType` nor `PaymentDetailsResponseSourceType` in the
+    # current specification and are **previous API (ABC) only**:
+    #
+    #   afterpay, alipay, applepay, baloto, bank_account, benefit, benefitpay,
+    #   boleto, cvconnect, dlocal, giropay, googlepay, illicado, oxxo, pagofacil,
+    #   poli, postfinance, provider_token, rapipago, sofort, tabby, trustly
+    #
+    # Use them only with a previous-platform client. Every other value below is
+    # current-API.
     module PaymentSourceType
       CARD = 'card'
       ID = 'id'
@@ -54,10 +67,16 @@ module PaymentSourceType
       ILLICADO = 'illicado'
       SEPA = 'sepa'
       ACH = 'ach'
+      BACS = 'bacs'
       BIZUM = 'bizum'
       OCTOPUS = 'octopus'
       PLAID = 'plaid'
       SEQURA = 'sequra'
+      MOBILEPAY = 'mobilepay'
+      PAYNOW = 'paynow'
+      SWISH = 'swish'
+      TWINT = 'twint'
+      VIPPS = 'vipps'
       TABBY = 'tabby'
       APPLEPAY = 'applepay'
       GOOGLEPAY = 'googlepay'

lib/checkout_sdk/instruments/ach_account_type.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Instruments
+    # The type of Direct Debit account on an ACH instrument.
+    #
+    # The ACH instrument schemas declare savings and checking only. The ACH payment
+    # source additionally declares cash - see {CheckoutSdk::Common::AccountType}.
+    module AchAccountType
+      SAVINGS = 'savings'
+      CHECKING = 'checking'
+    end
+  end
+end

lib/checkout_sdk/instruments/bacs_payment_type.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Instruments
+    # The type of payment on a Bacs Direct Debit instrument.
+    #
+    # Declared capitalized by the Bacs instrument schemas, unlike {SepaPaymentType}
+    # which declares the same two concepts lowercase. The casing is not
+    # interchangeable and must not be unified.
+    module BacsPaymentType
+      RECURRING = 'Recurring'
+      REGULAR = 'Regular'
+    end
+  end
+end

lib/checkout_sdk/instruments/create/create_ach_account_holder.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Instruments
+    # The account holder details of an ACH instrument being stored.
+    #
+    # The specification lists all four properties in the schema's required array,
+    # while the individual field descriptions make them conditional on type
+    # ("Required for individual account holder type" / "Required for corporate
+    # account holder type"). The two readings contradict each other; send the pair
+    # that matches your type value.
+    #
+    # @!attribute first_name
+    #   @return [String] First name. Required for individual account holder type.
+    # @!attribute last_name
+    #   @return [String] Last name. Required for individual account holder type.
+    # @!attribute company_name
+    #   @return [String] Company name. Required for corporate account holder type.
+    # @!attribute type
+    #   @return [String] {InstrumentAccountHolderType} Account holder type.
+    #     [Required]
+    class CreateAchAccountHolder
+      attr_accessor :first_name,
+                    :last_name,
+                    :company_name,
+                    :type
+    end
+  end
+end

lib/checkout_sdk/instruments/create/create_ach_instrument_data.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Instruments
+    # The details of the bank account of an ACH instrument being stored.
+    #
+    # @!attribute account_type
+    #   @return [String] {AchAccountType} The type of Direct Debit account,
+    #     savings or checking. [Required]
+    # @!attribute account_number
+    #   @return [String] The account number of the Direct Debit account.
+    #     [Required] min 4 characters, max 17 characters.
+    # @!attribute bank_code
+    #   @return [String] The bank code of the Direct Debit account.
+    #     [Required] min 8 characters, max 9 characters.
+    # @!attribute currency
+    #   @return [String] {CheckoutSdk::Common::Currency} The currency of the account.
+    #     [Required] min 3 characters, max 3 characters.
+    # @!attribute country
+    #   @return [String] {CheckoutSdk::Common::Country} The country of the account.
+    #     [Required] min 2 characters, max 2 characters.
+    class CreateAchInstrumentData
+      attr_accessor :account_type,
+                    :account_number,
+                    :bank_code,
+                    :currency,
+                    :country
+    end
+  end
+end

lib/checkout_sdk/instruments/create/create_bacs_account_holder.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Instruments
+    # The account holder details of a Bacs Direct Debit instrument being stored.
+    #
+    # The store shape declares three properties only. The update and retrieve shapes
+    # additionally declare company_name and type - see
+    # {UpdateBacsAccountHolder}.
+    #
+    # @!attribute first_name
+    #   @return [String] The first name of the account holder. [Required]
+    # @!attribute last_name
+    #   @return [String] The last name of the account holder. [Required]
+    # @!attribute billing_address
+    #   @return [CreateBacsBillingAddress] The billing address of the account
+    #     holder. [Required]
+    class CreateBacsAccountHolder
+      attr_accessor :first_name,
+                    :last_name,
+                    :billing_address
+    end
+  end
+end

lib/checkout_sdk/instruments/create/create_bacs_billing_address.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Instruments
+    # The billing address of the account holder of a Bacs Direct Debit instrument
+    # being stored.
+    #
+    # @!attribute address_line1
+    #   @return [String] The first line of the address. [Optional] max 200 characters.
+    # @!attribute address_line2
+    #   @return [String] The street number. If no number, pass "w/n".
+    #     [Optional] max 10 characters.
+    # @!attribute city
+    #   @return [String] The address city. [Optional] max 35 characters.
+    #     Note the update variant allows max 50.
+    # @!attribute zip
+    #   @return [String] The address zip/postal code. [Optional] max 16 characters.
+    #     Note the update variant allows max 50.
+    # @!attribute country
+    #   @return [String] {CheckoutSdk::Common::Country} The two-letter ISO country
+    #     code of the address. [Required] min 2 characters, max 2 characters.
+    class CreateBacsBillingAddress
+      attr_accessor :address_line1,
+                    :address_line2,
+                    :city,
+                    :zip,
+                    :country
+    end
+  end
+end