gocardless_pro 4.2.0 → 4.4.1

data/lib/gocardless_pro/services/scheme_identifiers_service.rb

@@ -20,7 +20,7 @@ module GoCardlessPro
       # become active. On other schemes, including SEPA,
       # this happens instantly.
       #
-      # #### Scheme identifier name validations
+      # Scheme identifier name validations
       #
       # The `name` field of a scheme identifier can contain alphanumeric characters,
       # spaces and
@@ -29,8 +29,8 @@ module GoCardlessPro
       # Its maximum length and the special characters it supports depend on the
       # scheme:
       #
-      # | __scheme__        | __maximum length__ | __special characters allowed__
-      #                 |
+      # | scheme        | maximum length | special characters allowed
+      #     |
       # | :---------------- | :----------------- |
       # :-------------------------------------------------- |
       # | `bacs`            | 18 characters      | `/` `.` `&` `-`
@@ -49,7 +49,6 @@ module GoCardlessPro
       # You should ensure that the name you set matches the legal name or the trading
       # name of
       # the creditor, otherwise, there is an increased risk of chargeback.
-      #
       # Example URL: /scheme_identifiers
       # @param options [Hash] parameters as a hash, under a params key.
       def create(options = {})
@@ -70,7 +69,7 @@ module GoCardlessPro
           if e.idempotent_creation_conflict?
             case @api_service.on_idempotency_conflict
             when :raise
-              raise IdempotencyConflict, e.error
+              raise IdempotencyConflict.new(e.error)
             when :fetch
               return get(e.conflicting_resource_id)
             end
@@ -84,8 +83,9 @@ module GoCardlessPro
         Resources::SchemeIdentifier.new(unenvelope_body(response.body), response)
       end
 
-      # Returns a [cursor-paginated](#api-usage-cursor-pagination) list of your scheme
-      # identifiers.
+      # Returns a cursor-paginated
+      # (https://developer.gocardless.com/api-reference/#api-usage-cursor-pagination)
+      # list of your scheme identifiers.
       # Example URL: /scheme_identifiers
       # @param options [Hash] parameters as a hash, under a params key.
       def list(options = {})
@@ -120,7 +120,7 @@ module GoCardlessPro
       # @param options [Hash] parameters as a hash, under a params key.
       def get(identity, options = {})
         path = sub_url('/scheme_identifiers/:identity', {
-                         'identity' => identity
+                         'identity' => identity,
                        })
 
         options[:retry_failures] = true
@@ -138,7 +138,13 @@ module GoCardlessPro
       #
       # @param body [Hash]
       def unenvelope_body(body)
-        body[envelope_key] || body['data']
+        if body.key?(envelope_key)
+          body[envelope_key]
+        elsif body.key?('data')
+          body['data']
+        else
+          body
+        end
       end
 
       # return the key which API responses will envelope data under

data/lib/gocardless_pro/services/subscriptions_service.rb

@@ -31,7 +31,7 @@ module GoCardlessPro
           if e.idempotent_creation_conflict?
             case @api_service.on_idempotency_conflict
             when :raise
-              raise IdempotencyConflict, e.error
+              raise IdempotencyConflict.new(e.error)
             when :fetch
               return get(e.conflicting_resource_id)
             end
@@ -45,9 +45,10 @@ module GoCardlessPro
         Resources::Subscription.new(unenvelope_body(response.body), response)
       end
 
-      # Returns a [cursor-paginated](#api-usage-cursor-pagination) list of your
-      # subscriptions. Please note if the subscriptions are related to customers who
-      # have been removed, they will not be shown in the response.
+      # Returns a cursor-paginated
+      # (https://developer.gocardless.com/api-reference/#api-usage-cursor-pagination)
+      # list of your subscriptions. Please note if the subscriptions are related to
+      # customers who have been removed, they will not be shown in the response.
       # Example URL: /subscriptions
       # @param options [Hash] parameters as a hash, under a params key.
       def list(options = {})
@@ -82,7 +83,7 @@ module GoCardlessPro
       # @param options [Hash] parameters as a hash, under a params key.
       def get(identity, options = {})
         path = sub_url('/subscriptions/:identity', {
-                         'identity' => identity
+                         'identity' => identity,
                        })
 
         options[:retry_failures] = true
@@ -98,33 +99,33 @@ module GoCardlessPro
       #
       # This fails with:
       #
-      # - `validation_failed` if invalid data is provided when attempting to update a
+      # -
+      # `validation_failed` if invalid data is provided when attempting to update a
       # subscription.
-      #
-      # - `subscription_not_active` if the subscription is no longer active.
-      #
-      # - `subscription_already_ended` if the subscription has taken all payments.
-      #
-      # - `mandate_payments_require_approval` if the amount is being changed and the
+      # -
+      # `subscription_not_active` if the subscription is no longer active.
+      # -
+      # `subscription_already_ended` if the subscription has taken all payments.
+      # -
+      # `mandate_payments_require_approval` if the amount is being changed and the
       # mandate requires approval.
-      #
-      # - `number_of_subscription_amendments_exceeded` error if the subscription
-      # amount has already been changed 10 times.
-      #
-      # - `forbidden` if the amount is being changed, and the subscription was created
+      # -
+      # `number_of_subscription_amendments_exceeded` error if the subscription amount
+      # has already been changed 10 times.
+      # -
+      # `forbidden` if the amount is being changed, and the subscription was created
       # by an app and you are not authenticated as that app, or if the subscription
       # was not created by an app and you are authenticated as an app
-      #
-      # - `resource_created_by_another_app` if the app fee is being changed, and the
+      # -
+      # `resource_created_by_another_app` if the app fee is being changed, and the
       # subscription was created by an app other than the app you are authenticated as
-      #
       # Example URL: /subscriptions/:identity
       #
       # @param identity       # Unique identifier, beginning with "SB".
       # @param options [Hash] parameters as a hash, under a params key.
       def update(identity, options = {})
         path = sub_url('/subscriptions/:identity', {
-                         'identity' => identity
+                         'identity' => identity,
                        })
 
         params = options.delete(:params) || {}
@@ -148,8 +149,10 @@ module GoCardlessPro
       # when they continue forever (created without `count` or `end_date`) or
       # the subscription is already paused for a number of cycles.
       #
-      # When `pause_cycles` is omitted the subscription is paused until the [resume
-      # endpoint](#subscriptions-resume-a-subscription) is called.
+      # When `pause_cycles` is omitted the subscription is paused until the resume
+      # endpoint
+      # (https://developer.gocardless.com/api-reference/#subscriptions-resume-a-subscription)
+      # is called.
       # If the subscription is collecting a fixed number of payments, `end_date` will
       # be set to `null`.
       # When paused indefinitely, `upcoming_payments` will be empty.
@@ -163,22 +166,23 @@ module GoCardlessPro
       #
       # This fails with:
       #
-      # - `forbidden` if the subscription was created by an app and you are not
+      # -
+      # `forbidden` if the subscription was created by an app and you are not
       # authenticated as that app, or if the subscription was not created by an app
       # and you are authenticated as an app
-      #
-      # - `validation_failed` if invalid data is provided when attempting to pause a
+      # -
+      # `validation_failed` if invalid data is provided when attempting to pause a
       # subscription.
-      #
-      # - `subscription_paused_cannot_update_cycles` if the subscription is already
+      # -
+      # `subscription_paused_cannot_update_cycles` if the subscription is already
       # paused for a number of cycles and the request provides a value for
       # `pause_cycle`.
-      #
-      # - `subscription_cannot_be_paused` if the subscription cannot be paused.
-      #
-      # - `subscription_already_ended` if the subscription has taken all payments.
-      #
-      # - `pause_cycles_must_be_greater_than_or_equal_to` if the provided value for
+      # -
+      # `subscription_cannot_be_paused` if the subscription cannot be paused.
+      # -
+      # `subscription_already_ended` if the subscription has taken all payments.
+      # -
+      # `pause_cycles_must_be_greater_than_or_equal_to` if the provided value for
       # `pause_cycles` cannot be satisfied.
       # Example URL: /subscriptions/:identity/actions/pause
       #
