gocardless_pro 2.3.0 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8695d142ee02b15a42c2ddbd7565ce06a067fa8f
-  data.tar.gz: 4c0927aad319de86206bdcc71952a47e4a0f1c88
+  metadata.gz: eb3944b3517a68c3d3a825fdd00ebd3e9951c130
+  data.tar.gz: 24cab2d00dc28ceda2fdaa2d9e0c10d71c57ab09
 SHA512:
-  metadata.gz: 91d51533cc01b11109feaba8810bd9b63bd84dc3f4b9fa083d180cac83961acb27026f448c10f32eeb08505745140f9fec010c42cc99762651218f856c85f67c
-  data.tar.gz: 000cec55d848d73509a7bcb60e398036fafb41417c183440d5563c8eee312ab0e076dc728c435e1a387f30c2e473fb6c492dc6bf83ca7b6ee4192cc40d7c18ca
+  metadata.gz: 8e6c180d2bf3d244a3f99c8f767852e7af34626aa09721a79a7c087e62cf1fdfef58efb3e5bef3f55b1077c140bbb1395f8917ec999e57dcfe95ce72994cac71
+  data.tar.gz: 3111e978bff8ffc020f35696f02ed12d418ca43bf1b38b87c9271cc1e0eb74071f73228bf65c4b48b5ccb44e51ebd9cd944c99352e715b4301d08fd898ef241d

data/lib/gocardless_pro.rb

@@ -67,6 +67,9 @@ require_relative 'gocardless_pro/services/payments_service'
 require_relative 'gocardless_pro/resources/payout'
 require_relative 'gocardless_pro/services/payouts_service'
 
+require_relative 'gocardless_pro/resources/payout_item'
+require_relative 'gocardless_pro/services/payout_items_service'
+
 require_relative 'gocardless_pro/resources/redirect_flow'
 require_relative 'gocardless_pro/services/redirect_flows_service'
 

data/lib/gocardless_pro/client.rb

@@ -53,6 +53,11 @@ module GoCardlessPro
       @payouts ||= Services::PayoutsService.new(@api_service)
     end
 
+    # Access to the service for payout_item to make API calls
+    def payout_items
+      @payout_items ||= Services::PayoutItemsService.new(@api_service)
+    end
+
     # Access to the service for redirect_flow to make API calls
     def redirect_flows
       @redirect_flows ||= Services::RedirectFlowsService.new(@api_service)
@@ -118,7 +123,7 @@ module GoCardlessPro
           'User-Agent' => user_agent.to_s,
           'Content-Type' => 'application/json',
           'GoCardless-Client-Library' => 'gocardless-pro-ruby',
-          'GoCardless-Client-Version' => '2.3.0',
+          'GoCardless-Client-Version' => '2.4.0',
         },
       }
     end

data/lib/gocardless_pro/resources/bank_details_lookup.rb

@@ -12,7 +12,7 @@ module GoCardlessPro
   module Resources
     # Represents an instance of a bank_details_lookup resource returned from the API
 
-    # Look up the name and reachability of a bank.
+    # Look up the name and reachability of a bank account.
     class BankDetailsLookup
       attr_reader :available_debit_schemes
       attr_reader :bank_name

data/lib/gocardless_pro/resources/creditor.rb

@@ -17,10 +17,9 @@ module GoCardlessPro
     # organisation will have a single "creditor", but the API also supports
     # collecting payments on behalf of others.
     #
-    # Please get in touch
-    # if you wish to use this endpoint. Currently, for Anti Money Laundering
-    # reasons, any creditors you add must be directly related to your
-    # organisation.
+    # Please get in touch if you wish to use this endpoint. Currently, for Anti
+    # Money Laundering reasons, any creditors you add must be directly related
+    # to your organisation.
     class Creditor
       attr_reader :address_line1
       attr_reader :address_line2

data/lib/gocardless_pro/resources/creditor_bank_account.rb

@@ -16,12 +16,11 @@ module GoCardlessPro
     # [creditor](#core-endpoints-creditors). These are the bank accounts which
     # your [payouts](#core-endpoints-payouts) will be sent to.
     #
-    # Note
-    # that creditor bank accounts must be unique, and so you will encounter a
-    # `bank_account_exists` error if you try to create a duplicate bank account.
-    # You may wish to handle this by updating the existing record instead, the
-    # ID of which will be provided as `links[creditor_bank_account]` in the
-    # error response.
+    # Note that creditor bank accounts must be unique, and so you will encounter
+    # a `bank_account_exists` error if you try to create a duplicate bank
+    # account. You may wish to handle this by updating the existing record
+    # instead, the ID of which will be provided as
+    # `links[creditor_bank_account]` in the error response.
     class CreditorBankAccount
       attr_reader :account_holder_name
       attr_reader :account_number_ending

data/lib/gocardless_pro/resources/customer.rb

