Skip to content
Newer
Older
100644 222 lines (159 sloc) 9.15 KB
b996983 @hmarr Documentation improvements
hmarr authored
1
2 # GoCardless Ruby Client
3
43addcb @hmarr Moved README from rdoc to markdown
hmarr authored
4
5 ## Introduction
6
b996983 @hmarr Documentation improvements
hmarr authored
7 The GoCardless Ruby client provides a simple Ruby interface to the GoCardless
8 API. This document covers the usage of the Ruby library, for information on the
9 structure of the API itself, or for details on particular API resources, read
10 the [API overview](../).
43addcb @hmarr Moved README from rdoc to markdown
hmarr authored
11
12
b996983 @hmarr Documentation improvements
hmarr authored
13 To use the GoCardless API, you'll need to register your app in the Developer
14 Panel. Registering an app provides you with an app ID and an app secret. These
15 are both required to access the API.
43addcb @hmarr Moved README from rdoc to markdown
hmarr authored
16
b996983 @hmarr Documentation improvements
hmarr authored
17 To start with, you'll need to create an instance of the {GoCardless::Client}
18 class, providing your app id and app secret as arguments to the constructor:
43addcb @hmarr Moved README from rdoc to markdown
hmarr authored
19
b996983 @hmarr Documentation improvements
hmarr authored
20 client = GoCardless::Client(APP_ID, APP_SECRET)
43addcb @hmarr Moved README from rdoc to markdown
hmarr authored
21
22
b996983 @hmarr Documentation improvements
hmarr authored
23 ## Linking a Merchant Account with the App
24
25 The API allows you to act on behalf of a merchant. For this to happen, the
26 merchant must give your app access to their account. This authorization process
27 results in an access token, which you may then use to act as the merchant via
28 the API. Note that an app may have access tokens for many merchant accounts.
29
30 To authorize your app the merchant must be redirected to the GoCardless
31 servers, where they will be presented with a page that allows them to link
32 their account with your app. The URL that you send the merchant to contains
33 information about your app, as well as the URL where the merchant should be
34 sent back to once they've completed the process. The Ruby client library takes
35 care of most of this for you, all you need to provide is the URL:
43addcb @hmarr Moved README from rdoc to markdown
hmarr authored
36
37 auth_url = client.authorize_url(:redirect_uri => 'http://mywebsite.com/cb')
38
b996983 @hmarr Documentation improvements
hmarr authored
39 Now you need to redirect the merchant to `auth_url`, so the merchant can give
40 your app access to their account. If the merchant hasn't already created a
41 merchant account on GoCardless, they will be prompted to do so first.
43addcb @hmarr Moved README from rdoc to markdown
hmarr authored
42
b996983 @hmarr Documentation improvements
hmarr authored
43 Once the merchant has authorized your app, they will be redirected back to the
44 URL you specified earlier (`http://mywebsite.com/cb` in the example above). The
45 API servers will include an "authorization code" as a query string parameter
46 (`code`):
43addcb @hmarr Moved README from rdoc to markdown
hmarr authored
47
b996983 @hmarr Documentation improvements
hmarr authored
48 auth_code = params[:code]
43addcb @hmarr Moved README from rdoc to markdown
hmarr authored
49
b996983 @hmarr Documentation improvements
hmarr authored
50 This authorization code may be exchanged for an access token, which may be used
51 to access the merchant's account through the API. You can use the
52 {GoCardless::Client client} object to perform the exchange. The `redirect_uri`
53 that you used in the previous step must also be provided:
43addcb @hmarr Moved README from rdoc to markdown
hmarr authored
54
b996983 @hmarr Documentation improvements
hmarr authored
55 client.fetch_access_token(auth_code, :redirect_uri => 'http://mywebsite.com/cb')
56 token = client.access_token
43addcb @hmarr Moved README from rdoc to markdown
hmarr authored
57
b996983 @hmarr Documentation improvements
hmarr authored
58 The `token` is the access token that gives your app access to the merchant's
59 account. You should store this access token alongside the merchant's record in
60 your database.
43addcb @hmarr Moved README from rdoc to markdown
hmarr authored
61
62
63 ## Retrieving Data from the API
64
b996983 @hmarr Documentation improvements
hmarr authored
65 To access the API on behalf of a merchant, you need to provide the
66 {GoCardless::Client client} object with the access token that corresponds to
67 the merchant. This may be done by assigning the token to the `access_token`
68 attribute:
69
70 client.access_token = token
71
43addcb @hmarr Moved README from rdoc to markdown
hmarr authored
72 Once your {GoCardless::Client client} has a valid access token, you may request
73 data about the merchant associated with the token. To access the merchant's
74 information, use the `merchant` attribute on the client object. This returns an
75 instance of {GoCardless::Merchant}:
76
77 merchant = client.merchant # => <GoCardless::Merchant ...>
78 merchant.name # => "Harry's Burritos"
79
80 The {GoCardless::Merchant merchant} object also provides access to related
81 data, such as {GoCardless::Bill bills}, {GoCardless::Subscription
82 subscriptions} and {GoCardless::PreAuthorization pre-authorizations}:
83
84 merchant.bills # => [<GoCardless::Bill>, ...]
85 merchant.subscriptions # => [<GoCardless::Subscription>, ...]
86 merchant.pre_authorizations # => [<GoCardless::PreAuthorization>, ...]
87
88 These may also be filtered with various parameters:
89
90 merchant.bills(:paid => true) # Only fetches paid bills
91 merchant.subscriptions(:user_id => 1) # User 1's subscriptions
92
93 Note that each time you use the {GoCardless::Client#merchant merchant}
94 attribute of {GoCardless::Client}, an API call will be made. So to prevent many
95 of unnecessary slow calls to the API server from being made, assign the
96 {GoCardless::Merchant merchant} object to a variable and use that:
97
98 # Rather than this (6 API calls):
99 client.merchant.bills
100 client.merchant.subscriptions
101 client.merchant.pre_authorizations
102
103 # Do this (4 API calls):
104 merchant = client.merchant
105 merchant.bills
106 merchant.subscriptions
107 merchant.pre_authorizations
108
109 To lookup instances of each resource type by id, accessor methods are provided
110 on {GoCardless::Client client} objects:
111
112 client.subscription(5) # => <GoCardless::Subscription ...>
113 client.payment(10) # => <GoCardless::Payment ...>
114
b996983 @hmarr Documentation improvements
hmarr authored
115
c71d4cd @hmarr Added methods for generating new limit urls
hmarr authored
116 ## Creating new Subscriptions, Pre Authorizations and One-Off Payments
117
118 To set up new subscriptions, pre-authorizations and one-off payments between a
119 user and merchant account, you need to send the user to the GoCardless site to
b356ebd @hmarr Docs for limit creation
hmarr authored
120 approve the process. This is broadly similar to how you link merchant accounts
121 with your app, the principal difference being that you don't get an access
122 token at the end of it.
123
124 You should pass through certain attributes about the resource that you're
125 trying to create, such as the payment amount, or the subscription frequency.
126 These attributes are sent as query-string arguments. For security purposes, the
127 request must also contain a timestamp, nonce (randomly-generated value),
128 merchant id and a signature. The {GoCardless::Client client} object does this
129 for you, so you just need to provide the attributes:
130
131 url = client.new_subscription_url(:frequency_unit => :week,
132 :frequency_length => 6,
133 :amount => 30,
134 :description => 'Premium membership')
135
136 Redirecting a user to `url` will take them to a page where they can authorize a
137 weekly subscription of £30 for a period of 6 weeks. Once they have authorized
138 the subscription, they will be taken back to your site.
c71d4cd @hmarr Added methods for generating new limit urls
hmarr authored
139
140
43addcb @hmarr Moved README from rdoc to markdown
hmarr authored
141 ## Creating and modifying bills
142
143 The GoCardless API may also be used to create and modify bills. Bills must be
144 created on a pre authorization. To create a bill, use the
145 {GoCardless::PreAuthorization#create_bill create\_bill} method on
146 {GoCardless::PreAuthorization PreAuthorization} objects, providing the amount
147 in pence as the only argument:
148
149 bill = pre_authorization.create_bill(150) # => <GoCardless::Bill ...>
150
151 To modify the bill, alter the attributes and call the
152 {GoCardless::Resource#save save} method:
153
154 bill.amount = 250
155 bill.save
156
b996983 @hmarr Documentation improvements
hmarr authored
157
43addcb @hmarr Moved README from rdoc to markdown
hmarr authored
158 ## Example usage
159 require 'gocardless'
160
161 # These are found in the GoCardless app admin interface
162 APP_ID = '3QmpV5yi8Ii9Rc2uCwalWRsqkpibtk5ISOk/F+oyzrOoNpjGguZ4IRn2379agARS'
163 APP_SECRET = '8oCITH2AVhaUYqJ+5hjyt8JUlSo5m/WTYLH8E/GO+TrBWdRK45lvoRt/zetr+t5Y'
164
165 # Create a new instance of the GoCardless API client
e97e0ec @hmarr More docs and examples
hmarr authored
166 client = GoCardless::Client.new(APP_ID, APP_SECRET)
43addcb @hmarr Moved README from rdoc to markdown
hmarr authored
167
168 # Generate the OAuth 'authorize endpoint' URL
e97e0ec @hmarr More docs and examples
hmarr authored
169 authorize_url = client.authorize_url(:redirect_uri => 'http://mywebsite.com/cb')
170
171 # Now, redirect the user (merchant) to 'authorize_url'. In Rails this would
172 # look like:
173 #
174 # redirect_to authorize_url
175 #
176 # They will be presented with a screen where they confirm the link between
177 # their merchant account and your app. Once they are done, they will be
178 # redirected back to the 'redirect_url' you provided.
179
180 # Now you need to retrieve the authorization code from the query string
181 # parameters:
182 #
183 # auth_code = params[:auth_code]
184 #
185 # Then exchange the authorization code for an access token:
43addcb @hmarr Moved README from rdoc to markdown
hmarr authored
186
187 client.fetch_access_token(auth_code, :redirect_uri => 'http://mywebsite.com/cb')
188
e97e0ec @hmarr More docs and examples
hmarr authored
189 # The access token should be saved to the database alongside the merchant.
190 # You can get the access token using 'client.access_token'
191
192 # The API client will be associated with a merchant account
43addcb @hmarr Moved README from rdoc to markdown
hmarr authored
193 client.merchant # => <GoCardless::Merchant ...>
194
195 # The client allows you to look up most resources by their id
196 client.subscription(5) # => <GoCardless::Subscription ...>
197 client.pre_authorization(5) # => <GoCardless::PreAuthorization ...>
198 client.bill(5) # => <GoCardless::Bill ...>
199 client.payment(5) # => <GoCardless::Payment ...>
200
201 # Retrieve referenced resources directly from resource objects
202 subscription = client.subscription(5)
203 subscription.merchant # => <GoCardless::Merchant ...>
204
e97e0ec @hmarr More docs and examples
hmarr authored
205 # To create a new subscription, generate the appropirate URL:
206 url = client.new_subscription_url(:frequency_unit => :week,
207 :frequency_length => 6,
208 :amount => 30,
209 :description => 'Premium membership')
210
211 # Then redirect the user to the URL:
212 #
213 # redirect_to url
214 #
215 # When the user is redirected back to your site, you need to confirm the
216 # new subscription (assuming params is the query-string parameters):
217 subscription = client.confirm_resource(params)
218
219 # Create a new bill via the API under a pre authorization:
43addcb @hmarr Moved README from rdoc to markdown
hmarr authored
220 client.merchant.pre_authorizations.first.create_bill(500) # £5.00 bill
e97e0ec @hmarr More docs and examples
hmarr authored
221
Something went wrong with that request. Please try again.