Class: GoCardless::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/gocardless/client.rb

Constant Summary collapse

BASE_URLS =
{
  :production => 'https://gocardless.com',
  :sandbox    => 'https://sandbox.gocardless.com',
}
API_PATH =
'/api/v1'

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(args = {}) ⇒ Client

Returns a new instance of Client.

Raises:


27
28
29
30
31
32
33
34
35
36
37
38
39
40
# File 'lib/gocardless/client.rb', line 27

def initialize(args = {})
  Utils.symbolize_keys! args
  @app_id = args.fetch(:app_id) { ENV['GOCARDLESS_APP_ID'] }
  @app_secret = args.fetch(:app_secret) { ENV['GOCARDLESS_APP_SECRET'] }
  raise ClientError.new("You must provide an app_id") unless @app_id
  raise ClientError.new("You must provide an app_secret") unless @app_secret

  @oauth_client = OAuth2::Client.new(@app_id, @app_secret,
                                     :site => self.base_url,
                                     :token_url => '/oauth/access_token')

  self.access_token = args[:token] if args[:token]
  @merchant_id = args[:merchant_id] if args[:merchant_id]
end

Instance Attribute Details

#merchant_idObject

Return the merchant id, throwing a proper error if it's missing.

Raises:


123
124
125
126
# File 'lib/gocardless/client.rb', line 123

def merchant_id
  raise ClientError, 'No merchant id set' unless @merchant_id
  @merchant_id
end

Class Method Details

.base_urlObject


22
23
24
# File 'lib/gocardless/client.rb', line 22

def base_url
  @base_url || BASE_URLS[GoCardless.environment || :production]
end

.base_url=(url) ⇒ Object


18
19
20
# File 'lib/gocardless/client.rb', line 18

def base_url=(url)
  @base_url = url.sub(%r|/$|, '')
end

Instance Method Details

#access_tokenObject


81
82
83
84
85
86
87
# File 'lib/gocardless/client.rb', line 81

def access_token
  warn "[DEPRECATION] (gocardless-ruby) the behaviour of " +
       "Client#access_token is deprecated. In future releases it will " +
       "return the unscoped access token. If you want the scoped access " +
       "token, use 'scoped_access_token'"
  self.scoped_access_token
end

#access_token=(token) ⇒ Object

Set the client's access token

