Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 152 lines (110 sloc) 6.373 kb
43addcbd » hmarr
2011-08-08 Moved README from rdoc to markdown
1 # GoCardless Ruby API
2
3 ## Introduction
4
5 This library provides a simple Ruby wrapper around the GoCardless REST API. To
6 use the API, you will need a GoCardless app id and app secret. To start with,
7 you'll need to create an instance of the {GoCardless::Client} class, providing
8 your app id and app secret as arguments to the constructor:
9
10 client = GoCardless::Client(APP_ID, APP_SECRET)
11
12 ## Setting up an Access Token
13
14 To retrieve data from the API, an access token is required. An access token
15 corresponds to a single merchant account, and give an app permission to access
16 and modify the merchant's data via the API. Multiple merchant accounts may be
17 accessed by using different access tokens.
18
19 ### Obtaining a new Access Token
20
21 ![Authorization Flow](http://i.imgur.com/sSgTy.png)
22
23 If you don't already have an access token stored, you will need the owner of a
24 merchant account to authorize your app via the web interface. Once they have
25 authorized your app, they will be redirected back to your website with an
26 authorization code. This code should then be exchanged for an access token,
27 which may be used to make authenticated requests against the API. The
28 {GoCardless::Client client} object can be used to generate the authorize url:
29
30 auth_url = client.authorize_url(:redirect_uri => 'http://mywebsite.com/cb')
31 redirect_to auth_url
32
33 The `redirect_uri` parameter specifies where the merchant account owner should
34 be sent after they have authorized your app. When the user is sent to this url,
35 the authorization code will be present as a query parameter named +code+. You
36 can use the {GoCardless::Client client} object to exchange this code for an
37 access token. Note that you must also provide the same `redirect_uri` used in
38 the previous step:
39
40 auth_code = params[:code]
41 client.fetch_access_token(auth_code, :redirect_uri => 'http://mywebsite.com/cb')
42
43 You can access a serialized version of the access token using the
44 {GoCardless::Client#access_token access\_token} attribute on the
45 {GoCardless::Client client} object. This should be stored alongside the
46 merchant for later use:
47
48 merchant = Merchant.new(:name => session[:merchant_name],
49 :token => client.access_token)
50 merchant.save!
51
52 ### Using an existing Access Token
53
54 To use a stored access token, just set the `access_token` attribute of a
55 {GoCardless::Client client} object to the stored token value, or initialize the
56 client object with the token as the third argument:
57
58 client.access_token = Merchant.find(123).token
59
60 ## Retrieving Data from the API
61
62 Once your {GoCardless::Client client} has a valid access token, you may request
63 data about the merchant associated with the token. To access the merchant's
64 information, use the `merchant` attribute on the client object. This returns an
65 instance of {GoCardless::Merchant}:
66
67 merchant = client.merchant # => <GoCardless::Merchant ...>
68 merchant.name # => "Harry's Burritos"
69
70 The {GoCardless::Merchant merchant} object also provides access to related
71 data, such as {GoCardless::Bill bills}, {GoCardless::Subscription
72 subscriptions} and {GoCardless::PreAuthorization pre-authorizations}:
73
74 merchant.bills # => [<GoCardless::Bill>, ...]
75 merchant.subscriptions # => [<GoCardless::Subscription>, ...]
76 merchant.pre_authorizations # => [<GoCardless::PreAuthorization>, ...]
77
78 These may also be filtered with various parameters:
79
80 merchant.bills(:paid => true) # Only fetches paid bills
81 merchant.subscriptions(:user_id => 1) # User 1's subscriptions
82
83 Note that each time you use the {GoCardless::Client#merchant merchant}
84 attribute of {GoCardless::Client}, an API call will be made. So to prevent many
85 of unnecessary slow calls to the API server from being made, assign the
86 {GoCardless::Merchant merchant} object to a variable and use that:
87
88 # Rather than this (6 API calls):
89 client.merchant.bills
90 client.merchant.subscriptions
91 client.merchant.pre_authorizations
92
93 # Do this (4 API calls):
94 merchant = client.merchant
95 merchant.bills
96 merchant.subscriptions
97 merchant.pre_authorizations
98
99 To lookup instances of each resource type by id, accessor methods are provided
100 on {GoCardless::Client client} objects:
101
102 client.subscription(5) # => <GoCardless::Subscription ...>
103 client.payment(10) # => <GoCardless::Payment ...>
104
105 ## Creating and modifying bills
106
107 The GoCardless API may also be used to create and modify bills. Bills must be
108 created on a pre authorization. To create a bill, use the
109 {GoCardless::PreAuthorization#create_bill create\_bill} method on
110 {GoCardless::PreAuthorization PreAuthorization} objects, providing the amount
111 in pence as the only argument:
112
113 bill = pre_authorization.create_bill(150) # => <GoCardless::Bill ...>
114
115 To modify the bill, alter the attributes and call the
116 {GoCardless::Resource#save save} method:
117
118 bill.amount = 250
119 bill.save
120
121 ## Example usage
122 require 'gocardless'
123
124 # These are found in the GoCardless app admin interface
125 APP_ID = '3QmpV5yi8Ii9Rc2uCwalWRsqkpibtk5ISOk/F+oyzrOoNpjGguZ4IRn2379agARS'
126 APP_SECRET = '8oCITH2AVhaUYqJ+5hjyt8JUlSo5m/WTYLH8E/GO+TrBWdRK45lvoRt/zetr+t5Y'
127
128 # Create a new instance of the GoCardless API client
129 client = GoCardless::Client.new(app_id, app_secret)
130
131 # Generate the OAuth 'authorize endpoint' URL
132 client.authorize_url(:redirect_uri => 'http://mywebsite.com/cb')
133
134 # Once the authorization code has been retrieved, exchange it for an access token
135 auth_code = params[:auth_code]
136 client.fetch_access_token(auth_code, :redirect_uri => 'http://mywebsite.com/cb')
137
138 # The API client will associated with a merchant account
139 client.merchant # => <GoCardless::Merchant ...>
140
141 # The client allows you to look up most resources by their id
142 client.subscription(5) # => <GoCardless::Subscription ...>
143 client.pre_authorization(5) # => <GoCardless::PreAuthorization ...>
144 client.bill(5) # => <GoCardless::Bill ...>
145 client.payment(5) # => <GoCardless::Payment ...>
146
147 # Retrieve referenced resources directly from resource objects
148 subscription = client.subscription(5)
149 subscription.merchant # => <GoCardless::Merchant ...>
150
151 # Create a new bill
152 client.merchant.pre_authorizations.first.create_bill(500) # £5.00 bill
Something went wrong with that request. Please try again.