@@ -17,7 +17,6 @@ module GoCardlessPro
     # accounts](#core-endpoints-customer-bank-accounts), which in turn can have
     # several Direct Debit [mandates](#core-endpoints-mandates).
     #
-    #
     # Note: the `swedish_identity_number` field may only be supplied for Swedish
     # customers, and must be supplied if you intend to set up an Autogiro
     # mandate with the customer.

data/lib/gocardless_pro/resources/customer_bank_account.rb

@@ -17,12 +17,11 @@ module GoCardlessPro
     # [customer](#core-endpoints-customers), and may be linked to several Direct
     # Debit [mandates](#core-endpoints-mandates).
     #
-    # Note that
-    # customer bank accounts must be unique, and so you will encounter a
-    # `bank_account_exists` error if you try to create a duplicate bank account.
-    # You may wish to handle this by updating the existing record instead, the
-    # ID of which will be provided as `links[customer_bank_account]` in the
-    # error response.
+    # Note that customer bank accounts must be unique, and so you will encounter
+    # a `bank_account_exists` error if you try to create a duplicate bank
+    # account. You may wish to handle this by updating the existing record
+    # instead, the ID of which will be provided as
+    # `links[customer_bank_account]` in the error response.
     class CustomerBankAccount
       attr_reader :account_holder_name
       attr_reader :account_number_ending

data/lib/gocardless_pro/resources/mandate.rb

@@ -15,9 +15,8 @@ module GoCardlessPro
     # Mandates represent the Direct Debit mandate with a
     # [customer](#core-endpoints-customers).
     #
-    # GoCardless will notify
-    # you via a [webhook](#appendix-webhooks) whenever the status of a mandate
-    # changes.
+    # GoCardless will notify you via a [webhook](#appendix-webhooks) whenever
+    # the status of a mandate changes.
     class Mandate
       attr_reader :created_at
       attr_reader :id

data/lib/gocardless_pro/resources/payment.rb

@@ -17,9 +17,8 @@ module GoCardlessPro
     # [creditor](#core-endpoints-creditors), taken against a Direct Debit
     # [mandate](#core-endpoints-mandates).
     #
-    # GoCardless will notify
-    # you via a [webhook](#appendix-webhooks) whenever the state of a payment
-    # changes.
+    # GoCardless will notify you via a [webhook](#appendix-webhooks) whenever
+    # the state of a payment changes.
     class Payment
       attr_reader :amount
       attr_reader :amount_refunded

data/lib/gocardless_pro/resources/payout_item.rb

@@ -0,0 +1,81 @@
+# 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 payout_item resource returned from the API
+
+    # When we collect a payment on your behalf, we add the money you've
+    # collected to your
+    # GoCardless balance, minus any fees paid. Periodically (usually every
+    # working day),
+    # we take any positive balance in your GoCardless account, and pay it out to
+    # your
+    # nominated bank account.
+    #
+    # Other actions in your GoCardless account can also affect your balance. For
+    # example,
+    # if a customer charges back a payment, we'll deduct the payment's amount
+    # from your
+    # balance, but add any fees you paid for that payment back to your balance.
+    #
+    # The Payout Items API allows you to view, on a per-payout basis, the credit
+    # and debit
+    # items that make up that payout's amount.
+    #
+    # <p class="beta-notice"><strong>Beta</strong>:	The Payout Items API is in
+    # beta, and is
+    # subject to <a href="#overview-backwards-compatibility">backwards
+    # incompatible changes</a>
+    # with 30 days notice. Before making any breaking changes, we will contact
+    # all integrators
+    # who have used the API.</p>
+    #
+    class PayoutItem
+      attr_reader :amount
+      attr_reader :type
+
+      # Initialize a payout_item resource instance
+      # @param object [Hash] an object returned from the API
+      def initialize(object, response = nil)
+        @object = object
+
+        @amount = object['amount']
+        @links = object['links']
+        @type = object['type']
+        @response = response
+      end
+
+      def api_response
+        ApiResponse.new(@response)
+      end
+
+      # Return the links that the resource has
+      def links
+        @payout_item_links ||= Links.new(@links)
+      end
+
+      # Provides the payout_item resource as a hash of all its readable attributes
+      def to_h
+        @object
+      end
+
+      class Links
+        def initialize(links)
+          @links = links || {}
+        end
+
+        def payment
+          @links['payment']
+        end
+      end
+    end
+  end
+end

data/lib/gocardless_pro/resources/redirect_flow.rb

@@ -20,35 +20,30 @@ module GoCardlessPro
     #
     # The overall flow is:
     #
-    # 1. You
-    # [create](#redirect-flows-create-a-redirect-flow) a redirect flow for your
-    # customer, and redirect them to the returned redirect url, e.g.
+    # 1. You [create](#redirect-flows-create-a-redirect-flow) a redirect flow
+    # for your customer, and redirect them to the returned redirect url, e.g.
     # `https://pay.gocardless.com/flow/RE123`.
     #
