gocardless_pro 2.27.0 → 2.28.0

data/lib/gocardless_pro/services/billing_requests_service.rb

@@ -63,8 +63,6 @@ module GoCardlessPro
               raise IdempotencyConflict, e.error
             when :fetch
               return get(e.conflicting_resource_id)
-            else
-              raise ArgumentError, 'Unknown mode for :on_idempotency_conflict'
             end
           end
 
@@ -79,7 +77,7 @@ module GoCardlessPro
       # Fetches a billing request
       # Example URL: /billing_requests/:identity
       #
-      # @param identity       # Unique identifier, beginning with "PY".
+      # @param identity       # Unique identifier, beginning with "BRQ".
       # @param options [Hash] parameters as a hash, under a params key.
       def get(identity, options = {})
         path = sub_url('/billing_requests/:identity', 'identity' => identity)
@@ -105,7 +103,7 @@ module GoCardlessPro
       # successful.
       # Example URL: /billing_requests/:identity/actions/collect_customer_details
       #
-      # @param identity       # Unique identifier, beginning with "PY".
+      # @param identity       # Unique identifier, beginning with "BRQ".
       # @param options [Hash] parameters as a hash, under a params key.
       def collect_customer_details(identity, options = {})
         path = sub_url('/billing_requests/:identity/actions/collect_customer_details', 'identity' => identity)
@@ -128,8 +126,6 @@ module GoCardlessPro
               raise IdempotencyConflict, e.error
             when :fetch
               return get(e.conflicting_resource_id)
-            else
-              raise ArgumentError, 'Unknown mode for :on_idempotency_conflict'
             end
           end
 
@@ -142,18 +138,18 @@ module GoCardlessPro
       end
 
       # If the billing request has a pending
-      # <code>collect_bank_account_details</code> action, this endpoint can be
+      # <code>collect_bank_account</code> action, this endpoint can be
       # used to collect the details in order to complete it.
       #
       # The endpoint takes the same payload as Customer Bank Accounts, but check
       # the bank account is valid for the billing request scheme before creating
       # and attaching it.
-      # Example URL: /billing_requests/:identity/actions/collect_bank_account_details
+      # Example URL: /billing_requests/:identity/actions/collect_bank_account
       #
-      # @param identity       # Unique identifier, beginning with "PY".
+      # @param identity       # Unique identifier, beginning with "BRQ".
       # @param options [Hash] parameters as a hash, under a params key.
-      def collect_bank_account_details(identity, options = {})
-        path = sub_url('/billing_requests/:identity/actions/collect_bank_account_details', 'identity' => identity)
+      def collect_bank_account(identity, options = {})
+        path = sub_url('/billing_requests/:identity/actions/collect_bank_account', 'identity' => identity)
 
         params = options.delete(:params) || {}
         options[:params] = {}
@@ -173,8 +169,6 @@ module GoCardlessPro
               raise IdempotencyConflict, e.error
             when :fetch
               return get(e.conflicting_resource_id)
-            else
-              raise ArgumentError, 'Unknown mode for :on_idempotency_conflict'
             end
           end
 
@@ -190,7 +184,7 @@ module GoCardlessPro
       # it to fulfil, executing the payment.
       # Example URL: /billing_requests/:identity/actions/fulfil
       #
-      # @param identity       # Unique identifier, beginning with "PY".
+      # @param identity       # Unique identifier, beginning with "BRQ".
       # @param options [Hash] parameters as a hash, under a params key.
       def fulfil(identity, options = {})
         path = sub_url('/billing_requests/:identity/actions/fulfil', 'identity' => identity)
@@ -213,8 +207,45 @@ module GoCardlessPro
               raise IdempotencyConflict, e.error
             when :fetch
               return get(e.conflicting_resource_id)