Parameters:

  • token (String)

    a string with format "#{token}" (as returned by #access_token)


105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
# File 'lib/gocardless/client.rb', line 105

def access_token=(token)
  token, scope = token.sub(/^bearer\s+/i, '').split(' ', 2)
  if scope
    warn "[DEPRECATION] (gocardless-ruby) merchant_id is now a separate " +
         "attribute, the manage_merchant scope should no longer be " +
         "included in the 'token' attribute. See http://git.io/G9y37Q " +
         "for more info."
  else
    scope = ''
  end

  @access_token = OAuth2::AccessToken.new(@oauth_client, token)
  @access_token.params['scope'] = scope

  set_merchant_id_from_scope(scope) unless @merchant_id
end

#api_delete(path, data = {}) ⇒ Hash

Note:

this method is for internal use

Issue a DELETE request to the API server

Parameters:

  • path (String)

    the path that will be added to the API prefix

  • data (Hash) (defaults to: {})

    a hash of data that will be sent as the request body

Returns:

  • (Hash)

    hash the parsed response data


166
167
168
# File 'lib/gocardless/client.rb', line 166

def api_delete(path, data = {})
  api_request(:delete, path, :data => data).parsed
end

#api_get(path, params = {}) ⇒ Hash

Note:

this method is for internal use

Issue an GET request to the API server

Parameters:

  • path (String)

    the path that will be added to the API prefix

  • params (Hash) (defaults to: {})

    query string parameters

Returns:

  • (Hash)

    hash the parsed response data


136
137
138
# File 'lib/gocardless/client.rb', line 136

def api_get(path, params = {})
  api_request(:get, path, :params => params).parsed
end

#api_post(path, data = {}) ⇒ Hash

Note:

this method is for internal use

Issue a POST request to the API server

Parameters:

  • path (String)

    the path that will be added to the API prefix

  • data (Hash) (defaults to: {})

    a hash of data that will be sent as the request body

Returns:

  • (Hash)

    hash the parsed response data


146
147
148
# File 'lib/gocardless/client.rb', line 146

def api_post(path, data = {})
  api_request(:post, path, :data => data).parsed
end

#api_put(path, data = {}) ⇒ Hash

Note:

this method is for internal use

Issue a PUT request to the API server

Parameters:

  • path (String)

    the path that will be added to the API prefix

  • data (Hash) (defaults to: {})

    a hash of data that will be sent as the request body

Returns:

  • (Hash)

    hash the parsed response data


156
157
158
# File 'lib/gocardless/client.rb', line 156

def api_put(path, data = {})
  api_request(:put, path, :data => data).parsed
end

#api_request(method, path, opts = {}) ⇒ Object

Note:

this method is for internal use

Issue a request to the API server, returning the full response

Parameters:

  • method (Symbol)

    the HTTP method to use (e.g. :get, :post)

  • path (String)

    the path that will be added to the API prefix

  • [Hash] (Hash)

    a customizable set of options


177
178
179
# File 'lib/gocardless/client.rb', line 177

def api_request(method, path, opts = {})
  request(method, "#{API_PATH}#{path}", opts)
end

#api_urlObject


329
330
331
# File 'lib/gocardless/client.rb', line 329

def api_url
  "#{base_url}#{API_PATH}"
end

#authorize_url(options) ⇒ String Also known as: new_merchant_url

Generate the OAuth authorize url

Parameters:

  • options (Hash)

    parameters to be included in the url. :redirect_uri is required.

Returns:

  • (String)

    the authorize url

Raises:

  • (ArgumentError)

47
48
49
50
51
52
53
54
55
56
57
# File 'lib/gocardless/client.rb', line 47

def authorize_url(options)
  raise ArgumentError, ':redirect_uri required' unless options[:redirect_uri]
  params = {
    :client_id => @app_id,
    :response_type => 'code',
    :scope => 'manage_merchant'
  }
  # Faraday doesn't flatten params in this case (Faraday issue #115)
  options = Hash[Utils.flatten_params(options)]
  @oauth_client.authorize_url(params.merge(options))
end

#base_urlObject

Get the base URL for the client. If set manually for the instance, that URL will be returned. Otherwise, it will be deferred to Client.base_url.


325
326
327
# File 'lib/gocardless/client.rb', line 325

def base_url
  @base_url || self.class.base_url
end

#base_url=(url) ⇒ Object

Set the base URL for this client instance. Overrides all other settings (setting the environment globally, setting the Client class's base URL).

Parameters:

  • url (String)

    the base URL to use


318
319
320
# File 'lib/gocardless/client.rb', line 318

def base_url=(url)
  @base_url = url
end

#bill(id) ⇒ Bill

Returns the Bill matching the id requested.

Parameters:

  • id (String)

    of the bill

Returns:

  • (Bill)

    the Bill matching the id requested


212
213
214
# File 'lib/gocardless/client.rb', line 212

def bill(id)
  Bill.find_with_client(self, id)
end

#confirm_resource(params) ⇒ Resource

Confirm a newly-created subscription, pre-authorzation or one-off bill. This method also checks that the resource response data includes a valid signature and will raise a SignatureError if the signature is invalid.

Parameters:

  • params (Hash)

    the response parameters returned by the API server

Returns:

  • (Resource)

    the confirmed resource object


269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
# File 'lib/gocardless/client.rb', line 269

def confirm_resource(params)
  params = prepare_params(params)

  if signature_valid?(params)
    data = {
      :resource_id => params[:resource_id],
      :resource_type => params[:resource_type],
    }

    credentials = Base64.encode64("#{@app_id}:#{@app_secret}")
    credentials = credentials.gsub(/\s/, '')
    headers = {
      'Authorization' => "Basic #{credentials}"
    }
    request(:post, "#{api_url}/confirm", :data => data,
                                              :headers => headers)

    # Initialize the correct class according to the resource's type
    klass = GoCardless.const_get(Utils.camelize(params[:resource_type]))
    klass.find_with_client(self, params[:resource_id])
  else
    raise SignatureError, 'An invalid signature was detected'
  end
end

#create_bill(attrs) ⇒ Bill

Create a new bill under a given pre-authorization pre_authorization you want to bill from) and :amount

Parameters:

  • attrs (Hash)

    must include :source_id (the id of the

Returns:

  • (Bill)

    the created bill object

See Also:


222
223
224
# File 'lib/gocardless/client.rb', line 222

def create_bill(attrs)
  Bill.new_with_client(self, attrs).save
end

#fetch_access_token(auth_code, options) ⇒ String

Exchange the authorization code for an access token

Parameters:

  • auth_code (String)

    to exchange for the access_token

Returns:

  • (String)

    the access_token required to make API calls to resources

Raises:

  • (ArgumentError)

64
65
66
67
68
69
70
71
72
73
74
# File 'lib/gocardless/client.rb', line 64

def fetch_access_token(auth_code, options)
  raise ArgumentError, ':redirect_uri required' unless options[:redirect_uri]
  # Exchange the auth code for an access token
  @access_token = @oauth_client.auth_code.get_token(auth_code, options)

  # Use the scope to figure out which merchant we're managing
  scope = @access_token.params[:scope] || @access_token.params['scope']
  set_merchant_id_from_scope(scope)

  self.scoped_access_token
end

#merchantMerchant

Returns the merchant associated with the client's access token.

Returns:

  • (Merchant)

    the merchant associated with the client's access token

Raises:


183
184
185
186
# File 'lib/gocardless/client.rb', line 183

def merchant
  raise ClientError, 'Access token missing' unless @access_token
  Merchant.new_with_client(self, api_get("/merchants/#{merchant_id}"))
end

#new_bill_url(params) ⇒ String

Generate the URL for creating a new bill. The parameters passed in define various attributes of the bill. Redirecting a user to the resulting URL will show them a page where they can approve or reject the bill described by the parameters. Note that this method automatically includes the nonce, timestamp and signature.

Parameters:

  • params (Hash)

    the bill parameters

Returns:

  • (String)

    the generated URL


258
259
260
# File 'lib/gocardless/client.rb', line 258

def new_bill_url(params)
  new_limit_url(:bill, params)
end

#new_pre_authorization_url(params) ⇒ String

Generate the URL for creating a new pre authorization. The parameters passed in define various attributes of the pre authorization. Redirecting a user to the resulting URL will show them a page where they can approve or reject the pre authorization described by the parameters. Note that this method automatically includes the nonce, timestamp and signature.

Parameters:

  • params (Hash)

    the pre authorization parameters

Returns:

  • (String)

    the generated URL


246
247
248
# File 'lib/gocardless/client.rb', line 246

def new_pre_authorization_url(params)
  new_limit_url(:pre_authorization, params)
end

#new_subscription_url(params) ⇒ String

Generate the URL for creating a new subscription. The parameters passed in define various attributes of the subscription. Redirecting a user to the resulting URL will show them a page where they can approve or reject the subscription described by the parameters. Note that this method automatically includes the nonce, timestamp and signature.

Parameters:

  • params (Hash)

    the subscription parameters

Returns:

  • (String)

    the generated URL


234
235
236
# File 'lib/gocardless/client.rb', line 234

def new_subscription_url(params)
  new_limit_url(:subscription, params)
end

#pre_authorization(id) ⇒ PreAuthorization

Returns the pre_authorization matching the id requested.

Parameters:

  • id (String)

    of the pre_authorization

Returns:


198
199
200
# File 'lib/gocardless/client.rb', line 198

def pre_authorization(id)
  PreAuthorization.find_with_client(self, id)
end

#response_params_valid?(params) ⇒ Boolean

Check that resource response data includes a valid signature.

Parameters:

  • params (Hash)

    the response parameters returned by the API server

Returns:

  • (Boolean)

    true when valid, false otherwise


299
300
301
302
303
# File 'lib/gocardless/client.rb', line 299

def response_params_valid?(params)
  params = prepare_params(params)

  signature_valid?(params)
end

#scopeString

Returns the scope of the current access token.

Returns:

  • (String)

    the scope of the current access token


95
96
97
98
99
# File 'lib/gocardless/client.rb', line 95

def scope
  if @access_token
    @access_token.params[:scope] || @access_token.params['scope']
  end
end

#scoped_access_tokenString

Returns a serialized form of the access token with its scope.

Returns:

  • (String)

    a serialized form of the access token with its scope


77
78
79
# File 'lib/gocardless/client.rb', line 77

def scoped_access_token
  "#{self.unscoped_access_token} #{self.scope}".strip if @access_token
end

#subscription(id) ⇒ Subscription

Returns the subscription matching the id requested.

Parameters:

  • id (String)

    of the subscription

Returns:

  • (Subscription)

    the subscription matching the id requested


191
192
193
# File 'lib/gocardless/client.rb', line 191

def subscription(id)
  Subscription.find_with_client(self, id)
end

#subscripton(id) ⇒ Subscription

Returns the subscription matching the id requested.

Parameters:

  • id (String)

    of the subscription

Returns:

  • (Subscription)

    the subscription matching the id requested


191
192
193
# File 'lib/gocardless/client.rb', line 191

def subscription(id)
  Subscription.find_with_client(self, id)
end

#unscoped_access_tokenString

Returns a serialized form of the access token without its scope.

Returns:

  • (String)

    a serialized form of the access token without its scope


90
91
92
# File 'lib/gocardless/client.rb', line 90

def unscoped_access_token
  @access_token.token if @access_token
end

#user(id) ⇒ User

Returns the User matching the id requested.

Parameters:

  • id (String)

    of the user

Returns:

  • (User)

    the User matching the id requested


205
206
207
# File 'lib/gocardless/client.rb', line 205

def user(id)
  User.find_with_client(self, id)
end

#user_agentObject


333
334
335
336
337
338
339
340
341
342
343
344
# File 'lib/gocardless/client.rb', line 333

def user_agent
  @user_agent ||=
    begin
      gem_info = "gocardless-ruby/v#{GoCardless::VERSION}"
      ruby_engine = defined?(RUBY_ENGINE) ? RUBY_ENGINE : 'ruby'
      ruby_version = RUBY_VERSION
      ruby_version += " p#{RUBY_PATCHLEVEL}" if defined?(RUBY_PATCHLEVEL)
      comment = ["#{ruby_engine} #{ruby_version}"]
      comment << RUBY_PLATFORM if defined?(RUBY_PLATFORM)
      "#{gem_info} (#{comment.join("; ")})"
    end
end

#webhook_valid?(params) ⇒ Boolean

Validates the payload contents of a webhook request.

Parameters:

  • params (Hash)

    the contents of payload of the webhook

Returns:

  • (Boolean)

    true when valid, false otherwise


310
311
312
# File 'lib/gocardless/client.rb', line 310

def webhook_valid?(params)
  signature_valid?(params)
end