-    # 2. Your customer
-    # supplies their name, email, address, and bank account details, and submits
-    # the form. This securely stores their details, and redirects them back to
-    # your `success_redirect_url` with `redirect_flow_id=RE123` in the
-    # querystring.
+    # 2. Your customer supplies their name, email, address, and bank account
+    # details, and submits the form. This securely stores their details, and
+    # redirects them back to your `success_redirect_url` with
+    # `redirect_flow_id=RE123` in the querystring.
     #
-    # 3. You
-    # [complete](#redirect-flows-complete-a-redirect-flow) the redirect flow,
-    # which creates a [customer](#core-endpoints-customers), [customer bank
-    # account](#core-endpoints-customer-bank-accounts), and
+    # 3. You [complete](#redirect-flows-complete-a-redirect-flow) the redirect
+    # flow, which creates a [customer](#core-endpoints-customers), [customer
+    # bank account](#core-endpoints-customer-bank-accounts), and
     # [mandate](#core-endpoints-mandates), and returns the ID of the mandate.
     # You may wish to create a [subscription](#core-endpoints-subscriptions) or
     # [payment](#core-endpoints-payments) at this point.
     #
-    # Once you
-    # have [completed](#redirect-flows-complete-a-redirect-flow) the redirect
-    # flow via the API, you should display a confirmation page to your customer,
-    # confirming that their Direct Debit has been set up. You can build your own
-    # page, or redirect to the one we provide in the `confirmation_url`
-    # attribute of the redirect flow.
+    # Once you have [completed](#redirect-flows-complete-a-redirect-flow) the
+    # redirect flow via the API, you should display a confirmation page to your
+    # customer, confirming that their Direct Debit has been set up. You can
+    # build your own page, or redirect to the one we provide in the
+    # `confirmation_url` attribute of the redirect flow.
     #
-    # Redirect flows expire 30
-    # minutes after they are first created. You cannot complete an expired
-    # redirect flow.
+    # Redirect flows expire 30 minutes after they are first created. You cannot
+    # complete an expired redirect flow.
     class RedirectFlow
       attr_reader :confirmation_url
       attr_reader :created_at

data/lib/gocardless_pro/resources/refund.rb

@@ -16,9 +16,9 @@ module GoCardlessPro
     # [payment](#core-endpoints-payments) back to the
     # [customer](#core-endpoints-customers).
     #
-    # GoCardless will notify
-    # you via a [webhook](#appendix-webhooks) whenever a refund is created, and
-    # will update the `amount_refunded` property of the payment.
+    # GoCardless will notify you via a [webhook](#appendix-webhooks) whenever a
+    # refund is created, and will update the `amount_refunded` property of the
+    # payment.
     class Refund
       attr_reader :amount
       attr_reader :created_at

data/lib/gocardless_pro/resources/subscription.rb

@@ -17,70 +17,54 @@ module GoCardlessPro
     #
     # ### Recurrence Rules
     #
-    # The following
-    # rules apply when specifying recurrence:
+    # The following rules apply when specifying recurrence:
     #
-    # - The first payment
-    # must be charged within 1 year.
-    # - When neither `month` nor
-    # `day_of_month` are present, the subscription will recur from the
-    # `start_date` based on the `interval_unit`.
-    # - If `month` or
-    # `day_of_month` are present, the recurrence rules will be applied from the
-    # `start_date`, and the following validations apply:
+    # - The first payment must be charged within 1 year.
+    # - When neither `month` nor `day_of_month` are present, the subscription
+    # will recur from the `start_date` based on the `interval_unit`.
+    # - If `month` or `day_of_month` are present, the recurrence rules will be
+    # applied from the `start_date`, and the following validations apply:
     #
-    # |
-    # interval_unit   | month                                          |
+    # | interval_unit   | month                                          |
     # day_of_month                            |
-    # | :-------------- |
-    # :--------------------------------------------- |
+    # | :-------------- | :--------------------------------------------- |
     # :-------------------------------------- |
-    # | yearly          |
-    # optional (required if `day_of_month` provided) | optional (required if
-    # `month` provided) |
-    # | monthly         | invalid
-    #                   | required                                |
-    # |
-    # weekly          | invalid                                        | invalid
-    #                                 |
+    # | yearly          | optional (required if `day_of_month` provided) |
+    # optional (required if `month` provided) |
+    # | monthly         | invalid                                        |
+    # required                                |
+    # | weekly          | invalid                                        |
+    # invalid                                 |
     #
     # Examples:
     #
-    # |
-    # interval_unit   | interval   | month   | day_of_month   | valid?
-    #                                   |
-    # | :-------------- | :--------- |
-    # :------ | :------------- |
+    # | interval_unit   | interval   | month   | day_of_month   | valid?
+    #                                     |
+    # | :-------------- | :--------- | :------ | :------------- |
     # :------------------------------------------------- |
-    # | yearly
-    #   | 1          | january | -1             | valid
-    #                     |
-    # | yearly          | 1          | march   |
-    #            | invalid - missing `day_of_month`                   |
-    # |
-    # monthly         | 6          |         | 12             | valid
-    #                                   |
-    # | monthly         | 6          |
-    # august  | 12             | invalid - `month` must be blank
-    #    |
-    # | weekly          | 2          |         |                |
-    # valid                                              |
-    # | weekly
-    #   | 2          | october | 10             | invalid - `month` and
-    # `day_of_month` must be blank |
+    # | yearly          | 1          | january | -1             | valid
+    #                                     |
+    # | yearly          | 1          | march   |                | invalid -
+    # missing `day_of_month`                   |
+    # | monthly         | 6          |         | 12             | valid
+    #                                     |
+    # | monthly         | 6          | august  | 12             | invalid -
+    # `month` must be blank                    |
+    # | weekly          | 2          |         |                | valid
+    #                                     |
+    # | weekly          | 2          | october | 10             | invalid -
+    # `month` and `day_of_month` must be blank |
     #
     # ### Rolling dates
     #
-    #
     # When a charge date falls on a non-business day, one of two things will
     # happen:
     #
-    # - if the recurrence rule specified `-1` as the
-    # `day_of_month`, the charge date will be rolled __backwards__ to the
-    # previous business day (i.e., the last working day of the month).
-    # -
-    # otherwise the charge date will be rolled __forwards__ to the next business
-    # day.
+    # - if the recurrence rule specified `-1` as the `day_of_month`, the charge
+    # date will be rolled __backwards__ to the previous business day (i.e., the
+    # last working day of the month).
+    # - otherwise the charge date will be rolled __forwards__ to the next
+    # business day.
     #
     class Subscription
       attr_reader :amount

data/lib/gocardless_pro/services/bank_details_lookups_service.rb

@@ -11,19 +11,23 @@ module GoCardlessPro
   module Services
     # Service for making requests to the BankDetailsLookup endpoints
     class BankDetailsLookupsService < BaseService
-      # Performs a bank details lookup.
-      #
-      # As part of the lookup a modulus check and
+      # Performs a bank details lookup. As part of the lookup, a modulus check and
       # reachability check are performed.
       #
-      # Bank account details may be supplied
-      # using [local details](#appendix-local-bank-details) or an IBAN.
+      # If your request returns an [error](#api-usage-errors) or the
+      # `available_debit_schemes`
+      # attribute is an empty array, you will not be able to collect payments from the
+      # specified bank account. GoCardless may be able to collect payments from an
+      # account
+      # even if no `bic` is returned.
+      #
+      # Bank account details may be supplied using [local
+      # details](#appendix-local-bank-details) or an IBAN.
       #
-      # _Note:_
-      # Usage of this endpoint is monitored. If your organisation relies on GoCardless
-      # for
-      # modulus or reachability checking but not for payment collection, please
-      # get in touch.
+      # _Note:_ Usage of this endpoint is monitored. If your organisation relies on
+      # GoCardless for
+      # modulus or reachability checking but not for payment collection, please get in
+      # touch.
       # Example URL: /bank_details_lookups
       # @param options [Hash] parameters as a hash, under a params key.
       def create(options = {})

data/lib/gocardless_pro/services/creditor_bank_accounts_service.rb

@@ -88,11 +88,11 @@ module GoCardlessPro
       # Immediately disables the bank account, no money can be paid out to a disabled
       # account.
       #
-      # This will return a `disable_failed` error if the bank account
-      # has already been disabled.
+      # This will return a `disable_failed` error if the bank account has already been
+      # disabled.
       #
-      # A disabled bank account can be re-enabled by
-      # creating a new bank account resource with the same details.
+      # A disabled bank account can be re-enabled by creating a new bank account
+      # resource with the same details.
       # Example URL: /creditor_bank_accounts/:identity/actions/disable
       #
       # @param identity       # Unique identifier, beginning with "BA".

data/lib/gocardless_pro/services/customer_bank_accounts_service.rb

@@ -13,17 +13,14 @@ module GoCardlessPro
     class CustomerBankAccountsService < BaseService
       # Creates a new customer bank account object.
       #
-      # There are three different
-      # ways to supply bank account details:
+      # There are three different ways to supply bank account details:
       #
-      # - [Local
-      # details](#appendix-local-bank-details)
+      # - [Local details](#appendix-local-bank-details)
       #
       # - IBAN
       #
-      # - [Customer Bank
-      # Account Tokens](#javascript-flow-create-a-customer-bank-account-token)
-      #
+      # - [Customer Bank Account
+      # Tokens](#javascript-flow-create-a-customer-bank-account-token)
       #
       # For more information on the different fields required in each country, see
       # [local bank details](#appendix-local-bank-details).
@@ -124,12 +121,11 @@ module GoCardlessPro
 
       # Immediately cancels all associated mandates and cancellable payments.
       #
-      #
       # This will return a `disable_failed` error if the bank account has already been
       # disabled.
       #
