bitpay-sdk 2.3.0 → 2.3.1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/GUIDE.md +198 -0
- data/README.md +1 -197
- data/lib/bitpay/client.rb +0 -48
- data/lib/bitpay/version.rb +1 -1
- data/spec/client_spec.rb +0 -51
- metadata +3 -2
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA1:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: bf3789696b7fcf3ba7b4b11df9f4c2ff3cc2d5b7
|
|
4
|
+
data.tar.gz: 1b0a2652ea570a21344280083fb0ab89a9e62f54
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 02cf470eaa7f2a0c05739d2f7217ffbd48811522c0f85f1a7aa9917cb57cc29f903836a30bb5ef180592ad2652f5132df11eca0e54e261c2f2ca018ec8501b09
|
|
7
|
+
data.tar.gz: 2590256522eb97aa5290cd4ad2435633155b0391534c38d87cd24f1a90679ee7235291280fbc9bef5a6bb06ae7736a91f4a3c03ec569e472b29b7a1c21bf5eb5
|
data/GUIDE.md
ADDED
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
# Using the BitPay Ruby Client Library
|
|
2
|
+
## Prerequisites
|
|
3
|
+
You must have a BitPay merchant account to use this library. It's free to [sign-up for a BitPay merchant account](https://bitpay.com/start).
|
|
4
|
+
|
|
5
|
+
Once you have a BitPay merchant account, you will need [a working BitPay Access Token](/api/getting-access.html) – this can be done either [via the library](#pairing) or manually in [the BitPay Dashboard](https://bitpay.com/tokens).
|
|
6
|
+
|
|
7
|
+
## Quick Start
|
|
8
|
+
### Installation
|
|
9
|
+
```bash
|
|
10
|
+
gem install bitpay-sdk
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
In your Gemfile:
|
|
14
|
+
|
|
15
|
+
```ruby
|
|
16
|
+
gem 'bitpay-sdk', :require => 'bitpay_sdk'
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Or directly:
|
|
20
|
+
```ruby
|
|
21
|
+
require 'bitpay_sdk'
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
### Configuration
|
|
25
|
+
The bitpay client creates a cryptographically secure connection to your server by pairing an API code with keys generated by the library. The client can be initialized with pre-existing keys passed in as a pem file, or paired if initialized with a pem file and a tokens hash. Examples can be found in the cucumber step helpers.
|
|
26
|
+
|
|
27
|
+
## Pairing
|
|
28
|
+
Most calls to the BitPay REST API require that your client is paired with the bitpay.com server. To pair with bitpay.com you need to have an approved merchant account.
|
|
29
|
+
|
|
30
|
+
Your client can be paired via the `pos` (point-of-sale) or `merchant` facade (or both). The `pos` facade allows for invoices to be created. The `merchant` facade has broader privileges to view all invoices, bills, and ledger entries, as well as to issue refunds. Consider the level of access required when you pair your client.
|
|
31
|
+
|
|
32
|
+
_For development or quick deployment purposes, consider the [BitPay Ruby Command-Line Interface](https://github.com/bitpay/ruby-cli) to simplify the deployment process_
|
|
33
|
+
|
|
34
|
+
### Pairing Programatically
|
|
35
|
+
|
|
36
|
+
If you are developing a client with built-in pairing capability, you can pair programattically using the `pair_client` method. This method can be called in two ways:
|
|
37
|
+
|
|
38
|
+
* `pair_client()` will perform a client-initiated pairing, and will provide a pairing code that can be entered at https://bitpay.com/dashboard/merchant/api-tokens to assign either `merchant` or `pos` facade.
|
|
39
|
+
* `pair_client('pairing_code')` will complete a server-initiated pairing, when provided a pre-generated pairing code from https://bitpay.com/dashboard/merchant/api-tokens. In this case, the `pos` facade will be automatically assigned.
|
|
40
|
+
|
|
41
|
+
The example below demonstrates this using a locally generated PEM file using OpenSSL and the irb tool.
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
$ gem install bitpay-sdk
|
|
45
|
+
Successfully installed bitpay-sdk-2.2.0
|
|
46
|
+
1 gem installed
|
|
47
|
+
$ openssl ecparam -genkey -name secp256k1 -noout -out bitpaykey.pem
|
|
48
|
+
$ irb
|
|
49
|
+
2.1.1 :001 > require 'bitpay_sdk'
|
|
50
|
+
=> true
|
|
51
|
+
2.1.1 :002 > client = BitPay::SDK::Client.new(api_uri: 'https://test.bitpay.com', pem: File.read('bitpaykey.pem'), insecure: true)
|
|
52
|
+
=> #<BitPay::SDK::Client:0x000000019c6d40 @pem="---... @tokens={}>
|
|
53
|
+
2.1.1 :003 > client.pair_client()
|
|
54
|
+
=> {"data"=>[{"policies"=>[{"policy"=>"id", "method"=>"inactive", "params"=>["Tf49SFeiUAtytFEW2EUqZgWj32nP51PK73M"]}], "token"=>"BKQyVdaGQZAArdkkSuvtZN5gcN2355c8vXLj5eFPkfuK", "dateCreated"=>1422474475162, "pairingExpiration"=>1422560875162, "pairingCode"=>"Vy76yTh"}]}
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
As described above, using the value from the `pairingCode` element, visit https://test.bitpay.com/api-tokens and search to register for the appropriate facade
|
|
58
|
+
|
|
59
|
+
## General Usage
|
|
60
|
+
|
|
61
|
+
### Initialize the client
|
|
62
|
+
|
|
63
|
+
```ruby
|
|
64
|
+
client = BitPay::SDK::Client.new(pem: File.read('bitpaykey.pem')
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Optional parameters:
|
|
68
|
+
* `api_uri` - specify a different api endpoint (e.g. 'https://test.bitpay.com'). Ensure no trailing slash.
|
|
69
|
+
* `tokens` - pass a stored hash of bitpay API tokens
|
|
70
|
+
* `user-agent` - specify a custom user-agent value
|
|
71
|
+
* `debug: true` - enable HTTP request logging to $stdout
|
|
72
|
+
* `insecure: true` - disable HTTPs certificate validation (for local test environments)
|
|
73
|
+
|
|
74
|
+
### Create a new bitcoin invoice
|
|
75
|
+
|
|
76
|
+
```ruby
|
|
77
|
+
invoice = client.create_invoice (price: <price>, currency: <currency>)
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
With invoice creation, `price` and `currency` are the only required fields. If you are sending a customer from your website to make a purchase, setting `redirectURL` will redirect the customer to your website when the invoice is paid.
|
|
81
|
+
|
|
82
|
+
Response will be a hash with information on your newly created invoice. Send your customer to the `url` to complete payment:
|
|
83
|
+
|
|
84
|
+
```javascript
|
|
85
|
+
{
|
|
86
|
+
"url": "https://bitpay.com/invoice?id=NKaqMuZWy3BAcP77RdkEEv",
|
|
87
|
+
"paymentUrls": {
|
|
88
|
+
"BIP21": "bitcoin:mvYRECDxKPaPHnjNz9ZxiTpbx29xYNoRy4?amount=0.3745",
|
|
89
|
+
"BIP72": "bitcoin:mvYRECDxKPaPHnjNz9ZxiTpbx29xYNoRy4?amount=0.3745&r=https://bitpay.com/i/NKaqMuZWy3BAcP77RdkEEv",
|
|
90
|
+
"BIP72b": "bitcoin:?r=https://bitpay.com/i/NKaqMuZWy3BAcP77RdkEEv",
|
|
91
|
+
"BIP73": "https://bitpay.com/i/NKaqMuZWy3BAcP77RdkEEv"
|
|
92
|
+
},
|
|
93
|
+
"status": "new",
|
|
94
|
+
"btcPrice": "0.3745",
|
|
95
|
+
"btcDue": "0.3745",
|
|
96
|
+
"price": 148,
|
|
97
|
+
"currency": "USD",
|
|
98
|
+
"exRates": {
|
|
99
|
+
"USD": 395.20000000000005
|
|
100
|
+
},
|
|
101
|
+
"invoiceTime": 1415987168612,
|
|
102
|
+
"expirationTime": 1415988068612,
|
|
103
|
+
"currentTime": 1415987168629,
|
|
104
|
+
"guid": "438e8237-fff1-483c-81b4-dc7dba28922a",
|
|
105
|
+
"id": "NKaqMuZWy3BAcP77RdkEEv",
|
|
106
|
+
"transactions": [
|
|
107
|
+
|
|
108
|
+
],
|
|
109
|
+
"btcPaid": "0.0000",
|
|
110
|
+
"rate": 395.2,
|
|
111
|
+
"exceptionStatus": false,
|
|
112
|
+
"token": "9kZgUXFb5AC6qMuLaMpP9WopbM8X2UjMhkphKKdaprRbSKgUJNE6JNTX8bGsmgxKKv",
|
|
113
|
+
"buyer": {
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
There are many options available when creating invoices, which are listed in the [BitPay API documentation](https://bitpay.com/bitcoin-payment-gateway-api).
|
|
119
|
+
|
|
120
|
+
### Get invoice status
|
|
121
|
+
The ruby library provides two methods for fetching an existing invoice:
|
|
122
|
+
|
|
123
|
+
```ruby
|
|
124
|
+
# For authorized clients with a 'merchant' token
|
|
125
|
+
client.get_invoice(id: 'PvVhgBfA7wKPWhuVC24rJo')
|
|
126
|
+
|
|
127
|
+
# For non-authenticated clients (public facade)
|
|
128
|
+
# Returns the public subset of invoice fields
|
|
129
|
+
client.get_public_invoice(id: 'PvVhgBfA7wKPWhuVC24rJo')
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
### Create a refund request
|
|
133
|
+
|
|
134
|
+
Clients with a `merchant` token can initiate a refund request for a paid invoice:
|
|
135
|
+
|
|
136
|
+
```ruby
|
|
137
|
+
client.refund_invoice(id: '6pbV13VBZfGFJ8BBmXmLZ8', params: {amount: 10, currency: 'USD'})
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
Refund rules:
|
|
141
|
+
|
|
142
|
+
* Invoices cannot be refunded prior to 6 blockchain confirmations
|
|
143
|
+
* Invoices without `["flags"]["refundable"] == true` must specify a `bitcoinAddress` param (one was not provided as part of the transaction)
|
|
144
|
+
* Invoices that are paid in full must specify an `amount` and `currency` param to indicate the amount to be refunded
|
|
145
|
+
|
|
146
|
+
### View Refund Requests
|
|
147
|
+
|
|
148
|
+
The ruby library provides two methods for viewing refund requests. Both require a `merchant` token.
|
|
149
|
+
|
|
150
|
+
```ruby
|
|
151
|
+
# To get an array of all refunds against a specific invoice
|
|
152
|
+
client.get_all_refunds_for_invoice(id: 'PvVhgBfA7wKPWhuVC24rJo')
|
|
153
|
+
|
|
154
|
+
# To get a specific refund for a specific invoice
|
|
155
|
+
client.get_refund(id: 'JB49z2MsDH7FunczeyDS8j', request_id: '4evCrXq4EDXk4oqDXdWQhX')
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
### Make a HTTP request directly against the REST API
|
|
159
|
+
|
|
160
|
+
For API tasks which lack a dedicated library method, BitPay provides a method that will automatically apply the proper cryptographic parameters to a request.
|
|
161
|
+
|
|
162
|
+
```ruby
|
|
163
|
+
client.send_request("GET", "/invoices/JB49z2MsDH7FunczeyDS8j", facade: 'merchant')
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
Usage:
|
|
167
|
+
* Specify HTTP verb and REST endpoint
|
|
168
|
+
* Specifying a `facade` will fetch and apply the corresponding `token`
|
|
169
|
+
* Alternatively provide a `token` explicitly
|
|
170
|
+
* For `POST` requests, the `params` hash will be included as the message body
|
|
171
|
+
|
|
172
|
+
## Testnet Usage
|
|
173
|
+
|
|
174
|
+
During development and testing, take advantage of the [Bitcoin TestNet](https://en.bitcoin.it/wiki/Testnet) by passing a custom `api_uri` option on initialization:
|
|
175
|
+
|
|
176
|
+
```ruby
|
|
177
|
+
BitPay::SDK::Client.new({api_uri: "https://test.bitpay.com/api"})
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
Note that in order to pair with testnet, you will need a pairing code from test.bitpay.com and will need to use the bitpay client with the --test option.
|
|
181
|
+
|
|
182
|
+
## API Documentation
|
|
183
|
+
|
|
184
|
+
API Documentation is available on the [BitPay site](https://bitpay.com/api).
|
|
185
|
+
|
|
186
|
+
## Running the Tests
|
|
187
|
+
|
|
188
|
+
In order to run the tests, you must have phantomjs installed and on your PATH.
|
|
189
|
+
|
|
190
|
+
The tests require that environment variables be set for the bitpay server, user name, and password. First run:
|
|
191
|
+
|
|
192
|
+
```bash
|
|
193
|
+
$ source ./spec/set_constants.sh https://test.bitpay.com <yourusername> <yourpassword>
|
|
194
|
+
$ bundle install
|
|
195
|
+
$ bundle exec rake
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
Tests are likely to run up against rate limiters on test.bitpay.com if used too frequently. Rake tasks which interact directly with BitPay will not run for the general public.
|
data/README.md
CHANGED
|
@@ -3,203 +3,7 @@ Powerful, flexible, lightweight interface to the BitPay Bitcoin Payment Gateway
|
|
|
3
3
|
|
|
4
4
|
The `bitpay-sdk` gem provides all the programattic tools required to implement a ruby client application for the BitPay REST API. For developers who prefer the ease of command-line pairing during the development or deployment process, BitPay provides a complementary [Ruby CLI gem](https://github.com/bitpay/ruby-cli) which can be used in conjunction with this gem.
|
|
5
5
|
|
|
6
|
-
##
|
|
7
|
-
|
|
8
|
-
```bash
|
|
9
|
-
gem install bitpay-sdk
|
|
10
|
-
```
|
|
11
|
-
|
|
12
|
-
In your Gemfile:
|
|
13
|
-
|
|
14
|
-
```ruby
|
|
15
|
-
gem 'bitpay-sdk', :require => 'bitpay_sdk'
|
|
16
|
-
```
|
|
17
|
-
|
|
18
|
-
Or directly:
|
|
19
|
-
```ruby
|
|
20
|
-
require 'bitpay_sdk'
|
|
21
|
-
```
|
|
22
|
-
|
|
23
|
-
## Configuration
|
|
24
|
-
|
|
25
|
-
The bitpay client creates a cryptographically secure connection to your server by pairing an API code with keys generated by the library. The client can be initialized with pre-existing keys passed in as a pem file, or paired if initialized with a pem file and a tokens hash. Examples can be found in the cucumber step helpers.
|
|
26
|
-
|
|
27
|
-
## Client Setup
|
|
28
|
-
|
|
29
|
-
### Pairing with Bitpay.com
|
|
30
|
-
|
|
31
|
-
Most calls to the BitPay REST API require that your client is paired with the bitpay.com server. To pair with bitpay.com you need to have an approved merchant account.
|
|
32
|
-
|
|
33
|
-
Your client can be paired via the `pos` (point-of-sale) or `merchant` facade (or both). The `pos` facade allows for invoices to be created. The `merchant` facade has broader privileges to view all invoices, bills, and ledger entries, as well as to issue refunds. Consider the level of access required when you pair your client.
|
|
34
|
-
|
|
35
|
-
_For development or quick deployment purposes, consider the [BitPay Ruby Command-Line Interface](https://github.com/bitpay/ruby-cli) to simplify the deployment process_
|
|
36
|
-
|
|
37
|
-
### Pairing Programattically
|
|
38
|
-
|
|
39
|
-
If you are developing a client with built-in pairing capability, you can pair programattically using the `pair_client` method. This method can be called in two ways:
|
|
40
|
-
|
|
41
|
-
* `pair_client()` will perform a client-initiated pairing, and will provide a pairing code that can be entered at https://bitpay.com/dashboard/merchant/api-tokens to assign either `merchant` or `pos` facade.
|
|
42
|
-
* `pair_client('pairing_code')` will complete a server-initiated pairing, when provided a pre-generated pairing code from https://bitpay.com/dashboard/merchant/api-tokens. In this case, the `pos` facade will be automatically assigned.
|
|
43
|
-
|
|
44
|
-
The example below demonstrates this using a locally generated PEM file using OpenSSL and the irb tool.
|
|
45
|
-
|
|
46
|
-
```bash
|
|
47
|
-
$ gem install bitpay-sdk
|
|
48
|
-
Successfully installed bitpay-sdk-2.2.0
|
|
49
|
-
1 gem installed
|
|
50
|
-
$ openssl ecparam -genkey -name secp256k1 -noout -out bitpaykey.pem
|
|
51
|
-
$ irb
|
|
52
|
-
2.1.1 :001 > require 'bitpay_sdk'
|
|
53
|
-
=> true
|
|
54
|
-
2.1.1 :002 > client = BitPay::SDK::Client.new(api_uri: 'https://test.bitpay.com', pem: File.read('bitpaykey.pem'), insecure: true)
|
|
55
|
-
=> #<BitPay::SDK::Client:0x000000019c6d40 @pem="---... @tokens={}>
|
|
56
|
-
2.1.1 :003 > client.pair_client()
|
|
57
|
-
=> {"data"=>[{"policies"=>[{"policy"=>"id", "method"=>"inactive", "params"=>["Tf49SFeiUAtytFEW2EUqZgWj32nP51PK73M"]}], "token"=>"BKQyVdaGQZAArdkkSuvtZN5gcN2355c8vXLj5eFPkfuK", "dateCreated"=>1422474475162, "pairingExpiration"=>1422560875162, "pairingCode"=>"Vy76yTh"}]}
|
|
58
|
-
```
|
|
59
|
-
|
|
60
|
-
As described above, using the value from the `pairingCode` element, visit https://test.bitpay.com/api-tokens and search to register for the appropriate facade
|
|
61
|
-
|
|
62
|
-
## General Usage
|
|
63
|
-
|
|
64
|
-
### Initialize the client
|
|
65
|
-
|
|
66
|
-
```ruby
|
|
67
|
-
client = BitPay::SDK::Client.new(pem: File.read('bitpaykey.pem')
|
|
68
|
-
```
|
|
69
|
-
|
|
70
|
-
Optional parameters:
|
|
71
|
-
* `api_uri` - specify a different api endpoint (e.g. 'https://test.bitpay.com'). Ensure no trailing slash.
|
|
72
|
-
* `tokens` - pass a stored hash of bitpay API tokens
|
|
73
|
-
* `user-agent` - specify a custom user-agent value
|
|
74
|
-
* `debug: true` - enable HTTP request logging to $stdout
|
|
75
|
-
* `insecure: true` - disable HTTPs certificate validation (for local test environments)
|
|
76
|
-
|
|
77
|
-
### Create a new bitcoin invoice
|
|
78
|
-
|
|
79
|
-
```ruby
|
|
80
|
-
invoice = client.create_invoice (price: <price>, currency: <currency>)
|
|
81
|
-
```
|
|
82
|
-
|
|
83
|
-
With invoice creation, `price` and `currency` are the only required fields. If you are sending a customer from your website to make a purchase, setting `redirectURL` will redirect the customer to your website when the invoice is paid.
|
|
84
|
-
|
|
85
|
-
Response will be a hash with information on your newly created invoice. Send your customer to the `url` to complete payment:
|
|
86
|
-
|
|
87
|
-
```javascript
|
|
88
|
-
{
|
|
89
|
-
"url": "https://bitpay.com/invoice?id=NKaqMuZWy3BAcP77RdkEEv",
|
|
90
|
-
"paymentUrls": {
|
|
91
|
-
"BIP21": "bitcoin:mvYRECDxKPaPHnjNz9ZxiTpbx29xYNoRy4?amount=0.3745",
|
|
92
|
-
"BIP72": "bitcoin:mvYRECDxKPaPHnjNz9ZxiTpbx29xYNoRy4?amount=0.3745&r=https://bitpay.com/i/NKaqMuZWy3BAcP77RdkEEv",
|
|
93
|
-
"BIP72b": "bitcoin:?r=https://bitpay.com/i/NKaqMuZWy3BAcP77RdkEEv",
|
|
94
|
-
"BIP73": "https://bitpay.com/i/NKaqMuZWy3BAcP77RdkEEv"
|
|
95
|
-
},
|
|
96
|
-
"status": "new",
|
|
97
|
-
"btcPrice": "0.3745",
|
|
98
|
-
"btcDue": "0.3745",
|
|
99
|
-
"price": 148,
|
|
100
|
-
"currency": "USD",
|
|
101
|
-
"exRates": {
|
|
102
|
-
"USD": 395.20000000000005
|
|
103
|
-
},
|
|
104
|
-
"invoiceTime": 1415987168612,
|
|
105
|
-
"expirationTime": 1415988068612,
|
|
106
|
-
"currentTime": 1415987168629,
|
|
107
|
-
"guid": "438e8237-fff1-483c-81b4-dc7dba28922a",
|
|
108
|
-
"id": "NKaqMuZWy3BAcP77RdkEEv",
|
|
109
|
-
"transactions": [
|
|
110
|
-
|
|
111
|
-
],
|
|
112
|
-
"btcPaid": "0.0000",
|
|
113
|
-
"rate": 395.2,
|
|
114
|
-
"exceptionStatus": false,
|
|
115
|
-
"token": "9kZgUXFb5AC6qMuLaMpP9WopbM8X2UjMhkphKKdaprRbSKgUJNE6JNTX8bGsmgxKKv",
|
|
116
|
-
"buyer": {
|
|
117
|
-
}
|
|
118
|
-
}
|
|
119
|
-
```
|
|
120
|
-
|
|
121
|
-
There are many options available when creating invoices, which are listed in the [BitPay API documentation](https://bitpay.com/bitcoin-payment-gateway-api).
|
|
122
|
-
|
|
123
|
-
### Get invoice status
|
|
124
|
-
|
|
125
|
-
The ruby library provides two methods for fetching an existing invoice:
|
|
126
|
-
|
|
127
|
-
```ruby
|
|
128
|
-
# For authorized clients with a 'merchant' token
|
|
129
|
-
client.get_invoice(id: 'PvVhgBfA7wKPWhuVC24rJo')
|
|
130
|
-
|
|
131
|
-
# For non-authenticated clients (public facade)
|
|
132
|
-
# Returns the public subset of invoice fields
|
|
133
|
-
client.get_public_invoice(id: 'PvVhgBfA7wKPWhuVC24rJo')
|
|
134
|
-
```
|
|
135
|
-
|
|
136
|
-
### Create a refund request
|
|
137
|
-
|
|
138
|
-
Clients with a `merchant` token can initiate a refund request for a paid invoice:
|
|
139
|
-
|
|
140
|
-
```ruby
|
|
141
|
-
client.refund_invoice(id: '6pbV13VBZfGFJ8BBmXmLZ8', params: {amount: 10, currency: 'USD'})
|
|
142
|
-
```
|
|
143
|
-
|
|
144
|
-
Refund rules:
|
|
145
|
-
|
|
146
|
-
* Invoices cannot be refunded prior to 6 blockchain confirmations
|
|
147
|
-
* Invoices without `["flags"]["refundable"] == true` must specify a `bitcoinAddress` param (one was not provided as part of the transaction)
|
|
148
|
-
* Invoices that are paid in full must specify an `amount` and `currency` param to indicate the amount to be refunded
|
|
149
|
-
|
|
150
|
-
### View Refund Requests
|
|
151
|
-
|
|
152
|
-
The ruby library provides two methods for viewing refund requests. Both require a `merchant` token.
|
|
153
|
-
|
|
154
|
-
```ruby
|
|
155
|
-
# To get an array of all refunds against a specific invoice
|
|
156
|
-
client.get_all_refunds_for_invoice(id: 'PvVhgBfA7wKPWhuVC24rJo')
|
|
157
|
-
|
|
158
|
-
# To get a specific refund for a specific invoice
|
|
159
|
-
client.get_refund(id: 'JB49z2MsDH7FunczeyDS8j', request_id: '4evCrXq4EDXk4oqDXdWQhX')
|
|
160
|
-
```
|
|
161
|
-
|
|
162
|
-
### Make a HTTP request directly against the REST API
|
|
163
|
-
|
|
164
|
-
For API tasks which lack a dedicated library method, BitPay provides a method that will automatically apply the proper cryptographic parameters to a request.
|
|
165
|
-
|
|
166
|
-
```ruby
|
|
167
|
-
client.send_request("GET", "/invoices/JB49z2MsDH7FunczeyDS8j", facade: 'merchant')
|
|
168
|
-
```
|
|
169
|
-
|
|
170
|
-
Usage:
|
|
171
|
-
* Specify HTTP verb and REST endpoint
|
|
172
|
-
* Specifying a `facade` will fetch and apply the corresponding `token`
|
|
173
|
-
* Alternatively provide a `token` explicitly
|
|
174
|
-
* For `POST` requests, the `params` hash will be included as the message body
|
|
175
|
-
|
|
176
|
-
## Testnet Usage
|
|
177
|
-
|
|
178
|
-
During development and testing, take advantage of the [Bitcoin TestNet](https://en.bitcoin.it/wiki/Testnet) by passing a custom `api_uri` option on initialization:
|
|
179
|
-
|
|
180
|
-
```ruby
|
|
181
|
-
BitPay::SDK::Client.new({api_uri: "https://test.bitpay.com/api"})
|
|
182
|
-
```
|
|
183
|
-
|
|
184
|
-
Note that in order to pair with testnet, you will need a pairing code from test.bitpay.com and will need to use the bitpay client with the --test option.
|
|
185
|
-
|
|
186
|
-
## API Documentation
|
|
187
|
-
|
|
188
|
-
API Documentation is available on the [BitPay site](https://bitpay.com/api).
|
|
189
|
-
|
|
190
|
-
## Running the Tests
|
|
191
|
-
|
|
192
|
-
In order to run the tests, you must have phantomjs installed and on your PATH.
|
|
193
|
-
|
|
194
|
-
The tests require that environment variables be set for the bitpay server, user name, and password. First run:
|
|
195
|
-
|
|
196
|
-
```bash
|
|
197
|
-
$ source ./spec/set_constants.sh https://test.bitpay.com <yourusername> <yourpassword>
|
|
198
|
-
$ bundle install
|
|
199
|
-
$ bundle exec rake
|
|
200
|
-
```
|
|
201
|
-
|
|
202
|
-
Tests are likely to run up against rate limiters on test.bitpay.com if used too frequently. Rake tasks which interact directly with BitPay will not run for the general public.
|
|
6
|
+
## [Getting Started »](http://dev.bitpay.com/guides/ruby.html)
|
|
203
7
|
|
|
204
8
|
## Found a bug?
|
|
205
9
|
Let us know! Send a pull request or a patch. Questions? Ask! We're here to help. We will respond to all filed issues.
|
data/lib/bitpay/client.rb
CHANGED
|
@@ -84,54 +84,6 @@ module BitPay
|
|
|
84
84
|
response["data"]
|
|
85
85
|
end
|
|
86
86
|
|
|
87
|
-
|
|
88
|
-
## Refund paid BitPay invoice
|
|
89
|
-
#
|
|
90
|
-
# If invoice["data"]["flags"]["refundable"] == true the a refund address was
|
|
91
|
-
# provided with the payment and the refund_address parameter is an optional override
|
|
92
|
-
#
|
|
93
|
-
# Amount and Currency are required fields for fully paid invoices but optional
|
|
94
|
-
# for under or overpaid invoices which will otherwise be completely refunded
|
|
95
|
-
#
|
|
96
|
-
# Requires merchant facade token
|
|
97
|
-
#
|
|
98
|
-
# @example
|
|
99
|
-
# client.refund_invoice(id: 'JB49z2MsDH7FunczeyDS8j', params: {amount: 10, currency: 'USD', bitcoinAddress: '1Jtcygf8W3cEmtGgepggtjCxtmFFjrZwRV'})
|
|
100
|
-
#
|
|
101
|
-
def refund_invoice(id:, params:{})
|
|
102
|
-
invoice = get_invoice(id: id)
|
|
103
|
-
response = send_request("POST", "invoices/#{id}/refunds", facade: nil, token: invoice["token"], params: params)
|
|
104
|
-
response["data"]
|
|
105
|
-
end
|
|
106
|
-
|
|
107
|
-
## Get All Refunds for Invoice
|
|
108
|
-
# Returns an array of all refund requests for a specific invoice,
|
|
109
|
-
#
|
|
110
|
-
# Requires merchant facade token
|
|
111
|
-
#
|
|
112
|
-
# @example:
|
|
113
|
-
# client.get_all_refunds_for_invoice(id: 'JB49z2MsDH7FunczeyDS8j')
|
|
114
|
-
#
|
|
115
|
-
def get_all_refunds_for_invoice(id:)
|
|
116
|
-
urlpath = "invoices/#{id}/refunds"
|
|
117
|
-
invoice = get_invoice(id: id)
|
|
118
|
-
response = send_request("GET", urlpath, facade: nil, token: invoice["token"])
|
|
119
|
-
response["data"]
|
|
120
|
-
end
|
|
121
|
-
|
|
122
|
-
## Get Refund
|
|
123
|
-
# Requires merchant facade token
|
|
124
|
-
#
|
|
125
|
-
# @example:
|
|
126
|
-
# client.get_refund(id: 'JB49z2MsDH7FunczeyDS8j', request_id: '4evCrXq4EDXk4oqDXdWQhX')
|
|
127
|
-
#
|
|
128
|
-
def get_refund(id:, request_id:)
|
|
129
|
-
urlpath = "invoices/#{id}/refunds/#{request_id}"
|
|
130
|
-
invoice = get_invoice(id: id)
|
|
131
|
-
response = send_request("GET", urlpath, facade: nil, token: invoice["token"])
|
|
132
|
-
response["data"]
|
|
133
|
-
end
|
|
134
|
-
|
|
135
87
|
## Checks that the passed tokens are valid by
|
|
136
88
|
# comparing them to those that are authorized by the server
|
|
137
89
|
#
|
data/lib/bitpay/version.rb
CHANGED
data/spec/client_spec.rb
CHANGED
|
@@ -19,12 +19,6 @@ describe BitPay::SDK::Client do
|
|
|
19
19
|
.to_return(:status => 200, :body => tokens.to_json, :headers => {})
|
|
20
20
|
stub_request(:get, "#{BitPay::TEST_API_URI}/invoices/TEST_INVOICE_ID?token=MERCHANT_TOKEN").
|
|
21
21
|
to_return(:body => get_fixture('invoices_{id}-GET.json'))
|
|
22
|
-
stub_request(:get, "#{BitPay::TEST_API_URI}/invoices/TEST_INVOICE_ID/refunds?token=MERCHANT_INVOICE_TOKEN").
|
|
23
|
-
to_return(:body => get_fixture('invoices_{id}_refunds-GET.json'))
|
|
24
|
-
stub_request(:get, "#{BitPay::TEST_API_URI}/invoices/TEST_INVOICE_ID/refunds/TEST_REQUEST_ID?token=MERCHANT_INVOICE_TOKEN").
|
|
25
|
-
to_return(:body => get_fixture('invoices_{id}_refunds-GET.json'))
|
|
26
|
-
stub_request(:post, "#{BitPay::TEST_API_URI}/invoices/TEST_INVOICE_ID/refunds").
|
|
27
|
-
to_return(:body => get_fixture('invoices_{id}_refunds-POST.json'))
|
|
28
22
|
end
|
|
29
23
|
|
|
30
24
|
describe "#initialize" do
|
|
@@ -115,51 +109,6 @@ describe BitPay::SDK::Client do
|
|
|
115
109
|
end
|
|
116
110
|
end
|
|
117
111
|
|
|
118
|
-
describe '#refund_invoice' do
|
|
119
|
-
subject { bitpay_client }
|
|
120
|
-
before { stub_const('ENV', {'BITPAY_PEM' => PEM}) }
|
|
121
|
-
it { is_expected.to respond_to(:refund_invoice) }
|
|
122
|
-
|
|
123
|
-
it 'should get the token for the invoice' do
|
|
124
|
-
bitpay_client.refund_invoice(id: 'TEST_INVOICE_ID')
|
|
125
|
-
expect(WebMock).to have_requested :get, "#{BitPay::TEST_API_URI}/invoices/TEST_INVOICE_ID?token=MERCHANT_TOKEN"
|
|
126
|
-
end
|
|
127
|
-
|
|
128
|
-
it 'should generate a POST to the invoices/refund endpoint' do
|
|
129
|
-
bitpay_client.refund_invoice(id: 'TEST_INVOICE_ID')
|
|
130
|
-
expect(WebMock).to have_requested :post, "#{BitPay::TEST_API_URI}/invoices/TEST_INVOICE_ID/refunds"
|
|
131
|
-
end
|
|
132
|
-
end
|
|
133
|
-
|
|
134
|
-
describe '#get_all_refunds_for_invoice' do
|
|
135
|
-
subject { bitpay_client }
|
|
136
|
-
before {stub_const('ENV', {'BITPAY_PEM' => PEM})}
|
|
137
|
-
it { is_expected.to respond_to(:get_all_refunds_for_invoice) }
|
|
138
|
-
|
|
139
|
-
it 'should get the token for the invoice' do
|
|
140
|
-
bitpay_client.get_all_refunds_for_invoice(id: 'TEST_INVOICE_ID')
|
|
141
|
-
expect(WebMock).to have_requested :get, "#{BitPay::TEST_API_URI}/invoices/TEST_INVOICE_ID?token=MERCHANT_TOKEN"
|
|
142
|
-
end
|
|
143
|
-
it 'should GET all refunds' do
|
|
144
|
-
bitpay_client.get_all_refunds_for_invoice(id: 'TEST_INVOICE_ID')
|
|
145
|
-
expect(WebMock).to have_requested :get, "#{BitPay::TEST_API_URI}/invoices/TEST_INVOICE_ID/refunds?token=MERCHANT_INVOICE_TOKEN"
|
|
146
|
-
end
|
|
147
|
-
end
|
|
148
|
-
|
|
149
|
-
describe '#get_refund' do
|
|
150
|
-
subject { bitpay_client }
|
|
151
|
-
before {stub_const('ENV', {'BITPAY_PEM' => PEM})}
|
|
152
|
-
it { is_expected.to respond_to(:get_refund) }
|
|
153
|
-
it 'should get the token for the invoice' do
|
|
154
|
-
bitpay_client.get_refund(id: 'TEST_INVOICE_ID', request_id: 'TEST_REQUEST_ID')
|
|
155
|
-
expect(WebMock).to have_requested :get, "#{BitPay::TEST_API_URI}/invoices/TEST_INVOICE_ID?token=MERCHANT_TOKEN"
|
|
156
|
-
end
|
|
157
|
-
it 'should GET a single refund' do
|
|
158
|
-
bitpay_client.get_refund(id: 'TEST_INVOICE_ID', request_id: 'TEST_REQUEST_ID')
|
|
159
|
-
expect(WebMock).to have_requested :get, "#{BitPay::TEST_API_URI}/invoices/TEST_INVOICE_ID/refunds/TEST_REQUEST_ID?token=MERCHANT_INVOICE_TOKEN"
|
|
160
|
-
end
|
|
161
|
-
end
|
|
162
|
-
|
|
163
112
|
describe "#verify_tokens" do
|
|
164
113
|
subject { bitpay_client }
|
|
165
114
|
before {stub_const('ENV', {'BITPAY_PEM' => PEM})}
|
metadata
CHANGED
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: bitpay-sdk
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 2.3.
|
|
4
|
+
version: 2.3.1
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Bitpay, Inc.
|
|
8
8
|
autorequire:
|
|
9
9
|
bindir: bin
|
|
10
10
|
cert_chain: []
|
|
11
|
-
date: 2015-02-
|
|
11
|
+
date: 2015-02-23 00:00:00.000000000 Z
|
|
12
12
|
dependencies:
|
|
13
13
|
- !ruby/object:Gem::Dependency
|
|
14
14
|
name: json
|
|
@@ -215,6 +215,7 @@ extra_rdoc_files: []
|
|
|
215
215
|
files:
|
|
216
216
|
- ".gitignore"
|
|
217
217
|
- ".travis.yml"
|
|
218
|
+
- GUIDE.md
|
|
218
219
|
- Gemfile
|
|
219
220
|
- LICENSE.md
|
|
220
221
|
- README.md
|