gocardless_pro 2.7.0 → 2.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 88c2d215e0c85d03f6564b77c2ea9815a33b080544cf2987030407b46b54472f
-  data.tar.gz: f0f9af3de5d443b2fb94bc39c64fd6478b86328e50a9283bdcaabe622e5013c8
+  metadata.gz: f0dcc61e6ad974bee34243805fb1a45bec38c51db4ebf9bbdc6ee240ca96e782
+  data.tar.gz: 9ef2aabea6263516ba9cee0e1bb1efa682f59f9ede69c880a20d9d73a2b8c820
 SHA512:
-  metadata.gz: '08ebee113a782abd51bd043cf41684b0a025ce6e25a5105c724d1b26663e645484c69f6c261bb5ad0f34f0e24b5b8688b22a40689e7144497a958e699a0a599e'
-  data.tar.gz: efc1fcf7ce492542fe13c455333e9a0846d6ce2c0b96e18aefc5f92790d3535618949b4f8ae1b74176e07505f182ad2936d1d9811bf784f8469d8035bbb0b43a
+  metadata.gz: 116e36fef2b4f6bec63d06f1a792fb240537bd2c1ed23b6684409367c24cb6148f21d7f52a14a7710642ba0e01cc5011c4f72d9cbc1c83918fc128759997cf96
+  data.tar.gz: cc8ad6e8119952e90cecc405a82a38d5631e06f42c2ea48cf03127526e644927c5f316be27968f9b3b466622c57b87a9c2842cd6fca9da7ecff06dae4d453bed

data/lib/gocardless_pro.rb

@@ -58,6 +58,12 @@ require_relative 'gocardless_pro/services/events_service'
 require_relative 'gocardless_pro/resources/mandate'
 require_relative 'gocardless_pro/services/mandates_service'
 
+require_relative 'gocardless_pro/resources/mandate_import'
+require_relative 'gocardless_pro/services/mandate_imports_service'
+
+require_relative 'gocardless_pro/resources/mandate_import_entry'
+require_relative 'gocardless_pro/services/mandate_import_entries_service'
+
 require_relative 'gocardless_pro/resources/mandate_pdf'
 require_relative 'gocardless_pro/services/mandate_pdfs_service'
 

data/lib/gocardless_pro/client.rb

@@ -38,6 +38,16 @@ module GoCardlessPro
       @mandates ||= Services::MandatesService.new(@api_service)
     end
 
+    # Access to the service for mandate_import to make API calls
+    def mandate_imports
+      @mandate_imports ||= Services::MandateImportsService.new(@api_service)
+    end
+
+    # Access to the service for mandate_import_entry to make API calls
+    def mandate_import_entries
+      @mandate_import_entries ||= Services::MandateImportEntriesService.new(@api_service)
+    end
+
     # Access to the service for mandate_pdf to make API calls
     def mandate_pdfs
       @mandate_pdfs ||= Services::MandatePdfsService.new(@api_service)
@@ -123,7 +133,7 @@ module GoCardlessPro
           'User-Agent' => user_agent.to_s,
           'Content-Type' => 'application/json',
           'GoCardless-Client-Library' => 'gocardless-pro-ruby',
-          'GoCardless-Client-Version' => '2.7.0',
+          'GoCardless-Client-Version' => '2.8.0',
         },
       }
     end

data/lib/gocardless_pro/resources/mandate_import.rb