-      # A disabled bank account can be re-enabled by creating a new
-      # bank account resource with the same details.
+      # A disabled bank account can be re-enabled by creating a new bank account
+      # resource with the same details.
       # Example URL: /customer_bank_accounts/:identity/actions/disable
       #
       # @param identity       # Unique identifier, beginning with "BA".

data/lib/gocardless_pro/services/mandate_pdfs_service.rb

@@ -13,10 +13,9 @@ module GoCardlessPro
     class MandatePdfsService < BaseService
       # Generates a PDF mandate and returns its temporary URL.
       #
-      # Customer and bank
-      # account details can be left blank (for a blank mandate), provided manually, or
-      # inferred from the ID of an existing [mandate](#core-endpoints-mandates).
-      #
+      # Customer and bank account details can be left blank (for a blank mandate),
+      # provided manually, or inferred from the ID of an existing
+      # [mandate](#core-endpoints-mandates).
       #
       # To generate a PDF mandate in a foreign language, set your `Accept-Language`
       # header to the relevant [ISO

data/lib/gocardless_pro/services/mandates_service.rb

@@ -110,8 +110,8 @@ module GoCardlessPro
       # metadata supplied to this endpoint will be stored on the mandate cancellation
       # event it causes.
       #
-      # This will fail with a `cancellation_failed` error if the
-      # mandate is already cancelled.
+      # This will fail with a `cancellation_failed` error if the mandate is already
+      # cancelled.
       # Example URL: /mandates/:identity/actions/cancel
       #
       # @param identity       # Unique identifier, beginning with "MD".
@@ -148,7 +148,6 @@ module GoCardlessPro
       # `failed` webhook up to two working days later. Any metadata supplied to this
       # endpoint will be stored on the `resubmission_requested` event it causes.
       #
-      #
       # This will fail with a `mandate_not_inactive` error if the mandate is already
       # being submitted, or is active.
       #

data/lib/gocardless_pro/services/payments_service.rb

@@ -13,8 +13,7 @@ module GoCardlessPro
     class PaymentsService < BaseService
       # <a name="mandate_is_inactive"></a>Creates a new payment object.
       #
-      # This
-      # fails with a `mandate_is_inactive` error if the linked
+      # This fails with a `mandate_is_inactive` error if the linked
       # [mandate](#core-endpoints-mandates) is cancelled or has failed. Payments can
       # be created against mandates with status of: `pending_customer_approval`,
       # `pending_submission`, `submitted`, and `active`.
@@ -116,8 +115,8 @@ module GoCardlessPro
       # metadata supplied to this endpoint will be stored on the payment cancellation
       # event it causes.
       #
-      # This will fail with a `cancellation_failed` error unless
-      # the payment's status is `pending_submission`.
+      # This will fail with a `cancellation_failed` error unless the payment's status
+      # is `pending_submission`.
       # Example URL: /payments/:identity/actions/cancel
       #
       # @param identity       # Unique identifier, beginning with "PM".
@@ -154,11 +153,9 @@ module GoCardlessPro
       # event. Any metadata supplied to this endpoint will be stored against the
       # payment submission event it causes.
       #
-      # This will return a `retry_failed`
-      # error if the payment has not failed.
+      # This will return a `retry_failed` error if the payment has not failed.
       #
-      # Payments can be retried up to 3
-      # times.
+      # Payments can be retried up to 3 times.
       # Example URL: /payments/:identity/actions/retry
       #
       # @param identity       # Unique identifier, beginning with "PM".

data/lib/gocardless_pro/services/payout_items_service.rb

@@ -0,0 +1,68 @@
+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 PayoutItem endpoints
+    class PayoutItemsService < BaseService
+      # Returns a [cursor-paginated](#api-usage-cursor-pagination) list of items in
+      # the payout.
+      #
+      # Example URL: /payout_items
+      # @param options [Hash] parameters as a hash, under a params key.
+      def list(options = {})
+        path = '/payout_items'
+
+        options[:retry_failures] = true
+
+        response = make_request(:get, path, options)
+
+        ListResponse.new(
+          response: response,
+          unenveloped_body: unenvelope_body(response.body),
+          resource_class: Resources::PayoutItem
+        )
+      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
+        'payout_items'
+      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/redirect_flows_service.rb

@@ -62,12 +62,11 @@ module GoCardlessPro
       # [mandate](#core-endpoints-mandates) using the details supplied by your
       # customer and returns the ID of the created mandate.
       #
-      # This will return a
-      # `redirect_flow_incomplete` error if your customer has not yet been redirected
-      # back to your site, and a `redirect_flow_already_completed` error if your
-      # integration has already completed this flow. It will return a `bad_request`
-      # error if the `session_token` differs to the one supplied when the redirect
-      # flow was created.
+      # This will return a `redirect_flow_incomplete` error if your customer has not
+      # yet been redirected back to your site, and a `redirect_flow_already_completed`
+      # error if your integration has already completed this flow. It will return a
+      # `bad_request` error if the `session_token` differs to the one supplied when
+      # the redirect flow was created.
       # Example URL: /redirect_flows/:identity/actions/complete
       #
       # @param identity       # Unique identifier, beginning with "RE".

