NAME

    WebService::Braintree - A Client Library for wrapping the Braintree
    Payment Services Gateway API

 FORK

    This is a fork of the original vendor-issued Net::Braintree. While the
    original is deprecated, it continues to work. However, it contains a
    number of code-style and maintainability problems. This fork was
    produced to address some of those problems and to provide a community
    driven basis for going forward.

 DOCUMENTATION

    The module is sparsely documented, at best. The public facing API is
    very similar to the Ruby libraries which are documented at
    https://developers.braintreepayments.com/ruby/sdk/server/overview.

    You can also look over the test suite for guidance of usage, especially
    the xt/sandbox tests. Not all of these tests work (ones marked
    todo_skip. This is because they are an adaptation of code used against
    Braintree's private integration server. Care has been taken that the
    same sandbox tests that fail in this module also fail for
    Net::Braintree, and in the same manner.

 GENERAL STYLE

    In general, clients of this library will not instantiate any objects.
    Every call you make will be a class method. Some methods will return
    objects. In those cases, those objects will be documented for you.

 CONFIGURATION

    You will need to set some configuration.

        use WebService::Braintree;
    
        my $conf = WebService::Braintree->configuration;
        $conf->environment( 'sandbox' );
        $conf->merchant_id( 'use_your_merchant_id' );
        $conf->public_key( 'use_your_public_key' );
        $conf->private_key( 'use_your_private_key' );

    Please see "" in WebService::Braintree::Configuration for more
    information.

  Client Tokens

    In general, your server code (that uses this library) will be
    interacting with a client-side SDK (such as for Mobile or Javascript).
    That library will need a client token in order to interact with
    Braintree. This token will be all the client-side needs, regardless of
    whether your server is pointing at the sandbox or to production.

    This token is created with "generate" in
    WebService::Braintree::ClientToken.

 INTERFACE

    There are twelve classes that you will interface with. Please see their
    respective documentation for more detail on how to use them.

  WebService::Braintree::Address

    Create, update, delete, and find addresses.

  WebService::Braintree::ClientToken

    Generate client tokens. These are used for client-side SDKs to take
    actions.

  WebService::Braintree::CreditCard

    Create, update, delete, and find credit cards.

  WebService::Braintree::CreditCardVerification

    Find and list credit card verifications.

  WebService::Braintree::Customer

    Create, update, delete, and find customers.

  WebService::Braintree::MerchantAccount

    Create, update, and find merchant accounts.

  WebService::Braintree::PaymentMethod

    Create, update, delete, and find payment methods.

  WebService::Braintree::PayPalAccount

    Find and update PayPal accounts.

  WebService::Braintree::SettlementBatchSummary

    Generate settlement batch summaries.

  WebService::Braintree::Subscription

    Create, update, cancel, find, and handle charges for subscriptions.

  WebService::Braintree::Transaction

    Create, manage, and search for transactions. This is the workhorse
    class and it has many methods.

  WebService::Braintree::TransparentRedirect

    Manage the transparent redirection of ????.

    NOTE: This class needs significant help in documentation.

 SEARCHING

    Several of the class interfaces provide a search() method. This method
    is unique in that it takes a subroutine reference (subref) instead of a
    hashref or other parameters.

    Documentation for this is forthcoming.

 ISSUES

    The bugtracker is at
    https://github.com/singingfish/braintree_perl/issues.

    Patches welcome!

 CONTRIBUTING

    Contributions are welcome. The process:

    Submissions

      Please fork this repository on Github, create a branch, then submit a
      pull request from that branch to the master of this repository. All
      other submissions will be summarily rejected.

    Developer Environment

      We use Docker to encapsulate the developer environment. There is a
      Bash script in the root called run_tests that provides an entrypoint
      to how this project uses Docker. The sequence is:

      run_tests build [ command ]

      run_tests test [ command ]

      run_tests integration [ command ]

      run_tests cover

      You can optionally select a Perl version or versions (5.10 through
      5.24) to run the command against by setting the PERL_VERSIONS
      environment variable. Use a space to separate multiple versions.

      This Bash script has been tested to work in Linux, OSX, and GitBash
      on Windows.

    Running the tests in xt/

      The tests in t/ are unit tests. The tests in xt/ are E2E tests that
      run against Braintree's sandbox / integration environment. To run
      them, you will need to have a Braintree sandbox account linked to
      Paypal.

      Signup

	Navigate to https://www.braintreepayments.com/sandbox. Enter your
	first name, last name, Comany name of "WebService::Braintree", your
	country, and your email address.

      Activate your account

	You will receive an email to the address you provided which will
	contain a link. Click on it and you'll sent to a page where you
	will be asked for a password.

      Create a sandbox_config.json

	On the dashboard page of your new sandbox account, three are three
	values you will need to put into a sandbox_config.json. The format
	of the file must be:

            {
              "merchant_id": "<< value 1 >>",
              "public_key": "<< value 2 >>",
              "private_key": "<< value 3 >>"
            }

	replacing what's in the double-quotes with the appropriate values
	from your Braintree sandbox's dashboard.

      Link your Paypal Sandbox Account

	You'll need to follow the instructions at
	https://developers.braintreepayments.com/guides/paypal/testing-go-live/ruby#linked-paypal-testing.
	This is required for some of the integration tests to pass.

	Within Setting > Processing, select "Link your sandbox" within the
	PayPal section.

	Once at the Paypal Developer Dashboard:

	  * My Apps & Credentials

	  * Rest Apps

	  * Create new App

	  * Give it a name

	  * Copy the information requested back to Braintree

      Run the tests

	You can now run the integration tests with run_tests integration.
	These tests will take between 5 and 20 minutes.

 TODO/WISHLIST/ROADMAP

    There is no pod documentation.

    Sandbox tests fail

      Some of this is likely needed because the sandbox account needs to be
      set up just right, and some may be because the paypal test
      integration server is emulating stateful transactions.

    Excessive metaobject wrangling

      The usage of Moose in this code is sub-opimtimal. In particular the
      following classes use the metaobject in a way that makes what is
      happening difficult to understand:

      WebService::Braintree::ResultObject

	This class is now the only one that is not immutable in the
	codebase. Unpicking how to make this mutable is problematic.

	The constructors for the following should be fixed to be explicit
	(requires understanding of what ResultObject is doing):

      WebService::Braintree::AdvancedSearchFields

      WebService::Braintree::SubscriptionSearch

      WebService::Braintree::CreditCardVerificationSearch

      WebService::Braintree::CustomerSearch

      WebService::Braintree::Result

      WebService::Braintree::TransactionSearch

      Also, having stared at the internals of some objects in the perl
      debugger for a bit, I fear there may be memory leaks, but I have not
      investigated this closely. It's also possible that the way that
      several of the above methods use a $field variable in package lexical
      scope that this module may not be fork-safe. These concerns also
      apply to Net::Braintree (only it has a bigger memory footprint).

    Sandbox tests

      One of the sandbox tests is really really slow.

 ACKNOWLEDGEMENTS

    Thanks to the staff at Braintree for endorsing this fork.

 LICENSE AND COPYRIGHT

    Copyright 2017 Kieren Diment <zarquon@cpan.org>

    Copyright 2011-2014 Braintree, a division of PayPal, Inc.

    This program is free software; you can redistribute it and/or modify it
    under the terms of either: the GNU General Public License as published
    by the Free Software Foundation; or the Artistic License.

    See http://dev.perl.org/licenses/ for more information.