@@ -0,0 +1,88 @@
+# encoding: utf-8
+
+#
+# This client is automatically generated from a template and JSON schema definition.
+# See https://github.com/gocardless/gocardless-pro-ruby#contributing before editing.
+#
+
+require 'uri'
+
+module GoCardlessPro
+  # A module containing classes for each of the resources in the GC Api
+  module Resources
+    # Represents an instance of a mandate_import resource returned from the API
+
+    # Mandate Imports allow you to migrate existing mandates from other
+    # providers into the
+    # GoCardless platform.
+    #
+    # The process is as follows:
+    #
+    #   1. [Create a mandate
+    # import](#mandate-imports-create-a-new-mandate-import)
+    #   2. [Add entries](#mandate-import-entries-add-a-mandate-import-entry) to
+    # the import
+    #   3. [Submit](#mandate-imports-submit-a-mandate-import) the import
+    #   4. Wait until a member of the GoCardless team approves the import, at
+    # which point the mandates will be created
+    #   5. [Link up the
+    # mandates](#mandate-import-entries-list-all-mandate-import-entries) in your
+    # system
+    #
+    # When you add entries to your mandate import, they are not turned into
+    # actual mandates
+    # until the mandate import is submitted by you via the API, and then
+    # processed by a member
+    # of the GoCardless team. When that happens, a mandate will be created for
+    # each entry in the import.
+    #
+    # We will issue a `mandate_created` webhook for each entry, which will be
+    # the same as the webhooks
+    # triggered when [ creating a mandate ](#mandates-create-a-mandate) using
+    # the mandates API. Once these
+    # webhooks start arriving, any reconciliation can now be accomplished by
+    # [checking the current status](#mandate-imports-get-a-mandate-import) of
+    # the mandate import and
+    # [linking up the mandates to your
+    # system](#mandate-import-entries-list-all-mandate-import-entries).
+    #
+    # <p class="notice">Note that all Mandate Imports have an upper limit of
+    # 30,000 entries, so
+    # we recommend you split your import into several smaller imports if you're
+    # planning to
+    # exceed this threshold.</p>
+    #
+    # <p class="restricted-notice"><strong>Restricted</strong>: This API is
+    # currently
+    # only available for approved partners - please <a
+    # href="mailto:help@gocardless.com">get
+    # in touch</a> if you would like to use this API.</p>
+    class MandateImport
+      attr_reader :created_at
+      attr_reader :id
+      attr_reader :scheme
+      attr_reader :status
+
+      # Initialize a mandate_import resource instance
+      # @param object [Hash] an object returned from the API
+      def initialize(object, response = nil)
+        @object = object
+
+        @created_at = object['created_at']
+        @id = object['id']
+        @scheme = object['scheme']
+        @status = object['status']
+        @response = response
+      end
+
+      def api_response
+        ApiResponse.new(@response)
+      end
+
+      # Provides the mandate_import resource as a hash of all its readable attributes
+      def to_h
+        @object
+      end
+    end
+  end
+end

data/lib/gocardless_pro/resources/mandate_import_entry.rb

@@ -0,0 +1,99 @@
+# encoding: utf-8
+
+#
+# This client is automatically generated from a template and JSON schema definition.
+# See https://github.com/gocardless/gocardless-pro-ruby#contributing before editing.
+#
+
+require 'uri'
+
+module GoCardlessPro
+  # A module containing classes for each of the resources in the GC Api
+  module Resources
+    # Represents an instance of a mandate_import_entry resource returned from the API
+
+    # Mandate Import Entries are added to a [Mandate
+    # Import](#core-endpoints-mandate-imports).
+    # Each entry corresponds to one mandate to be imported into GoCardless.
+    #
+    # To import a mandate you will need:
+    # <ol>
+    #   <li>Identifying information about the customer (name/company and
+    # address)</li>
+    #   <li>Bank account details, consisting of an account holder name and
+    #      either an IBAN or <a href="#appendix-local-bank-details">local bank
+    # details</a></li>
+    #   <li>Amendment details (SEPA only)</li>
+    # </ol>
+    #
+    # We suggest you provide a `record_identifier` (which is unique within the
+    # context of a
+    # single mandate import) to help you to identify mandates that have been
+    # created once the
+    # import has been processed by GoCardless. You can
+    # [list the mandate import
+    # entries](#mandate-import-entries-list-all-mandate-import-entries),
+    # match them up in your system using the `record_identifier`, and look at
+    # the `links`
+    # fields to find the mandate, customer and customer bank account that have
+    # been imported.
+    #
+    # <p class="restricted-notice"><strong>Restricted</strong>: This API is
+    # currently
+    # only available for approved partners - please <a
+    # href="mailto:help@gocardless.com">get
+    # in touch</a> if you would like to use this API.</p>
+    #
+    class MandateImportEntry
+      attr_reader :created_at
+      attr_reader :record_identifier
+
+      # Initialize a mandate_import_entry resource instance
+      # @param object [Hash] an object returned from the API
+      def initialize(object, response = nil)
+        @object = object
+
+        @created_at = object['created_at']
+        @links = object['links']
+        @record_identifier = object['record_identifier']
+        @response = response
+      end
+
+      def api_response
+        ApiResponse.new(@response)
+      end
+
+      # Return the links that the resource has
+      def links
+        @mandate_import_entry_links ||= Links.new(@links)
+      end
+
+      # Provides the mandate_import_entry resource as a hash of all its readable attributes
+      def to_h
+        @object
+      end
+
+      class Links
+        def initialize(links)
+          @links = links || {}
+        end
+
+        def customer
+          @links['customer']
+        end
+
+        def customer_bank_account
+          @links['customer_bank_account']
+        end
+
+        def mandate
+          @links['mandate']
+        end
+
+        def mandate_import
+          @links['mandate_import']
+        end
+      end
+    end
+  end
+end