@@ -186,7 +190,7 @@ module GoCardlessPro
       # @param options [Hash] parameters as a hash, under a params key.
       def pause(identity, options = {})
         path = sub_url('/subscriptions/:identity/actions/pause', {
-                         'identity' => identity
+                         'identity' => identity,
                        })
 
         params = options.delete(:params) || {}
@@ -204,7 +208,7 @@ module GoCardlessPro
           if e.idempotent_creation_conflict?
             case @api_service.on_idempotency_conflict
             when :raise
-              raise IdempotencyConflict, e.error
+              raise IdempotencyConflict.new(e.error)
             when :fetch
               return get(e.conflicting_resource_id)
             end
@@ -226,22 +230,22 @@ module GoCardlessPro
       #
       # This fails with:
       #
-      # - `forbidden` if the subscription was created by an app and you are not
+      # -
+      # `forbidden` if the subscription was created by an app and you are not
       # authenticated as that app, or if the subscription was not created by an app
       # and you are authenticated as an app
-      #
-      # - `validation_failed` if invalid data is provided when attempting to resume a
+      # -
+      # `validation_failed` if invalid data is provided when attempting to resume a
       # subscription.
-      #
-      # - `subscription_not_paused` if the subscription is not paused.
-      #
+      # -
+      # `subscription_not_paused` if the subscription is not paused.
       # Example URL: /subscriptions/:identity/actions/resume
       #
       # @param identity       # Unique identifier, beginning with "SB".
       # @param options [Hash] parameters as a hash, under a params key.
       def resume(identity, options = {})
         path = sub_url('/subscriptions/:identity/actions/resume', {
-                         'identity' => identity
+                         'identity' => identity,
                        })
 
         params = options.delete(:params) || {}
@@ -259,7 +263,7 @@ module GoCardlessPro
           if e.idempotent_creation_conflict?
             case @api_service.on_idempotency_conflict
             when :raise
-              raise IdempotencyConflict, e.error
+              raise IdempotencyConflict.new(e.error)
             when :fetch
               return get(e.conflicting_resource_id)
             end
@@ -285,7 +289,7 @@ module GoCardlessPro
       # @param options [Hash] parameters as a hash, under a params key.
       def cancel(identity, options = {})
         path = sub_url('/subscriptions/:identity/actions/cancel', {
-                         'identity' => identity
+                         'identity' => identity,
                        })
 
         params = options.delete(:params) || {}
@@ -303,7 +307,7 @@ module GoCardlessPro
           if e.idempotent_creation_conflict?
             case @api_service.on_idempotency_conflict
             when :raise
-              raise IdempotencyConflict, e.error
+              raise IdempotencyConflict.new(e.error)
             when :fetch
               return get(e.conflicting_resource_id)
             end
@@ -323,7 +327,13 @@ module GoCardlessPro
       #
       # @param body [Hash]
       def unenvelope_body(body)
-        body[envelope_key] || body['data']
+        if body.key?(envelope_key)
+          body[envelope_key]
+        elsif body.key?('data')
+          body['data']
+        else
+          body
+        end
       end
 
       # return the key which API responses will envelope data under

data/lib/gocardless_pro/services/tax_rates_service.rb

@@ -10,8 +10,9 @@ module GoCardlessPro
   module Services
     # Service for making requests to the TaxRate endpoints
     class TaxRatesService < BaseService
-      # Returns a [cursor-paginated](#api-usage-cursor-pagination) list of all tax
-      # rates.
+      # Returns a cursor-paginated
+      # (https://developer.gocardless.com/api-reference/#api-usage-cursor-pagination)
+      # list of all tax rates.
       # Example URL: /tax_rates
       # @param options [Hash] parameters as a hash, under a params key.
       def list(options = {})
@@ -46,7 +47,7 @@ module GoCardlessPro
       # @param options [Hash] parameters as a hash, under a params key.
       def get(identity, options = {})
         path = sub_url('/tax_rates/:identity', {
-                         'identity' => identity
+                         'identity' => identity,
                        })
 
         options[:retry_failures] = true
@@ -64,7 +65,13 @@ module GoCardlessPro
       #
       # @param body [Hash]
       def unenvelope_body(body)
-        body[envelope_key] || body['data']
+        if body.key?(envelope_key)
+          body[envelope_key]
+        elsif body.key?('data')
+          body['data']
+        else
+          body
+        end
       end
 
       # return the key which API responses will envelope data under