data/lib/gocardless_pro/services/refunds_service.rb

@@ -13,22 +13,19 @@ module GoCardlessPro
     class RefundsService < BaseService
       # Creates a new refund object.
       #
-      # This fails with:<a
-      # name="refund_payment_invalid_state"></a><a
+      # This fails with:<a name="refund_payment_invalid_state"></a><a
       # name="total_amount_confirmation_invalid"></a><a
       # name="number_of_refunds_exceeded"></a>
       #
-      # - `refund_payment_invalid_state`
-      # error if the linked [payment](#core-endpoints-payments) isn't either
-      # `confirmed` or `paid_out`.
+      # - `refund_payment_invalid_state` error if the linked
+      # [payment](#core-endpoints-payments) isn't either `confirmed` or `paid_out`.
       #
-      # - `total_amount_confirmation_invalid` if the
-      # confirmation amount doesn't match the total amount refunded for the payment.
-      # This safeguard is there to prevent two processes from creating refunds without
-      # awareness of each other.
+      # - `total_amount_confirmation_invalid` if the confirmation amount doesn't match
+      # the total amount refunded for the payment. This safeguard is there to prevent
+      # two processes from creating refunds without awareness of each other.
       #
-      # - `number_of_refunds_exceeded` if five or more
-      # refunds have already been created against the payment.
+      # - `number_of_refunds_exceeded` if five or more refunds have already been
+      # created against the payment.
       #
       # Example URL: /refunds
       # @param options [Hash] parameters as a hash, under a params key.

data/lib/gocardless_pro/services/subscriptions_service.rb

@@ -86,6 +86,22 @@ module GoCardlessPro
       end
 
       # Updates a subscription object.
+      #
+      # This fails with:
+      #
+      # - `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
+      # mandate requires approval.
+      #
+      # - `exceeded_max_amendments` error if the amount is being changed and the
+      #   subscription amount has already been changed 10 times.
+      #
       # Example URL: /subscriptions/:identity
       #
       # @param identity       # Unique identifier, beginning with "SB".
@@ -110,8 +126,8 @@ module GoCardlessPro
       # Any metadata supplied to this endpoint will be stored on the payment
       # cancellation event it causes.
       #
-      # This will fail with a cancellation_failed
-      # error if the subscription is already cancelled or finished.
+      # This will fail with a cancellation_failed error if the subscription is already
+      # cancelled or finished.
       # Example URL: /subscriptions/:identity/actions/cancel
       #
       # @param identity       # Unique identifier, beginning with "SB".

data/lib/gocardless_pro/version.rb

@@ -4,5 +4,5 @@ end
 
 module GoCardlessPro
   # Current version of the GC gem
-  VERSION = '2.3.0'.freeze
+  VERSION = '2.4.0'.freeze
 end

data/spec/resources/payout_item_spec.rb

@@ -0,0 +1,96 @@
+require 'spec_helper'
+
+describe GoCardlessPro::Resources::PayoutItem do
+  let(:client) do
+    GoCardlessPro::Client.new(
+      access_token: 'SECRET_TOKEN'
+    )
+  end
+
+  let(:response_headers) { { 'Content-Type' => 'application/json' } }
+
+  describe '#list' do
+    describe 'with no filters' do
+      subject(:get_list_response) { client.payout_items.list }
+
+      before do
+        stub_request(:get, %r{.*api.gocardless.com/payout_items}).to_return(
+          body: {
+            'payout_items' => [{
+
+              'amount' => 'amount-input',
+              'links' => 'links-input',
+              'type' => 'type-input',
+            }],
+            meta: {
+              cursors: {
+                before: nil,
+                after: 'ABC123',
+              },
+            },
+          }.to_json,
+          headers: response_headers
+        )
+      end
+
+      it 'wraps each item in the resource class' do
+        expect(get_list_response.records.map(&:class).uniq.first).to eq(GoCardlessPro::Resources::PayoutItem)
+
+        expect(get_list_response.records.first.amount).to eq('amount-input')
+
+        expect(get_list_response.records.first.type).to eq('type-input')
+      end
+
+      it 'exposes the cursors for before and after' do
+        expect(get_list_response.before).to eq(nil)
+        expect(get_list_response.after).to eq('ABC123')
+      end
+
+      specify { expect(get_list_response.api_response.headers).to eql('content-type' => 'application/json') }
+    end
+  end
+
+  describe '#all' do
+    let!(:first_response_stub) do
+      stub_request(:get, %r{.*api.gocardless.com/payout_items$}).to_return(
+        body: {
+          'payout_items' => [{
+
+            'amount' => 'amount-input',
+            'links' => 'links-input',
+            'type' => 'type-input',
+          }],
+          meta: {
+            cursors: { after: 'AB345' },
+            limit: 1,
+          },
+        }.to_json,
+        headers: response_headers
+      )
+    end
+
+    let!(:second_response_stub) do
+      stub_request(:get, %r{.*api.gocardless.com/payout_items\?after=AB345}).to_return(
+        body: {
+          'payout_items' => [{
+
+            'amount' => 'amount-input',
+            'links' => 'links-input',
+            'type' => 'type-input',
+          }],
+          meta: {
+            limit: 2,
+            cursors: {},
+          },
+        }.to_json,
+        headers: response_headers
+      )
+    end
+
+    it 'automatically makes the extra requests' do
+      expect(client.payout_items.all.to_a.length).to eq(2)
+      expect(first_response_stub).to have_been_requested
+      expect(second_response_stub).to have_been_requested
+    end
+  end
+end