data/lib/gocardless_pro/services/mandate_import_entries_service.rb

@@ -0,0 +1,99 @@
+require_relative './base_service'
+require 'uri'
+
+# encoding: utf-8
+#
+# This client is automatically generated from a template and JSON schema definition.
+# See https://github.com/gocardless/gocardless-pro-ruby#contributing before editing.
+#
+
+module GoCardlessPro
+  module Services
+    # Service for making requests to the MandateImportEntry endpoints
+    class MandateImportEntriesService < BaseService
+      # For an existing [mandate import](#core-endpoints-mandate-imports), this
+      # endpoint can
+      # be used to add individual mandates to be imported into GoCardless.
+      #
+      # You can add no more than 30,000 rows to a single mandate import.
+      # If you attempt to go over this limit, the API will return a
+      # `record_limit_exceeded` error.
+      # Example URL: /mandate_import_entries
+      # @param options [Hash] parameters as a hash, under a params key.
+      def create(options = {})
+        path = '/mandate_import_entries'
+
+        params = options.delete(:params) || {}
+        options[:params] = {}
+        options[:params][envelope_key] = params
+
+        options[:retry_failures] = true
+
+        response = make_request(:post, path, options)
+
+        return if response.body.nil?
+
+        Resources::MandateImportEntry.new(unenvelope_body(response.body), response)
+      end
+
+      # For an existing mandate import, this endpoint lists all of the entries
+      # attached.
+      #
+      # After a mandate import has been submitted, you can use this endpoint to
+      # associate records
+      # in your system (using the `record_identifier` that you provided when creating
+      # the
+      # mandate import).
+      #
+      # Example URL: /mandate_import_entries
+      # @param options [Hash] parameters as a hash, under a params key.
+      def list(options = {})
+        path = '/mandate_import_entries'
+
+        options[:retry_failures] = true
+
+        response = make_request(:get, path, options)
+
+        ListResponse.new(
+          response: response,
+          unenveloped_body: unenvelope_body(response.body),
+          resource_class: Resources::MandateImportEntry
+        )
+      end
+
+      # Get a lazily enumerated list of all the items returned. This is simmilar to the `list` method but will paginate for you automatically.
+      #
+      # @param options [Hash] parameters as a hash. If the request is a GET, these will be converted to query parameters.
+      # Otherwise they will be the body of the request.
+      def all(options = {})
+        Paginator.new(
+          service: self,
+          options: options
+        ).enumerator
+      end
+
+      private
+
+      # Unenvelope the response of the body using the service's `envelope_key`
+      #
+      # @param body [Hash]
+      def unenvelope_body(body)
+        body[envelope_key] || body['data']
+      end
+
+      # return the key which API responses will envelope data under
+      def envelope_key
+        'mandate_import_entries'
+      end
+
+      # take a URL with placeholder params and substitute them out for the actual value
+      # @param url [String] the URL with placeholders in
+      # @param param_map [Hash] a hash of placeholders and their actual values (which will be escaped)
+      def sub_url(url, param_map)
+        param_map.reduce(url) do |new_url, (param, value)|
+          new_url.gsub(":#{param}", URI.escape(value))
+        end
+      end
+    end
+  end
+end

data/lib/gocardless_pro/services/mandate_imports_service.rb