data/lib/gocardless_pro/services/transferred_mandates_service.rb

@@ -19,7 +19,7 @@ module GoCardlessPro
       # @param options [Hash] parameters as a hash, under a params key.
       def transferred_mandates(identity, options = {})
         path = sub_url('/transferred_mandates/:identity', {
-                         'identity' => identity
+                         'identity' => identity,
                        })
 
         options[:retry_failures] = false
@@ -37,7 +37,13 @@ module GoCardlessPro
       #
       # @param body [Hash]
       def unenvelope_body(body)
-        body[envelope_key] || body['data']
+        if body.key?(envelope_key)
+          body[envelope_key]
+        elsif body.key?('data')
+          body['data']
+        else
+          body
+        end
       end
 
       # return the key which API responses will envelope data under

data/lib/gocardless_pro/services/verification_details_service.rb

@@ -63,7 +63,13 @@ module GoCardlessPro
       #
       # @param body [Hash]
       def unenvelope_body(body)
-        body[envelope_key] || body['data']
+        if body.key?(envelope_key)
+          body[envelope_key]
+        elsif body.key?('data')
+          body['data']
+        else
+          body
+        end
       end
 
       # return the key which API responses will envelope data under

data/lib/gocardless_pro/services/webhooks_service.rb

@@ -10,8 +10,9 @@ module GoCardlessPro
   module Services
     # Service for making requests to the Webhook endpoints
     class WebhooksService < BaseService
-      # Returns a [cursor-paginated](#api-usage-cursor-pagination) list of your
-      # webhooks.
+      # Returns a cursor-paginated
+      # (https://developer.gocardless.com/api-reference/#api-usage-cursor-pagination)
+      # list of your webhooks.
       # Example URL: /webhooks
       # @param options [Hash] parameters as a hash, under a params key.
       def list(options = {})
@@ -46,7 +47,7 @@ module GoCardlessPro
       # @param options [Hash] parameters as a hash, under a params key.
       def get(identity, options = {})
         path = sub_url('/webhooks/:identity', {
-                         'identity' => identity
+                         'identity' => identity,
                        })
 
         options[:retry_failures] = true
@@ -65,7 +66,7 @@ module GoCardlessPro
       # @param options [Hash] parameters as a hash, under a params key.
       def retry(identity, options = {})
         path = sub_url('/webhooks/:identity/actions/retry', {
-                         'identity' => identity
+                         'identity' => identity,
                        })
 
         params = options.delete(:params) || {}
@@ -83,7 +84,7 @@ module GoCardlessPro
           if e.idempotent_creation_conflict?
             case @api_service.on_idempotency_conflict
             when :raise
-              raise IdempotencyConflict, e.error
+              raise IdempotencyConflict.new(e.error)
             when :fetch
               return get(e.conflicting_resource_id)
             end
@@ -103,7 +104,13 @@ module GoCardlessPro
       #
       # @param body [Hash]
       def unenvelope_body(body)
-        body[envelope_key] || body['data']
+        if body.key?(envelope_key)
+          body[envelope_key]
+        elsif body.key?('data')
+          body['data']
+        else
+          body
+        end
       end
 
       # return the key which API responses will envelope data under

data/lib/gocardless_pro/version.rb

@@ -3,5 +3,5 @@ end
 
 module GoCardlessPro
   # Current version of the GC gem
-  VERSION = '4.2.0'
+  VERSION = '4.4.1'
 end

data/lib/gocardless_pro/webhook.rb

@@ -1,6 +1,18 @@
 require 'openssl'
 
 module GoCardlessPro
+  # Represents the result of parsing a webhook, containing both the events
+  # and the webhook metadata.
+  class WebhookParseResult
+    attr_reader :events
+    attr_reader :webhook_id
+
+    def initialize(events, webhook_id)
+      @events = events
+      @webhook_id = webhook_id
+    end
+  end
+
   class Webhook
     class InvalidSignatureError < StandardError; end
 
@@ -38,6 +50,39 @@ module GoCardlessPro
         events.map { |event| Resources::Event.new(event) }
       end
 