data/spec/services/payout_items_service_spec.rb

@@ -0,0 +1,212 @@
+require 'spec_helper'
+
+describe GoCardlessPro::Services::PayoutItemsService do
+  let(:client) do
+    GoCardlessPro::Client.new(
+      access_token: 'SECRET_TOKEN'
+    )
+  end
+
+  let(:response_headers) { { 'Content-Type' => 'application/json' } }
+
+  describe '#list' do
+    describe 'with no filters' do
+      subject(:get_list_response) { client.payout_items.list }
+
+      let(:body) do
+        {
+          'payout_items' => [{
+
+            'amount' => 'amount-input',
+            'links' => 'links-input',
+            'type' => 'type-input',
+          }],
+          meta: {
+            cursors: {
+              before: nil,
+              after: 'ABC123',
+            },
+          },
+        }.to_json
+      end
+
+      before do
+        stub_request(:get, %r{.*api.gocardless.com/payout_items}).to_return(
+          body: body,
+          headers: response_headers
+        )
+      end
+
+      it 'wraps each item in the resource class' do
+        expect(get_list_response.records.map(&:class).uniq.first).to eq(GoCardlessPro::Resources::PayoutItem)
+
+        expect(get_list_response.records.first.amount).to eq('amount-input')
+
+        expect(get_list_response.records.first.type).to eq('type-input')
+      end
+
+      it 'exposes the cursors for before and after' do
+        expect(get_list_response.before).to eq(nil)
+        expect(get_list_response.after).to eq('ABC123')
+      end
+
+      specify { expect(get_list_response.api_response.headers).to eql('content-type' => 'application/json') }
+
+      describe 'retry behaviour' do
+        before { allow_any_instance_of(GoCardlessPro::Request).to receive(:sleep) }
+
+        it 'retries timeouts' do
+          stub = stub_request(:get, %r{.*api.gocardless.com/payout_items}).
+                 to_timeout.then.to_return(status: 200, headers: response_headers, body: body)
+
+          get_list_response
+          expect(stub).to have_been_requested.twice
+        end
+
+        it 'retries 5XX errors' do
+          stub = stub_request(:get, %r{.*api.gocardless.com/payout_items}).
+                 to_return(status: 502,
+                           headers: { 'Content-Type' => 'text/html' },
+                           body: '<html><body>Response from Cloudflare</body></html>').
+                 then.to_return(status: 200, headers: response_headers, body: body)
+
+          get_list_response
+          expect(stub).to have_been_requested.twice
+        end
+      end
+    end
+  end
+
+  describe '#all' do
+    let!(:first_response_stub) do
+      stub_request(:get, %r{.*api.gocardless.com/payout_items$}).to_return(
+        body: {
+          'payout_items' => [{
+
+            'amount' => 'amount-input',
+            'links' => 'links-input',
+            'type' => 'type-input',
+          }],
+          meta: {
+            cursors: { after: 'AB345' },
+            limit: 1,
+          },
+        }.to_json,
+        headers: response_headers
+      )
+    end
+
+    let!(:second_response_stub) do
+      stub_request(:get, %r{.*api.gocardless.com/payout_items\?after=AB345}).to_return(
+        body: {
+          'payout_items' => [{
+
+            'amount' => 'amount-input',
+            'links' => 'links-input',
+            'type' => 'type-input',
+          }],
+          meta: {
+            limit: 2,
+            cursors: {},
+          },
+        }.to_json,
+        headers: response_headers
+      )
+    end
+
+    it 'automatically makes the extra requests' do
+      expect(client.payout_items.all.to_a.length).to eq(2)
+      expect(first_response_stub).to have_been_requested
+      expect(second_response_stub).to have_been_requested
+    end
+
+    describe 'retry behaviour' do
+      before { allow_any_instance_of(GoCardlessPro::Request).to receive(:sleep) }
+
+      it 'retries timeouts' do
+        first_response_stub = stub_request(:get, %r{.*api.gocardless.com/payout_items$}).to_return(
+          body: {
+            'payout_items' => [{
+
+              'amount' => 'amount-input',
+              'links' => 'links-input',
+              'type' => 'type-input',
+            }],
+            meta: {
+              cursors: { after: 'AB345' },
+              limit: 1,
+            },
+          }.to_json,
+          headers: response_headers
+        )
+
+        second_response_stub = stub_request(:get, %r{.*api.gocardless.com/payout_items\?after=AB345}).
+                               to_timeout.then.
+                               to_return(
+                                 body: {
+                                   'payout_items' => [{
+
+                                     'amount' => 'amount-input',
+                                     'links' => 'links-input',
+                                     'type' => 'type-input',
+                                   }],
+                                   meta: {
+                                     limit: 2,
+                                     cursors: {},
+                                   },
+                                 }.to_json,
+                                 headers: response_headers
+                               )
+
+        client.payout_items.all.to_a
+
+        expect(first_response_stub).to have_been_requested
+        expect(second_response_stub).to have_been_requested.twice
+      end
+
+      it 'retries 5XX errors' do
+        first_response_stub = stub_request(:get, %r{.*api.gocardless.com/payout_items$}).to_return(
+          body: {
+            'payout_items' => [{
+
+              'amount' => 'amount-input',
+              'links' => 'links-input',
+              'type' => 'type-input',
+            }],
+            meta: {
+              cursors: { after: 'AB345' },
+              limit: 1,
+            },
+          }.to_json,
+          headers: response_headers
+        )
+
+        second_response_stub = stub_request(:get, %r{.*api.gocardless.com/payout_items\?after=AB345}).
+                               to_return(
+                                 status: 502,
+                                 body: '<html><body>Response from Cloudflare</body></html>',
+                                 headers: { 'Content-Type' => 'text/html' }
+                               ).then.to_return(
+                                 body: {
+                                   'payout_items' => [{
+
+                                     'amount' => 'amount-input',
+                                     'links' => 'links-input',
+                                     'type' => 'type-input',
+                                   }],
+                                   meta: {
+                                     limit: 2,
+                                     cursors: {},
+                                   },
+                                 }.to_json,
+                                 headers: response_headers
+                               )
+
+        client.payout_items.all.to_a
+
+        expect(first_response_stub).to have_been_requested
+        expect(second_response_stub).to have_been_requested.twice
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gocardless_pro
 version: !ruby/object:Gem::Version
