lib/WebService/Braintree.pm

filter: Statementstmt 100% 94 / 94 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 31 / 31 Podpod 0.0% 0 / 1 totaltotal 99.2% 125 / 126 CC 1 SCAR 0.0
CC
1
Cov
100%
BEGIN
1.0
BEGIN
1.0
BEGIN
1.0
CRAP 1.0
« lib/WebService/Braintree/Types.pm ↑ Summary lib/WebService/Braintree/ApplePayCard/CardType.pm »
1 # vim: sw=4 ts=4 ft=perl
2  
3 package WebService::Braintree;
4 22 $WebService::Braintree::VERSION = '1.7';
5 22 ▶use 5.010_001;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 22 ▶use strictures 1;
Subroutine BEGIN: called CC=1 SCAR=0.0
7  
8 # Load the error codes omnibus so clients can get at them.
9 22 ▶use WebService::Braintree::ErrorCodes;
Subroutine BEGIN: called CC=1 SCAR=0.0
10  
11 # Load all the interfaces so clients can get at them.
12 22 ▶use WebService::Braintree::AddOn;
Subroutine BEGIN: called CC=1 SCAR=0.0
13 22 ▶use WebService::Braintree::Address;
Subroutine BEGIN: called CC=1 SCAR=0.0
14 22 ▶use WebService::Braintree::ApplePay;
Subroutine BEGIN: called CC=1 SCAR=0.0
15 22 ▶use WebService::Braintree::ClientToken;
Subroutine BEGIN: called CC=1 SCAR=0.0
16 22 ▶use WebService::Braintree::CreditCard;
Subroutine BEGIN: called CC=1 SCAR=0.0
17 22 ▶use WebService::Braintree::CreditCardVerification;
Subroutine BEGIN: called CC=1 SCAR=0.0
18 22 ▶use WebService::Braintree::Customer;
Subroutine BEGIN: called CC=1 SCAR=0.0
19 22 ▶use WebService::Braintree::Discount;
Subroutine BEGIN: called CC=1 SCAR=0.0
20 22 ▶use WebService::Braintree::Dispute;
Subroutine BEGIN: called CC=1 SCAR=0.0
21 22 ▶use WebService::Braintree::DocumentUpload;
Subroutine BEGIN: called CC=1 SCAR=0.0
22 22 ▶use WebService::Braintree::EuropeBankAccount;
Subroutine BEGIN: called CC=1 SCAR=0.0
23 22 ▶use WebService::Braintree::IdealPayment;
Subroutine BEGIN: called CC=1 SCAR=0.0
24 22 ▶use WebService::Braintree::Merchant;
Subroutine BEGIN: called CC=1 SCAR=0.0
25 22 ▶use WebService::Braintree::MerchantAccount;
Subroutine BEGIN: called CC=1 SCAR=0.0
26 22 ▶use WebService::Braintree::PaymentMethod;
Subroutine BEGIN: called CC=1 SCAR=0.0
27 22 ▶use WebService::Braintree::PaymentMethodNonce;
Subroutine BEGIN: called CC=1 SCAR=0.0
28 22 ▶use WebService::Braintree::PayPalAccount;
Subroutine BEGIN: called CC=1 SCAR=0.0
29 22 ▶use WebService::Braintree::Plan;
Subroutine BEGIN: called CC=1 SCAR=0.0
30 22 ▶use WebService::Braintree::SettlementBatchSummary;
Subroutine BEGIN: called CC=1 SCAR=0.0
31 22 ▶use WebService::Braintree::Subscription;
Subroutine BEGIN: called CC=1 SCAR=0.0
32 22 ▶use WebService::Braintree::Transaction;
Subroutine BEGIN: called CC=1 SCAR=0.0
33 22 ▶use WebService::Braintree::TransactionLineItem;
Subroutine BEGIN: called CC=1 SCAR=0.0
34 22 ▶use WebService::Braintree::TransparentRedirect;
Subroutine BEGIN: called CC=1 SCAR=0.0
35 22 ▶use WebService::Braintree::UsBankAccount;
Subroutine BEGIN: called CC=1 SCAR=0.0
36 22 ▶use WebService::Braintree::WebhookNotification;
Subroutine BEGIN: called CC=1 SCAR=0.0
37 22 ▶use WebService::Braintree::WebhookTesting;
Subroutine BEGIN: called CC=1 SCAR=0.0
38  
39 # Finally, load the configuration class.
40 22 ▶use WebService::Braintree::Configuration;
Subroutine BEGIN: called CC=1 SCAR=0.0
41  
42 =head1 NAME
43  
44 WebService::Braintree - A Client Library for wrapping the Braintree Payment
45 Services Gateway API
46  
47 =head2 FORK
48  
49 This is a fork of the original vendor-issued L<Net::Braintree>. While the
50 original is deprecated, it continues to work. However, it contains a number
51 of code-style and maintainability problems. This fork was produced to
52 address some of those problems and to provide a community driven basis for
53 going forward.
54  
55 =head2 DOCUMENTATION
56  
57 The module is fully documented, but that documentation is reverse-engineered.
58 The public facing API is very similar to the Ruby libraries which are documented
59 at L<https://developers.braintreepayments.com/ruby/sdk/server/overview>.
60  
61 You can also look over the test suite for guidance of usage, especially the
62 C<t/sandbox> tests. Not all of these tests work (ones marked
63 C<todo_skip>). This is because they are an adaptation of code used against
64 Braintree's private integration server.
65  
66 As of version 0.94, with appropriate manual intervention for your sandbox
67 account (documented in C<t/sandbox/README>), more of the sandbox tests
68 run/pass for this module than for the original module L<Net::Braintree>.
69  
70 =head2 OBJECT VS CLASS INTERFACE
71  
72 As of January, 2018, Braintree released a large refactoring to how clients
73 interact with the Braintre API. They call the different class (old-style) vs.
74 object (new-style). Under the old style, configuration is global and all the
75 interactions with the API use the same configuration. Under the new style, each
76 call I<could> use a new configuration, if needed.
77  
78 Both styles will be supported for the foreseeable future. Clients can still set
79 a global configuration and use the class interface, just like before.
80  
81 In the documentation below, everything applies to both styles, except where
82 otherwise noted. If there is a difference between them, an exmaple of both will
83 be provided.
84  
85 =head2 GENERAL STYLE
86  
87 In general, clients of this library will not instantiate any objects. Every
88 call you make will be a class method. Some methods will return objects. In
89 those cases, those objects will be documented for you.
90  
91 Unless otherwise noted, all attributes in these objects will be read-only and
92 will have been populated by the responses from Braintree.
93  
94 =head3 Object Style
95  
96 If you use the object style, then you will instantiate and manage instances of
97 gateway objects. Each gateway object will have its own configuration.
98  
99 =cut
100  
101 {
102 22 my $configuration_instance = WebService::Braintree::Configuration->new;
103 93 ▶ sub configuration { return $configuration_instance; }
Subroutine configuration: called CC=1 SCAR=0.0
Pod undocumented
104 }
105  
106 =head2 CONFIGURATION
107  
108 You will need to set some configuration. Please see
109 L<WebService::Braintree::Configuration/> for details.
110  
111 =head3 Class Style
112  
113 use WebService::Braintree;
114  
115 my $conf = WebService::Braintree->configuration;
116 $conf->environment( 'sandbox' );
117 $conf->merchant_id( 'use_your_merchant_id' );
118 $conf->public_key( 'use_your_public_key' );
119 $conf->private_key( 'use_your_private_key' );
120  
121 my $result = WebService::Braintree::Transaction->sale(
122 ...
123 );
124  
125 =head3 Object Style
126  
127 use WebService::Braintree;
128  
129 my $gateway = WebService::Braintree::Gateway->new({
130 environment => 'sandbox',
131 merchant_id => 'use_your_merchant_id',
132 public_key => 'use_your_public_key',
133 private_key => 'use_your_private_key',
134 });
135  
136 my $result = $gateway->transaction->sale(
137 ...
138 );
139  
140 =head3 Client Tokens
141  
142 In general, your server code (that uses this library) will be interacting with
143 a client-side SDK (such as for Mobile or Javascript). That library will need a
144 client token in order to interact with Braintree. This token will be all the
145 client-side needs, regardless of whether your server is pointing at the sandbox
146 or to production.
147  
148 This token is created with L<WebService::Braintree::ClientToken/generate>.
149  
150 =head2 OBJECT INTERFACE
151  
152 The object interface is described on each of the gateway classes. In general,
153 they are identical to the class interface described below, with the change that
154 you have invoked a method on a generic C<< $gateway >> object instead of using
155 the class.
156  
157 q.v. L<WebService::Braintree::Gateway> for more information.
158  
159 =head2 CLASS INTERFACE
160  
161 These are the classes that you will interface with. Please see their
162 respective documentation for more detail on how to use them. These classes
163 only provide class methods. These methods all invoke some part of the
164 Braintree API.
165  
166 =head3 L<WebService::Braintree::AddOn>
167  
168 List all plan add-ons.
169  
170 =head3 L<WebService::Braintree::Address>
171  
172 Create, update, delete, and find addresses.
173  
174 =head3 L<WebService::Braintree::ApplePay>
175  
176 List, register, and unregister ApplePay domains.
177  
178 =head3 L<WebService::Braintree::ClientToken>
179  
180 Generate client tokens. These are used for client-side SDKs to take actions.
181  
182 =head3 L<WebService::Braintree::CreditCard>
183  
184 Create, update, delete, and find credit cards.
185  
186 =head3 L<WebService::Braintree::CreditCardVerification>
187  
188 Find and list credit card verifications.
189  
190 =head3 L<WebService::Braintree::Customer>
191  
192 Create, update, delete, and find customers.
193  
194 =head3 L<WebService::Braintree::Discount>
195  
196 List all plan discounts.
197  
198 =head3 L<WebService::Braintree::Dispute>
199  
200 Accept, and find disputes.
201  
202 =head3 L<WebService::Braintree::DocumentUpload>
203  
204 Manage document uploads.
205  
206 =head3 L<WebService::Braintree::EuropeBankAccount>
207  
208 Find Europe Bank Accounts.
209  
210 =head3 L<WebService::Braintree::IdealPayment>
211  
212 Find IdealPayment payment methods.
213  
214 =head3 L<WebService::Braintree::Merchant>
215  
216 Provision merchants from "raw ApplePay".
217  
218 =head3 L<WebService::Braintree::MerchantAccount>
219  
220 Create, update, and find merchant accounts.
221  
222 =head3 L<WebService::Braintree::PaymentMethod>
223  
224 Create, update, delete, and find payment methods.
225  
226 =head3 L<WebService::Braintree::PaymentMethodNonce>
227  
228 Create, update, delete, and find payment method nonces.
229  
230 =head3 L<WebService::Braintree::PayPalAccount>
231  
232 Find and update PayPal accounts.
233  
234 =head3 L<WebService::Braintree::Plan>
235  
236 List all subscription plans.
237  
238 =head3 L<WebService::Braintree::SettlementBatchSummary>
239  
240 Generate settlement batch summaries.
241  
242 =head3 L<WebService::Braintree::Subscription>
243  
244 Create, update, cancel, find, and handle charges for subscriptions.
245  
246 =head3 L<WebService::Braintree::Transaction>
247  
248 Create, manage, and search for transactions. This is the workhorse class and it
249 has many methods.
250  
251 =head3 L<WebService::Braintree::TransactionLineItem>
252  
253 Find all the transaction line-items.
254  
255 =head3 L<WebService::Braintree::TransparentRedirect>
256  
257 Manage the transparent redirection of ????.
258  
259 B<NOTE>: This class needs significant help in documentation.
260  
261 =head3 L<WebService::Braintree::UsBankAccount>
262  
263 Find US Bank Accounts.
264  
265 =head2 SEARCHING
266  
267 Several of the interfaces provide a C<< search() >> method. This method
268 is unique in that it takes a subroutine reference (subref) instead of a hashref
269 or other parameters.
270  
271 =head3 Example
272  
273 my $results = WebService::Braintree::Transaction->search(sub {
274 my $search = shift;
275 $search->amount->between(10, 20);
276 });
277  
278 =head3 Additional Documentation
279  
280 The various field types are documenated at L<WebService::Braintree::AdvancedSearchNodes>.
281  
282 =head2 RESPONSES
283  
284 Responses from the interface methods will either be a
285 L<Result|WebService::Braintree::Result/> or an
286 L<ErrorResult|WebService::Braintree::ErrorResult/>. You can distinguish between
287 them by calling C<< $result->is_success >>.
288  
289 =head3 Success
290  
291 If the request is successful, Braintee will reply back and you will receive
292 (in most cases) a L<result/WebService::Braintree::Result> object. This object
293 will allow you to access the various components of the response.
294  
295 In some cases, you will receive something different. Those cases are documented
296 in the method itself.
297  
298 =head3 Failure
299  
300 If there is an issue with the request, Braintree will reply back and you will
301 receive a L<ErrorResult/WebService::Braintree::ErrorResult> object. It will
302 contain a L<collection/WebService::Braintree::ValidationErrorCollection> of
303 L<errors/WebService::Braintree::Error> explaining each issue with the request.
304  
305 =head2 ISSUES
306  
307 The bugtracker is at L<https://github.com/singingfish/braintree_perl/issues>.
308  
309 Patches welcome!
310  
311 =head2 CONTRIBUTING
312  
313 Contributions are welcome. The process:
314  
315 =over 4
316  
317 =item Submissions
318  
319 Please fork this repository on Github, create a branch, then submit a pull
320 request from that branch to the master of this repository. All other
321 submissions will be summarily rejected.
322  
323 =item Developer Environment
324  
325 We use Docker to encapsulate the developer environment. There is a Bash script
326 in the root called C<< run_tests >> that provides an entrypoint to how this
327 project uses Docker. The sequence is:
328  
329 =over 4
330  
331 =item run_tests build
332  
333 This will build the Docker developer environment for each Perl version listed
334 in C<< PERL_VERSIONS >>
335  
336 =item run_tests unit [ command ]
337  
338 This will run the unit tests for each Perl version listed in
339 C<< PERL_VERSIONS >>. You can provide a C<< prove >> command to limit which
340 test(s) you run.
341  
342 =item run_tests integration [ command ]
343  
344 This will run the sandbox tests for each Perl version listed in
345 C<< PERL_VERSIONS >>. You can provide a C<< prove >> command to limit which
346 test(s) you run.
347  
348 =item run_tests cover
349  
350 This will run the all the tests for each Perl version listed in
351 C<< PERL_VERSIONS >> and calculate the coverage.
352  
353 =back
354  
355 You can optionally select a Perl version or versions (5.10 through 5.24) to
356 run the command against by setting the C<< PERL_VERSIONS >> environment
357 variable. Use a space to separate multiple versions.
358  
359 This Bash script has been tested to work in Linux, OSX, and GitBash on Windows.
360  
361 =over 4
362  
363 =item Signup
364  
365 Navigate to L<https://www.braintreepayments.com/sandbox>. Enter your first name,
366 last name, Company name of "WebService::Braintree", your country, and your email
367 address.
368  
369 =item Activate your account
370  
371 You will receive an email to the address you provided which will contain a link.
372 Click on it and you'll sent to a page where you will be asked for a password.
373  
374 =item Create a sandbox_config.json
375  
376 On the dashboard page of your new sandbox account, three are three values you
377 will need to put into a C<< sandbox_config.json >>. The format of the file must
378 be:
379  
380 {
381 "merchant_id": "<< value 1 >>",
382 "public_key": "<< value 2 >>",
383 "private_key": "<< value 3 >>"
384 }
385  
386 replacing what's in the double-quotes with the appropriate values from your
387 Braintree sandbox's dashboard.
388  
389 =item Link your Paypal Sandbox Account
390  
391 You'll need to follow the instructions at L<< https://developers.braintreepayments.com/guides/paypal/testing-go-live/ruby#linked-paypal-testing >>. This is
392 required for some of the integration tests to pass.
393  
394 Within Setting > Processing, select "Link your sandbox" within the PayPal
395 section.
396  
397 Once at the Paypal Developer Dashboard:
398  
399 =over 4
400  
401 =item * My Apps & Credentials
402  
403 =item * Rest Apps
404  
405 =item * Create new App
406  
407 =item * Give it a name
408  
409 =item * Copy the information requested back to Braintree
410  
411 =back
412  
413 =item Run the tests
414  
415 You can now run the integration tests with C<< run_tests integration >>. These
416 tests will take between 5 and 20 minutes.
417  
418 =back
419  
420 =back
421  
422 =head2 TODO/WISHLIST/ROADMAP
423  
424 =over 4
425  
426 =item Many of the integration tests are still skipped.
427  
428 =item There aren't enough unit tests.
429  
430 =item The documentation is still sparse, especially for the PURPOSE sections.
431  
432 =back
433  
434 =head2 ACKNOWLEDGEMENTS
435  
436 Thanks to the staff at Braintree for endorsing this fork.
437  
438 Thanks to ZipRecruiter for sponsoring improvements to the forked code.
439  
440 Thanks to Rob Kinyon for refactoring significant portions of the codebase.
441  
442 =head2 LICENSE AND COPYRIGHT
443  
444 Copyright 2017 Kieren Diment <zarquon@cpan.org>
445  
446 Copyright 2011-2014 Braintree, a division of PayPal, Inc.
447  
448 This program is free software; you can redistribute it and/or modify it
449 under the terms of either: the GNU General Public License as published
450 by the Free Software Foundation; or the Artistic License.
451  
452 See http://dev.perl.org/licenses/ for more information.
453  
454 =cut
455  
456 22 1; # End of WebService::Braintree
457 __END__
« lib/WebService/Braintree/Types.pm ↑ Summary lib/WebService/Braintree/ApplePayCard/CardType.pm »