+      # Validates that a webhook was genuinely sent by GoCardless using
+      # `.signature_valid?`, and then parses it into a WebhookParseResult containing
+      # both the events and the webhook ID from the meta field
+      #
+      # @option options [String] :request_body the request body
+      # @option options [String] :signature_header the signature included in the request,
+      #   found in the `Webhook-Signature` header
+      # @option options [String] :webhook_endpoint_secret the webhook endpoint secret for
+      #   your webhook endpoint, as configured in your GoCardless Dashboard
+      # @return [WebhookParseResult] containing the events and webhook ID
+      # @raise [InvalidSignatureError] if the signature header specified does not match
+      #   the signature computed using the request body and webhook endpoint secret
+      # @raise [ArgumentError] if a required keyword argument is not provided or is not
+      #   of the required type
+      def parse_with_meta(options = {})
+        validate_options!(options)
+
+        unless signature_valid?(request_body: options[:request_body],
+                                signature_header: options[:signature_header],
+                                webhook_endpoint_secret: options[:webhook_endpoint_secret])
+          raise InvalidSignatureError, "This webhook doesn't appear to be a genuine " \
+                                        'webhook from GoCardless, because the signature ' \
+                                        "header doesn't match the signature computed" \
+                                        ' with your webhook endpoint secret.'
+        end
+
+        parsed = JSON.parse(options[:request_body])
+        events = parsed['events'].map { |event| Resources::Event.new(event) }
+        webhook_id = parsed.dig('meta', 'webhook_id')
+
+        WebhookParseResult.new(events, webhook_id)
+      end
+
       # Validates that a webhook was genuinely sent by GoCardless by computing its
       # signature using the body and your webhook endpoint secret, and comparing that with
       # the signature included in the `Webhook-Signature` header

data/lib/gocardless_pro.rb

@@ -45,6 +45,9 @@ require_relative 'gocardless_pro/services/balances_service'
 require_relative 'gocardless_pro/resources/bank_account_detail'
 require_relative 'gocardless_pro/services/bank_account_details_service'
 
+require_relative 'gocardless_pro/resources/bank_account_holder_verification'
+require_relative 'gocardless_pro/services/bank_account_holder_verifications_service'
+
 require_relative 'gocardless_pro/resources/bank_authorisation'
 require_relative 'gocardless_pro/services/bank_authorisations_service'
 
@@ -90,6 +93,9 @@ require_relative 'gocardless_pro/services/events_service'
 require_relative 'gocardless_pro/resources/export'
 require_relative 'gocardless_pro/services/exports_service'
 
+require_relative 'gocardless_pro/resources/funds_availability'
+require_relative 'gocardless_pro/services/funds_availabilities_service'
+
 require_relative 'gocardless_pro/resources/instalment_schedule'
 require_relative 'gocardless_pro/services/instalment_schedules_service'
 
@@ -117,6 +123,12 @@ require_relative 'gocardless_pro/services/negative_balance_limits_service'
 require_relative 'gocardless_pro/resources/outbound_payment'
 require_relative 'gocardless_pro/services/outbound_payments_service'
 
+require_relative 'gocardless_pro/resources/outbound_payment_import'
+require_relative 'gocardless_pro/services/outbound_payment_imports_service'
+
+require_relative 'gocardless_pro/resources/outbound_payment_import_entry'
+require_relative 'gocardless_pro/services/outbound_payment_import_entries_service'
+
 require_relative 'gocardless_pro/resources/payer_authorisation'
 require_relative 'gocardless_pro/services/payer_authorisations_service'
 
@@ -126,6 +138,12 @@ require_relative 'gocardless_pro/services/payer_themes_service'
 require_relative 'gocardless_pro/resources/payment'
 require_relative 'gocardless_pro/services/payments_service'
 
+require_relative 'gocardless_pro/resources/payment_account'
+require_relative 'gocardless_pro/services/payment_accounts_service'
+
+require_relative 'gocardless_pro/resources/payment_account_transaction'
+require_relative 'gocardless_pro/services/payment_account_transactions_service'
+
 require_relative 'gocardless_pro/resources/payout'
 require_relative 'gocardless_pro/services/payouts_service'