class GoCardlessPro::Services::MandatesService

Service for making requests to the Mandate endpoints

Public Instance Methods

all(options = {}) click to toggle source

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/mandates_service.rb, line 70
def all(options = {})
  Paginator.new(
    service: self,
    options: options
  ).enumerator
end
cancel(identity, options = {}) click to toggle source

Immediately cancels a mandate and all associated cancellable payments. Any 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. Example URL: /mandates/:identity/actions/cancel

@param identity # Unique identifier, beginning with “MD”. Note that this prefix may not apply to mandates created before 2016. @param options [Hash] parameters as a hash, under a params key.

# File lib/gocardless_pro/services/mandates_service.rb, line 128
def cancel(identity, options = {})
  path = sub_url('/mandates/: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::Mandate.new(unenvelope_body(response.body), response)
end
create(options = {}) click to toggle source

Creates a new mandate object. Example URL: /mandates @param options [Hash] parameters as a hash, under a params key.

# File lib/gocardless_pro/services/mandates_service.rb, line 16
def create(options = {})
  path = '/mandates'

  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::Mandate.new(unenvelope_body(response.body), response)
end
get(identity, options = {}) click to toggle source

Retrieves the details of an existing mandate. Example URL: /mandates/:identity

@param identity # Unique identifier, beginning with “MD”. Note that this prefix may not apply to mandates created before 2016. @param options [Hash] parameters as a hash, under a params key.

# File lib/gocardless_pro/services/mandates_service.rb, line 83
def get(identity, options = {})
  path = sub_url('/mandates/:identity', 'identity' => identity)

  options[:retry_failures] = true

  response = make_request(:get, path, options)

  return if response.body.nil?

  Resources::Mandate.new(unenvelope_body(response.body), response)
end
list(options = {}) click to toggle source

Returns a [cursor-paginated](api-usage-cursor-pagination) list of your mandates. Example URL: /mandates @param options [Hash] parameters as a hash, under a params key.

# File lib/gocardless_pro/services/mandates_service.rb, line 52
def list(options = {})
  path = '/mandates'

  options[:retry_failures] = true

  response = make_request(:get, path, options)

  ListResponse.new(
    response: response,
    unenveloped_body: unenvelope_body(response.body),
    resource_class: Resources::Mandate
  )
end
reinstate(identity, options = {}) click to toggle source

<a name=“mandate_not_inactive”></a>Reinstates a cancelled or expired mandate to the banks. You will receive a `resubmission_requested` webhook, but after that reinstating the mandate follows the same process as its initial creation, so you will receive a `submitted` webhook, followed by a `reinstated` or `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.

Mandates can be resubmitted up to 10 times. Example URL: /mandates/:identity/actions/reinstate

@param identity # Unique identifier, beginning with “MD”. Note that this prefix may not apply to mandates created before 2016. @param options [Hash] parameters as a hash, under a params key.

# File lib/gocardless_pro/services/mandates_service.rb, line 176
def reinstate(identity, options = {})
  path = sub_url('/mandates/:identity/actions/reinstate', '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::Mandate.new(unenvelope_body(response.body), response)
end
update(identity, options = {}) click to toggle source

Updates a mandate object. This accepts only the metadata parameter. Example URL: /mandates/:identity

@param identity # Unique identifier, beginning with “MD”. Note that this prefix may not apply to mandates created before 2016. @param options [Hash] parameters as a hash, under a params key.

# File lib/gocardless_pro/services/mandates_service.rb, line 101
def update(identity, options = {})
  path = sub_url('/mandates/:identity', 'identity' => identity)

  params = options.delete(:params) || {}
  options[:params] = {}
  options[:params][envelope_key] = params

  options[:retry_failures] = true

  response = make_request(:put, path, options)

  return if response.body.nil?

  Resources::Mandate.new(unenvelope_body(response.body), response)
end

Private Instance Methods

envelope_key() click to toggle source

return the key which API responses will envelope data under

# File lib/gocardless_pro/services/mandates_service.rb, line 218
def envelope_key
  'mandates'
end
unenvelope_body(body) click to toggle source

Unenvelope the response of the body using the service's `envelope_key`

@param body [Hash]

# File lib/gocardless_pro/services/mandates_service.rb, line 213
def unenvelope_body(body)
  body[envelope_key] || body['data']
end