@@ -0,0 +1,156 @@
+require_relative './base_service'
+require 'uri'
+
+# encoding: utf-8
+#
+# This client is automatically generated from a template and JSON schema definition.
+# See https://github.com/gocardless/gocardless-pro-ruby#contributing before editing.
+#
+
+module GoCardlessPro
+  module Services
+    # Service for making requests to the MandateImport endpoints
+    class MandateImportsService < BaseService
+      # Mandate imports are first created, before mandates are added one-at-a-time, so
+      # this endpoint merely signals the start of the import process. Once you've
+      # finished
+      # adding entries to an import, you should
+      # [submit](#mandate-imports-submit-a-mandate-import) it.
+      # Example URL: /mandate_imports
+      # @param options [Hash] parameters as a hash, under a params key.
+      def create(options = {})
+        path = '/mandate_imports'
+
+        params = options.delete(:params) || {}
+        options[:params] = {}
+        options[:params][envelope_key] = params
+
+        options[:retry_failures] = true
+
+        begin
+          response = make_request(:post, path, options)
+
+          # Response doesn't raise any errors until #body is called
+          response.tap(&:body)
+        rescue InvalidStateError => e
+          return get(e.conflicting_resource_id) if e.idempotent_creation_conflict?
+
+          raise e
+        end
+
+        return if response.body.nil?
+
+        Resources::MandateImport.new(unenvelope_body(response.body), response)
+      end
+
+      # Returns a single mandate import.
+      # Example URL: /mandate_imports/:identity
+      #
+      # @param identity       # Unique identifier, beginning with "IM".
+      # @param options [Hash] parameters as a hash, under a params key.
+      def get(identity, options = {})
+        path = sub_url('/mandate_imports/:identity', 'identity' => identity)
+
+        options[:retry_failures] = true
+
+        response = make_request(:get, path, options)
+
+        return if response.body.nil?
+
+        Resources::MandateImport.new(unenvelope_body(response.body), response)
+      end
+
+      # Submits the mandate import, which allows it to be processed by a member of the
+      # GoCardless team. Once the import has been submitted, it can no longer have
+      # entries
+      # added to it.
+      # Example URL: /mandate_imports/:identity/actions/submit
+      #
+      # @param identity       # Unique identifier, beginning with "IM".
+      # @param options [Hash] parameters as a hash, under a params key.
+      def submit(identity, options = {})
+        path = sub_url('/mandate_imports/:identity/actions/submit', 'identity' => identity)
+
+        params = options.delete(:params) || {}
+        options[:params] = {}
+        options[:params]['data'] = params
+
+        options[:retry_failures] = false
+
+        begin
+          response = make_request(:post, path, options)
+
+          # Response doesn't raise any errors until #body is called
+          response.tap(&:body)
+        rescue InvalidStateError => e
+          return get(e.conflicting_resource_id) if e.idempotent_creation_conflict?
+
+          raise e
+        end
+
+        return if response.body.nil?
+
+        Resources::MandateImport.new(unenvelope_body(response.body), response)
+      end
+
+      # Cancels the mandate import, which aborts the import process and stops the
+      # mandates
+      # being set up in GoCardless. Once the import has been cancelled, it can no
+      # longer have
+      # entries added to it. Mandate imports which have already been submitted cannot
+      # be
+      # cancelled.
+      # Example URL: /mandate_imports/:identity/actions/cancel
+      #
+      # @param identity       # Unique identifier, beginning with "IM".
+      # @param options [Hash] parameters as a hash, under a params key.
+      def cancel(identity, options = {})
+        path = sub_url('/mandate_imports/:identity/actions/cancel', 'identity' => identity)
+
+        params = options.delete(:params) || {}
+        options[:params] = {}
+        options[:params]['data'] = params
+
+        options[:retry_failures] = false
+
+        begin
+          response = make_request(:post, path, options)
+
+          # Response doesn't raise any errors until #body is called
+          response.tap(&:body)
+        rescue InvalidStateError => e
+          return get(e.conflicting_resource_id) if e.idempotent_creation_conflict?
+
+          raise e
+        end
+
+        return if response.body.nil?
+
+        Resources::MandateImport.new(unenvelope_body(response.body), response)
+      end
+
+      private
+
+      # Unenvelope the response of the body using the service's `envelope_key`
+      #
+      # @param body [Hash]
+      def unenvelope_body(body)
+        body[envelope_key] || body['data']
+      end
+
+      # return the key which API responses will envelope data under
+      def envelope_key
+        'mandate_imports'
+      end
+
+      # take a URL with placeholder params and substitute them out for the actual value
+      # @param url [String] the URL with placeholders in
+      # @param param_map [Hash] a hash of placeholders and their actual values (which will be escaped)
+      def sub_url(url, param_map)
+        param_map.reduce(url) do |new_url, (param, value)|
+          new_url.gsub(":#{param}", URI.escape(value))
+        end
+      end
+    end
+  end
+end