pin-payments 1.0 → 1.1
Sign up to get free protection for your applications and to get access to all the features.
- data/.travis.yml +8 -0
- data/README.md +119 -25
- data/lib/pin-payments/base.rb +1 -6
- data/lib/pin-payments/charge.rb +12 -0
- data/pin-payments.gemspec +3 -1
- data/test/test_helper.rb +1 -1
- metadata +35 -1
data/.travis.yml
ADDED
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:
|
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
|
-
###
|
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
|
-
|
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
|
-
|
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',
|
66
|
-
|
67
|
-
|
68
|
-
|
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 (
|
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',
|
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
|
-
#
|
127
|
+
# create a customer using a card object
|
82
128
|
customer = Pin::Customer.create 'user@example.com', card
|
83
129
|
|
84
|
-
#
|
85
|
-
|
86
|
-
|
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
|
-
|
136
|
+
**Retrieving a customer**
|
90
137
|
|
91
138
|
```ruby
|
92
|
-
# get all customers
|
93
|
-
|
139
|
+
# get all customers
|
140
|
+
Pin::Customer.all
|
94
141
|
|
95
|
-
#
|
96
|
-
|
142
|
+
# get a customer with token "cus_XZg1ULpWaROQCOT5PdwLkQ"
|
143
|
+
Pin::Customer.find("cus_XZg1ULpWaROQCOT5PdwLkQ")
|
144
|
+
```
|
97
145
|
|
98
|
-
|
99
|
-
|
100
|
-
|
101
|
-
|
102
|
-
|
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
|
-
|
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
|
data/lib/pin-payments/base.rb
CHANGED
@@ -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 =
|
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
|
data/lib/pin-payments/charge.rb
CHANGED
@@ -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
|
data/pin-payments.gemspec
CHANGED
@@ -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.
|
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
|
data/test/test_helper.rb
CHANGED
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.
|
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:
|