bitpay-sdk 2.3.0 → 2.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- 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
|