class GoCardlessPro::Services::BillingRequestsService
Service for making requests to the BillingRequest endpoints
Public Instance Methods
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.
# File lib/gocardless_pro/services/billing_requests_service.rb, line 35 def all(options = {}) Paginator.new( service: self, options: options ).enumerator end
Immediately cancels a billing request, causing all billing request flows to expire. Example URL: /billing_requests/:identity/actions/cancel
@param identity # Unique identifier, beginning with “BRQ”. @param options [Hash] parameters as a hash, under a params key.
# File lib/gocardless_pro/services/billing_requests_service.rb, line 266 def cancel(identity, options = {}) path = sub_url('/billing_requests/: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 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 raise e end return if response.body.nil? Resources::BillingRequest.new(unenvelope_body(response.body), response) end
If the billing request has a pending collect_bank_account
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
@param identity # Unique identifier, beginning with “BRQ”. @param options [Hash] parameters as a hash, under a params key.
# File lib/gocardless_pro/services/billing_requests_service.rb, line 151 def collect_bank_account(identity, options = {}) path = sub_url('/billing_requests/:identity/actions/collect_bank_account', '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 raise e end return if response.body.nil? Resources::BillingRequest.new(unenvelope_body(response.body), response) end
If the billing request has a pending collect_customer_details
action, this endpoint can be used to collect the details in order to complete it.
The endpoint takes the same payload as Customers, but checks that the customer fields are populated correctly for the billing request scheme.
Whatever is provided to this endpoint is used to update the referenced customer, and will take effect immediately after the request is successful. Example URL: /billing_requests/:identity/actions/collect_customer_details
@param identity # Unique identifier, beginning with “BRQ”. @param options [Hash] parameters as a hash, under a params key.
# File lib/gocardless_pro/services/billing_requests_service.rb, line 108 def collect_customer_details(identity, options = {}) path = sub_url('/billing_requests/:identity/actions/collect_customer_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 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.
# File lib/gocardless_pro/services/billing_requests_service.rb, line 228 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 raise e end return if response.body.nil? Resources::BillingRequest.new(unenvelope_body(response.body), response) end
Example URL: /billing_requests @param options [Hash] parameters as a hash, under a params key.
# File lib/gocardless_pro/services/billing_requests_service.rb, line 45 def create(options = {}) path = '/billing_requests' 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 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 raise e end return if response.body.nil? Resources::BillingRequest.new(unenvelope_body(response.body), response) end
If a billing request is ready to be fulfilled, call this endpoint to cause it to fulfil, executing the payment. Example URL: /billing_requests/:identity/actions/fulfil
@param identity # Unique identifier, beginning with “BRQ”. @param options [Hash] parameters as a hash, under a params key.
# File lib/gocardless_pro/services/billing_requests_service.rb, line 189 def fulfil(identity, options = {}) path = sub_url('/billing_requests/:identity/actions/fulfil', '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 raise e end return if response.body.nil? Resources::BillingRequest.new(unenvelope_body(response.body), response) end
Fetches a billing request Example URL: /billing_requests/:identity
@param identity # Unique identifier, beginning with “BRQ”. @param options [Hash] parameters as a hash, under a params key.
# File lib/gocardless_pro/services/billing_requests_service.rb, line 82 def get(identity, options = {}) path = sub_url('/billing_requests/:identity', 'identity' => identity) options[:retry_failures] = true response = make_request(:get, path, options) return if response.body.nil? Resources::BillingRequest.new(unenvelope_body(response.body), response) end
Returns a [cursor-paginated](api-usage-cursor-pagination) list of your billing_requests. Example URL: /billing_requests @param options [Hash] parameters as a hash, under a params key.
# File lib/gocardless_pro/services/billing_requests_service.rb, line 17 def list(options = {}) path = '/billing_requests' options[:retry_failures] = true response = make_request(:get, path, options) ListResponse.new( response: response, unenveloped_body: unenvelope_body(response.body), resource_class: Resources::BillingRequest ) end
Notifies the customer linked to the billing request, asking them to authorise it. Currently, the customer can only be notified by email. Example URL: /billing_requests/:identity/actions/notify
@param identity # Unique identifier, beginning with “BRQ”. @param options [Hash] parameters as a hash, under a params key.
# File lib/gocardless_pro/services/billing_requests_service.rb, line 305 def notify(identity, options = {}) path = sub_url('/billing_requests/:identity/actions/notify', '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 raise e end return if response.body.nil? Resources::BillingRequest.new(unenvelope_body(response.body), response) end
Private Instance Methods
return the key which API responses will envelope data under
# File lib/gocardless_pro/services/billing_requests_service.rb, line 347 def envelope_key 'billing_requests' end
Unenvelope the response of the body using the service's `envelope_key`
@param body [Hash]
# File lib/gocardless_pro/services/billing_requests_service.rb, line 342 def unenvelope_body(body) body[envelope_key] || body['data'] end