pin-payments 1.0 → 1.1

Sign up to get free protection for your applications and to get access to all the features.
@@ -0,0 +1,8 @@
1
+ language: ruby
2
+
3
+ rvm:
4
+ - 1.9.2
5
+ - 1.9.3
6
+ - 2.0.0
7
+
8
+ script: bundle exec rake
data/README.md CHANGED
@@ -2,6 +2,16 @@
2
2
 
3
3
  A wrapper for the [pin.net.au](https://pin.net.au/) [API](https://pin.net.au/docs/api). MIT licensed.
4
4
 
5
+ ## Installation
6
+
7
+ Available via [RubyGems](https://rubygems.org/gems/pin-payments). Install the usual way;
8
+
9
+ gem install pin-payments
10
+
11
+ ## Build Status
12
+
13
+ [![Build status](https://travis-ci.org/ghiculescu/pin-payments.png)](https://travis-ci.org/ghiculescu/pin-payments)
14
+
5
15
  ## Usage
6
16
 
7
17
  ### Prerequisites
@@ -13,7 +23,7 @@ You'll need to create an account at [pin.net.au](https://pin.net.au/) first.
13
23
  Create an initializer, eg. `pin.rb`, using keys from Pin's [Your Account](https://dashboard.pin.net.au/account) page.
14
24
 
15
25
  ```ruby
16
- Pin.setup secret_key: 'PIN_SECRET_KEY', publishable_key: 'PIN_PUBLISHABLE_KEY', mode: :test
26
+ Pin.setup secret_key: ENV['PIN_SECRET_KEY'], publishable_key: ENV['PIN_PUBLISHABLE_KEY'], mode: ENV['PIN_ENV']
17
27
  ```
18
28
 
19
29
  The `mode` should be `:live` or `:test` depending on which API you want to access. The `publishable_key` is optional.
@@ -50,59 +60,135 @@ production:
50
60
 
51
61
  This allows you to inject `pin.yml` at deployment time, so that the secret key can be kept separate from your codebase.
52
62
 
53
- ### Usage
63
+ ### JavaScript Helpers
64
+
65
+ You'll probably want to create a form through which users can enter their details. [Pin's guide](https://pin.net.au/docs/guides/payment-forms) will step you through this. The publishable key will be necessary and, if set, can be obtained by calling `Pin.publishable_key`. So for example, you could have at the bottom of your form:
54
66
 
55
- You'll probably want to create a form through which users can enter their details. [Pin's guide](https://pin.net.au/docs/guides/payment-forms) will step you through this. The publishable key will be necessary and, if set, can be obtained by calling `Pin.publishable_key`. You can also ask the module for the path to the javascript for the configured mode:
67
+ ```javascript
68
+ $('form.pin').pinForm('<%= Pin.publishable_key %>')
69
+ ```
70
+
71
+ You also need to include [Pin.js](https://pin.net.au/pin-js) in pages that will talk to Pin via JavaScript. You can easily do this (and load the appropriate live or test version of pin.js) by doing:
56
72
 
57
73
  ```erb
58
74
  <%= javascript_include_tag Pin.js_url %>
59
75
  ```
60
76
 
61
- Creating a charge is simple. In your controller:
77
+ ### Charges
78
+
79
+ [API Documentation](https://pin.net.au/docs/api/charges)
80
+
81
+ **Creating a charge**
62
82
 
63
83
  ```ruby
64
84
  def create
65
- Pin::Charge.create email: 'user@example.com', description: '1 year of service', amount: 10000,
66
- currency: 'AUD', ip_address: params[:ip_address], card_token: params[:card_token]
67
-
68
- redirect_to new_payment_path, notice: "Your credit card has been charged"
85
+ Pin::Charge.create email: 'user@example.com',
86
+ description: '1 year of service', amount: 10000,
87
+ currency: 'AUD',
88
+ ip_address: params[:ip_address],
89
+ card_token: params[:card_token]
69
90
  end
70
91
  ```
71
92
 
72
- This will issue a once-off charge ([API](https://pin.net.au/docs/api/charges)).
93
+ This will issue a once-off charge. Generally it's a good practice to do this in a background job and not directly in the controller. You can also create a charge against a customer token, once you have saved a customer (more details below).
94
+
95
+ ```ruby
96
+ Pin::Charge.create email: 'user@example.com',
97
+ description: '1 year of service', amount: 10000,
98
+ currency: 'AUD',
99
+ ip_address: params[:ip_address],
100
+ customer_token: customer.token
101
+ ```
102
+
103
+ **Retrieving charges**
104
+
105
+ ```ruby
106
+ # get all charges
107
+ Pin::Charge.all
108
+
109
+ # get a charge with token "ch_lfUYEBK14zotCTykezJkfg"
110
+ Pin::Charge.find("ch_lfUYEBK14zotCTykezJkfg")
111
+ ```
112
+
113
+ ### Customers
114
+
115
+ [API Documentation](https://pin.net.au/docs/api/customers)
73
116
 
74
117
  For a recurring charge, you may wish to create a customer record at Pin. To do this, either create a `Card` object first, then a corresponding `Customer` via the [API](https://pin.net.au/docs/api/customers); or use a `card_token` returned from `Pin.js` to create a customer. Note that in either case you may activate additional compliance provisions in Pin's [Terms & Conditions](https://pin.net.au/terms).
75
118
 
119
+ **Creating a customer**
120
+
76
121
  ```ruby
77
122
  # this doesn't contact the API
78
123
  card = Pin::Card.new number: '5520000000000000', expiry_month: '12', expiry_year: '2018', cvc: '123',
79
- name: 'User Name', address_line1: 'GPO Box 1234', address_city: 'Melbourne', address_postcode: '3001', address_state: 'VIC', address_country: 'Australia'
124
+ name: 'User Name', address_line1: 'GPO Box 1234', address_city: 'Melbourne',
125
+ address_postcode: '3001', address_state: 'VIC', address_country: 'Australia'
80
126
 
81
- # this contacts the API and returns a customer
127
+ # create a customer using a card object
82
128
  customer = Pin::Customer.create 'user@example.com', card
83
129
 
84
- # this contacts the API and returns a charge
85
- Pin::Charge.create email: 'user@example.com', description: '1 year of service', amount: 10000,
86
- currency: 'AUD', ip_address: '127.0.0.1', customer: customer # shorthand for customer_token: customer.token
130
+ # you can also create a customer using a card token - for example, in a controller
131
+ def create
132
+ customer = Pin::Customer.create 'user@example.com', params[:card_token]
133
+ end
87
134
  ```
88
135
 
89
- You can view your customers in the [Pin dashboard](https://dashboard.pin.net.au/test/customers). This lets you charge customers regularly without asking for their credit card details each time.
136
+ **Retrieving a customer**
90
137
 
91
138
  ```ruby
92
- # get all customers from the API
93
- customers = Pin::Customer.all
139
+ # get all customers
140
+ Pin::Customer.all
94
141
 
95
- # find the customer you are trying to charge, assuming `current_user` is defined elsewhere
96
- customer = customers.find {|c| c.email == current_user.email}
142
+ # get a customer with token "cus_XZg1ULpWaROQCOT5PdwLkQ"
143
+ Pin::Customer.find("cus_XZg1ULpWaROQCOT5PdwLkQ")
144
+ ```
97
145
 
98
- # create a charge for the customer
99
- # note that using this method you will need to store the `ip_address` of the user
100
- # generally you can store this from when you initially created the customer (via Pin.js)
101
- Pin::Charge.create email: user.email, description: '1 month of service', amount: 19900,
102
- currency: 'AUD', ip_address: user.ip_address, customer: customer
146
+ ### Refunds
147
+
148
+ [API Documentation](https://pin.net.au/docs/api/refunds)
149
+
150
+ Refunds work based on charges, so you'll need a charge first.
151
+
152
+ ```ruby
153
+ charge = Pin::Charge.first
154
+ ```
155
+
156
+ Create a refund:
157
+
158
+ ```ruby
159
+ # provide an amount to refund that amount - defaults to refunding the full amount
160
+ # both methods do the same thing
161
+ charge.refund!(250)
162
+ Pin::Refund.create(charge, 250)
163
+ ```
164
+
165
+ Get refunds for this charge:
166
+
167
+ ```ruby
168
+ # both do the same thing
169
+ refunds = charge.refunds
170
+ refunds = Pin::Refund.all(charge)
103
171
  ```
104
172
 
105
- Errors from the API will result in a`Pin::APIError` exception being thrown:
173
+ ### Card Tokens
174
+
175
+ [API Documentation](https://pin.net.au/docs/api/cards)
176
+
177
+ Given a credit card, store it in Pin and get a card token in exchange:
178
+
179
+ ```ruby
180
+ # contact the API and get a card token
181
+ card = Pin::Card.create number: '5520000000000000', expiry_month: '12', expiry_year: '2018', cvc: '123',
182
+ name: 'User Name', address_line1: 'GPO Box 1234', address_city: 'Melbourne',
183
+ address_postcode: '3001', address_state: 'VIC', address_country: 'Australia'
184
+ token = card.token
185
+ ```
186
+
187
+ You can then use this token to create a customer or make a charge. If possible, it is better practice to create card tokens using `Pin.js` and only pass on the required information (ie. the card token and IP address) to your server.
188
+
189
+ ### Errors
190
+
191
+ Errors from the API will result in a`Pin::APIError` exception being raised:
106
192
 
107
193
  ```ruby
108
194
  begin
@@ -111,3 +197,11 @@ rescue Pin::APIError => e
111
197
  redirect_to new_payment_path, flash: { error: "Charge failed: #{e.message}" }
112
198
  end
113
199
  ```
200
+
201
+ ## License
202
+
203
+ MIT
204
+
205
+ ## Contributors
206
+
207
+ https://github.com/ghiculescu/pin-payments/graphs/contributors
@@ -25,14 +25,10 @@ module Pin
25
25
 
26
26
  def all(options = {})
27
27
  options = {path: api_path, page: 1}.merge(options)
28
- paging = "page=#{options[:page]}" unless options[:page] == 1
28
+ paging = {page: options[:page]} unless options[:page] == 1
29
29
  build_collection_from_response(authenticated_get(options[:path], paging))
30
30
  end
31
31
 
32
- def all_pages(options = {})
33
- options = options.merge(path: api_path)
34
- end
35
-
36
32
  def first(options = {})
37
33
  all(options).first
38
34
  end
@@ -46,7 +42,6 @@ module Pin
46
42
  end
47
43
 
48
44
  protected
49
-
50
45
  def auth
51
46
  Pin.auth
52
47
  end
@@ -21,6 +21,18 @@ module Pin
21
21
  options[:customer_token] = options.delete(:customer).token unless options[:customer].nil?
22
22
  super(options)
23
23
  end
24
+
25
+ # search for charges using parameters provided in options
26
+ # available parameters:
27
+ # query (string)
28
+ # start_date (date, or string formatted as 'YYYY-MM-DD')
29
+ # end_date (date, or string formatted as 'YYYY-MM-DD')
30
+ # sort (string or symbol: "created_at" (default), "description", or "amount")
31
+ # direction ("asc"/"desc", or 1/-1)
32
+ def search(options = {})
33
+ options[:direction] = options[:direction] == 'asc' ? 1 : -1 if ['asc', 'desc'].include?(options[:direction])
34
+ build_collection_from_response(authenticated_get('/charges/search', options))
35
+ end
24
36
  end
25
37
 
26
38
  # find all refunds for the current Charge object
@@ -4,7 +4,7 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
4
4
 
5
5
  Gem::Specification.new do |s|
6
6
  s.name = 'pin-payments'
7
- s.version = '1.0'
7
+ s.version = '1.1'
8
8
  s.date = '2013-08-06'
9
9
  s.summary = "Pin Payments API wrapper"
10
10
  s.description = "A wrapper for the Pin Payments (https://pin.net.au/) API"
@@ -23,4 +23,6 @@ Gem::Specification.new do |s|
23
23
 
24
24
  s.add_development_dependency "bundler", "~> 1.3"
25
25
  s.add_development_dependency "webmock"
26
+ s.add_development_dependency "rake"
27
+ s.add_development_dependency "activesupport"
26
28
  end
@@ -1,5 +1,5 @@
1
1
  require "rubygems"
2
- require 'debugger'
2
+ #require 'debugger'
3
3
  require 'test/unit'
4
4
  require 'webmock/test_unit'
5
5
  require 'active_support/inflector'
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: pin-payments
3
3
  version: !ruby/object:Gem::Version
4
- version: '1.0'
4
+ version: '1.1'
5
5
  prerelease:
6
6
  platform: ruby
7
7
  authors:
@@ -59,6 +59,38 @@ dependencies:
59
59
  - - ! '>='
60
60
  - !ruby/object:Gem::Version
61
61
  version: '0'
62
+ - !ruby/object:Gem::Dependency
63
+ name: rake
64
+ requirement: !ruby/object:Gem::Requirement
65
+ none: false
66
+ requirements:
67
+ - - ! '>='
68
+ - !ruby/object:Gem::Version
69
+ version: '0'
70
+ type: :development
71
+ prerelease: false
72
+ version_requirements: !ruby/object:Gem::Requirement
73
+ none: false
74
+ requirements:
75
+ - - ! '>='
76
+ - !ruby/object:Gem::Version
77
+ version: '0'
78
+ - !ruby/object:Gem::Dependency
79
+ name: activesupport
80
+ requirement: !ruby/object:Gem::Requirement
81
+ none: false
82
+ requirements:
83
+ - - ! '>='
84
+ - !ruby/object:Gem::Version
85
+ version: '0'
86
+ type: :development
87
+ prerelease: false
88
+ version_requirements: !ruby/object:Gem::Requirement
89
+ none: false
90
+ requirements:
91
+ - - ! '>='
92
+ - !ruby/object:Gem::Version
93
+ version: '0'
62
94
  description: A wrapper for the Pin Payments (https://pin.net.au/) API
63
95
  email: alexghiculescu@gmail.com
64
96
  executables: []
@@ -66,6 +98,7 @@ extensions: []
66
98
  extra_rdoc_files: []
67
99
  files:
68
100
  - .gitignore
101
+ - .travis.yml
69
102
  - Gemfile
70
103
  - Gemfile.lock
71
104
  - README.md
@@ -132,3 +165,4 @@ test_files:
132
165
  - test/unit/charges_test.rb
133
166
  - test/unit/customers_test.rb
134
167
  - test/unit/refunds_test.rb
168
+ has_rdoc: