| 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__ | ||