-  version: 2.3.0
+  version: 2.4.0
 platform: ruby
 authors:
 - GoCardless
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-09-18 00:00:00.000000000 Z
+date: 2017-11-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -126,6 +126,7 @@ files:
 - lib/gocardless_pro/resources/mandate_pdf.rb
 - lib/gocardless_pro/resources/payment.rb
 - lib/gocardless_pro/resources/payout.rb
+- lib/gocardless_pro/resources/payout_item.rb
 - lib/gocardless_pro/resources/redirect_flow.rb
 - lib/gocardless_pro/resources/refund.rb
 - lib/gocardless_pro/resources/subscription.rb
@@ -140,6 +141,7 @@ files:
 - lib/gocardless_pro/services/mandate_pdfs_service.rb
 - lib/gocardless_pro/services/mandates_service.rb
 - lib/gocardless_pro/services/payments_service.rb
+- lib/gocardless_pro/services/payout_items_service.rb
 - lib/gocardless_pro/services/payouts_service.rb
 - lib/gocardless_pro/services/redirect_flows_service.rb
 - lib/gocardless_pro/services/refunds_service.rb
@@ -159,6 +161,7 @@ files:
 - spec/resources/mandate_pdf_spec.rb
 - spec/resources/mandate_spec.rb
 - spec/resources/payment_spec.rb
+- spec/resources/payout_item_spec.rb
 - spec/resources/payout_spec.rb
 - spec/resources/redirect_flow_spec.rb
 - spec/resources/refund_spec.rb
@@ -173,6 +176,7 @@ files:
 - spec/services/mandate_pdfs_service_spec.rb
 - spec/services/mandates_service_spec.rb
 - spec/services/payments_service_spec.rb
+- spec/services/payout_items_service_spec.rb
 - spec/services/payouts_service_spec.rb
 - spec/services/redirect_flows_service_spec.rb
 - spec/services/refunds_service_spec.rb
@@ -217,6 +221,7 @@ test_files:
 - spec/resources/mandate_pdf_spec.rb
 - spec/resources/mandate_spec.rb
 - spec/resources/payment_spec.rb
+- spec/resources/payout_item_spec.rb
 - spec/resources/payout_spec.rb
 - spec/resources/redirect_flow_spec.rb
 - spec/resources/refund_spec.rb
@@ -231,6 +236,7 @@ test_files:
 - spec/services/mandate_pdfs_service_spec.rb
 - spec/services/mandates_service_spec.rb
 - spec/services/payments_service_spec.rb
+- spec/services/payout_items_service_spec.rb
 - spec/services/payouts_service_spec.rb
 - spec/services/redirect_flows_service_spec.rb
 - spec/services/refunds_service_spec.rb