-            else
-              raise ArgumentError, 'Unknown mode for :on_idempotency_conflict'
+            end
+          end
+
+          raise e
+        end
+
+        return if response.body.nil?
+
+        Resources::BillingRequest.new(unenvelope_body(response.body), response)
+      end
+
+      # This is needed when you have mandate_request. As a scheme compliance rule we
+      # are required to
+      # allow the payer to crosscheck the details entered by them and confirm it.
+      # Example URL: /billing_requests/:identity/actions/confirm_payer_details
+      #
+      # @param identity       # Unique identifier, beginning with "BRQ".
+      # @param options [Hash] parameters as a hash, under a params key.
+      def confirm_payer_details(identity, options = {})
+        path = sub_url('/billing_requests/:identity/actions/confirm_payer_details', '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
+          if e.idempotent_creation_conflict?
+            case @api_service.on_idempotency_conflict
+            when :raise
+              raise IdempotencyConflict, e.error
+            when :fetch
+              return get(e.conflicting_resource_id)
             end
           end
 
@@ -230,7 +261,7 @@ module GoCardlessPro
       # to expire.
       # Example URL: /billing_requests/:identity/actions/cancel
       #
-      # @param identity       # Unique identifier, beginning with "PY".
+      # @param identity       # Unique identifier, beginning with "BRQ".
       # @param options [Hash] parameters as a hash, under a params key.
       def cancel(identity, options = {})
         path = sub_url('/billing_requests/:identity/actions/cancel', 'identity' => identity)
@@ -253,8 +284,6 @@ module GoCardlessPro
               raise IdempotencyConflict, e.error
             when :fetch
               return get(e.conflicting_resource_id)
-            else
-              raise ArgumentError, 'Unknown mode for :on_idempotency_conflict'
             end
           end
 
@@ -271,7 +300,7 @@ module GoCardlessPro
       # Currently, the customer can only be notified by email.
       # Example URL: /billing_requests/:identity/actions/notify
       #
-      # @param identity       # Unique identifier, beginning with "PY".
+      # @param identity       # Unique identifier, beginning with "BRQ".
       # @param options [Hash] parameters as a hash, under a params key.
       def notify(identity, options = {})
         path = sub_url('/billing_requests/:identity/actions/notify', 'identity' => identity)
@@ -294,8 +323,6 @@ module GoCardlessPro
               raise IdempotencyConflict, e.error
             when :fetch
               return get(e.conflicting_resource_id)
-            else
-              raise ArgumentError, 'Unknown mode for :on_idempotency_conflict'
             end
           end
 

data/lib/gocardless_pro/services/creditor_bank_accounts_service.rb

@@ -34,8 +34,6 @@ module GoCardlessPro
               raise IdempotencyConflict, e.error
             when :fetch
               return get(e.conflicting_resource_id)
-            else
-              raise ArgumentError, 'Unknown mode for :on_idempotency_conflict'
             end
           end
 
@@ -126,8 +124,6 @@ module GoCardlessPro
               raise IdempotencyConflict, e.error
             when :fetch
               return get(e.conflicting_resource_id)
-            else
-              raise ArgumentError, 'Unknown mode for :on_idempotency_conflict'
             end
           end
 

data/lib/gocardless_pro/services/creditors_service.rb

@@ -34,8 +34,6 @@ module GoCardlessPro
               raise IdempotencyConflict, e.error
             when :fetch
               return get(e.conflicting_resource_id)
-            else
-              raise ArgumentError, 'Unknown mode for :on_idempotency_conflict'
             end
           end
 

data/lib/gocardless_pro/services/customer_bank_accounts_service.rb

@@ -46,8 +46,6 @@ module GoCardlessPro
               raise IdempotencyConflict, e.error
             when :fetch
               return get(e.conflicting_resource_id)
-            else
-              raise ArgumentError, 'Unknown mode for :on_idempotency_conflict'
             end
           end
 
@@ -159,8 +157,6 @@ module GoCardlessPro
               raise IdempotencyConflict, e.error
             when :fetch
               return get(e.conflicting_resource_id)
-            else
-              raise ArgumentError, 'Unknown mode for :on_idempotency_conflict'
             end
           end
 

data/lib/gocardless_pro/services/customers_service.rb

@@ -34,8 +34,6 @@ module GoCardlessPro
               raise IdempotencyConflict, e.error
             when :fetch
               return get(e.conflicting_resource_id)
-            else
-              raise ArgumentError, 'Unknown mode for :on_idempotency_conflict'
             end
           end
 

data/lib/gocardless_pro/services/instalment_schedules_service.rb

@@ -52,8 +52,6 @@ module GoCardlessPro
               raise IdempotencyConflict, e.error
             when :fetch
               return get(e.conflicting_resource_id)
-            else
-              raise ArgumentError, 'Unknown mode for :on_idempotency_conflict'
             end
           end
 
@@ -102,8 +100,6 @@ module GoCardlessPro
               raise IdempotencyConflict, e.error
             when :fetch
               return get(e.conflicting_resource_id)
-            else
-              raise ArgumentError, 'Unknown mode for :on_idempotency_conflict'
             end
           end
 
@@ -212,8 +208,6 @@ module GoCardlessPro
               raise IdempotencyConflict, e.error
             when :fetch
               return get(e.conflicting_resource_id)
-            else
-              raise ArgumentError, 'Unknown mode for :on_idempotency_conflict'
             end
           end
 

data/lib/gocardless_pro/services/mandate_imports_service.rb

@@ -38,8 +38,6 @@ module GoCardlessPro
               raise IdempotencyConflict, e.error
             when :fetch
               return get(e.conflicting_resource_id)
-            else
-              raise ArgumentError, 'Unknown mode for :on_idempotency_conflict'
             end
           end
 
@@ -104,8 +102,6 @@ module GoCardlessPro
               raise IdempotencyConflict, e.error
             when :fetch
               return get(e.conflicting_resource_id)
-            else
-              raise ArgumentError, 'Unknown mode for :on_idempotency_conflict'
             end
           end
 
@@ -149,8 +145,6 @@ module GoCardlessPro
               raise IdempotencyConflict, e.error
             when :fetch
               return get(e.conflicting_resource_id)
-            else
-              raise ArgumentError, 'Unknown mode for :on_idempotency_conflict'
             end
           end
 

data/lib/gocardless_pro/services/mandates_service.rb

@@ -34,8 +34,6 @@ module GoCardlessPro
               raise IdempotencyConflict, e.error
             when :fetch
               return get(e.conflicting_resource_id)
-            else
-              raise ArgumentError, 'Unknown mode for :on_idempotency_conflict'
             end
           end
 
@@ -148,8 +146,6 @@ module GoCardlessPro
               raise IdempotencyConflict, e.error
             when :fetch
               return get(e.conflicting_resource_id)
-            else
-              raise ArgumentError, 'Unknown mode for :on_idempotency_conflict'
             end
           end
 
@@ -198,8 +194,6 @@ module GoCardlessPro
               raise IdempotencyConflict, e.error
             when :fetch
               return get(e.conflicting_resource_id)
-            else
-              raise ArgumentError, 'Unknown mode for :on_idempotency_conflict'
             end
           end
 

data/lib/gocardless_pro/services/payer_authorisations_service.rb

@@ -57,8 +57,6 @@ module GoCardlessPro
               raise IdempotencyConflict, e.error
             when :fetch
               return get(e.conflicting_resource_id)
-            else
-              raise ArgumentError, 'Unknown mode for :on_idempotency_conflict'
             end
           end
 
@@ -128,8 +126,6 @@ module GoCardlessPro
               raise IdempotencyConflict, e.error
             when :fetch
               return get(e.conflicting_resource_id)
-            else
-              raise ArgumentError, 'Unknown mode for :on_idempotency_conflict'
             end
           end
 
@@ -177,8 +173,6 @@ module GoCardlessPro
               raise IdempotencyConflict, e.error
             when :fetch
               return get(e.conflicting_resource_id)
-            else
-              raise ArgumentError, 'Unknown mode for :on_idempotency_conflict'
             end
           end
 

data/lib/gocardless_pro/services/payments_service.rb

@@ -39,8 +39,6 @@ module GoCardlessPro
               raise IdempotencyConflict, e.error
             when :fetch
               return get(e.conflicting_resource_id)
-            else
-              raise ArgumentError, 'Unknown mode for :on_idempotency_conflict'
             end
           end
 
@@ -150,8 +148,6 @@ module GoCardlessPro
               raise IdempotencyConflict, e.error
             when :fetch
               return get(e.conflicting_resource_id)
-            else
-              raise ArgumentError, 'Unknown mode for :on_idempotency_conflict'
             end
           end
 
@@ -198,8 +194,6 @@ module GoCardlessPro
               raise IdempotencyConflict, e.error
             when :fetch
               return get(e.conflicting_resource_id)
-            else
-              raise ArgumentError, 'Unknown mode for :on_idempotency_conflict'
             end
           end
 

data/lib/gocardless_pro/services/redirect_flows_service.rb

@@ -35,8 +35,6 @@ module GoCardlessPro
               raise IdempotencyConflict, e.error
             when :fetch
               return get(e.conflicting_resource_id)
-            else
-              raise ArgumentError, 'Unknown mode for :on_idempotency_conflict'
             end
           end
 
@@ -100,8 +98,6 @@ module GoCardlessPro
               raise IdempotencyConflict, e.error
             when :fetch
               return get(e.conflicting_resource_id)
-            else
-              raise ArgumentError, 'Unknown mode for :on_idempotency_conflict'
             end
           end
 

data/lib/gocardless_pro/services/refunds_service.rb

@@ -50,8 +50,6 @@ module GoCardlessPro
               raise IdempotencyConflict, e.error
             when :fetch
               return get(e.conflicting_resource_id)
-            else
-              raise ArgumentError, 'Unknown mode for :on_idempotency_conflict'
             end
           end
 

data/lib/gocardless_pro/services/scenario_simulators_service.rb

@@ -27,6 +27,11 @@ module GoCardlessPro
       # <li>`creditor_verification_status_successful`: Sets a creditor's
       # `verification status` to `successful`, meaning that the creditor is
       # fully verified and can receive payouts.</li>
+      # <li>`payment_confirmed`: Transitions a payment through to `confirmed`.
+      # It must start in the `pending_submission` state, and its mandate must be
+      # in the `activated` state (unless it is a payment for ACH, BECS, BECS_NZ
+      # or SEPA, in which cases the mandate may be `pending_submission`, since
+      # their mandates are submitted with their first payment).</li>
       # <li>`payment_paid_out`: Transitions a payment through to `paid_out`,
       # having been collected successfully and paid out to you. It must start in
       # the `pending_submission` state, and its mandate must be in the
@@ -82,8 +87,8 @@ module GoCardlessPro
       # <li>`mandate_failed`: Transitions a mandate through to `failed`, having
       # been submitted to the banks but found to be invalid (for example due to
       # invalid bank details). It must start in the `pending_submission` or
-      # `submitted` states. Not compatible with ACH, BECS, BECS_NZ and SEPA
-      # mandates, which are submitted with their first payment.</li>
+      # `submitted` states. Not compatible with SEPA mandates, which are
+      # submitted with their first payment.</li>
       # <li>`mandate_expired`: Transitions a mandate through to `expired`,
       # having been submitted to the banks, set up successfully and then expired
       # because no collection attempts were made against it for longer than the
@@ -104,14 +109,31 @@ module GoCardlessPro
       # mandates.</li>
       # <li>`refund_paid`: Transitions a refund to `paid`. It must start in
       # either the `pending_submission` or `submitted` state.</li>
+      # <li>`refund_settled`: Transitions a refund to `paid`, if it's not
+      # already, then generates a payout that includes the refund, thereby
+      # settling the funds. It must start in one of `pending_submission`,
+      # `submitted` or `paid` states.</li>
       # <li>`refund_bounced`: Transitions a refund to `bounced`. It must start
       # in either the `pending_submission`, `submitted`, or `paid` state.</li>
+      # <li>`refund_returned`: Transitions a refund to `refund_returned`. The
+      # refund must start in `pending_submission`.</li>
       # <li>`payout_bounced`: Transitions a payout to `bounced`. It must start
       # in the `paid` state.</li>
-      # <li>`payout_create`: Creates a payout containing payments in
-      # `confirmed`, `failed` & `charged_back` states; refunds in `submitted` &
-      # `bounced`; and all related fees. Can only be used with a positive total
-      # payout balance and when some eligible items exist.</li>
+      # <li>`billing_request_fulfilled`: Authorises the billing request, fulfils
+      # it, and moves the associated payment to `failed`. The billing request
+      # must be in the `pending` state, with all actions completed except for
+      # `bank_authorisation`. Only billing requests with a `payment_request` are
+      # supported.</li>
+      # <li>`billing_request_fulfilled_and_payment_failed`: Authorises the
+      # billing request, fulfils it, and moves the associated payment to
+      # `failed`. The billing request must be in the `pending` state, with all
+      # actions completed except for `bank_authorisation`. Only billing requests
+      # with a `payment_request` are supported.</li>
+      # <li>`billing_request_fulfilled_and_payment_paid_out`: Authorises the
+      # billing request, fulfils it, and moves the associated payment to
+      # `paid_out`. The billing request must be in the `pending` state, with all
+      # actions completed except for `bank_authorisation`. Only billing requests
+      # with a `payment_request` are supported.</li>
       # </ul>
       # @param options [Hash] parameters as a hash, under a params key.
       def run(identity, options = {})

data/lib/gocardless_pro/services/subscriptions_service.rb

@@ -34,8 +34,6 @@ module GoCardlessPro
               raise IdempotencyConflict, e.error
             when :fetch
               return get(e.conflicting_resource_id)
-            else
-              raise ArgumentError, 'Unknown mode for :on_idempotency_conflict'
             end
           end
 
@@ -140,10 +138,10 @@ module GoCardlessPro
       # Pause a subscription object.
       # No payments will be created until it is resumed.
       #
-      # This can only be used when a subscription collecting a fixed number of
+      # This can only be used when a subscription is collecting a fixed number of
       # payments (created using `count`),
       # when they continue forever (created without `count` or `end_date`) or
-      # the subscription is paused for a number of cycles.
+      # 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.
@@ -203,8 +201,6 @@ module GoCardlessPro
               raise IdempotencyConflict, e.error
             when :fetch
               return get(e.conflicting_resource_id)
-            else
-              raise ArgumentError, 'Unknown mode for :on_idempotency_conflict'
             end
           end
 
@@ -258,8 +254,6 @@ module GoCardlessPro
               raise IdempotencyConflict, e.error
             when :fetch
               return get(e.conflicting_resource_id)
-            else
-              raise ArgumentError, 'Unknown mode for :on_idempotency_conflict'
             end
           end
 
@@ -302,8 +296,6 @@ module GoCardlessPro
               raise IdempotencyConflict, e.error
             when :fetch
               return get(e.conflicting_resource_id)
-            else
-              raise ArgumentError, 'Unknown mode for :on_idempotency_conflict'
             end
           end