++ed by:

1 non-PAUSE user.

Kieren Diment


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


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.


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.

As of version 0.94, with appropriate manual intervention for your sandbox account (documented in t/sandbox/README), more of the sandbox tests run/pass for this module than for the original module Net::Braintree.


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.


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.


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


List all plan add-ons.


Create, update, delete, and find addresses.


List, register, and unregister ApplePay domains.


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


Create, update, delete, and find credit cards.


Find and list credit card verifications.


Create, update, delete, and find customers.


List all plan discounts.


Accept, and find disputes.


Provision merchants from "raw ApplePay".


Create, update, and find merchant accounts.


Create, update, delete, and find payment methods.


Find and update PayPal accounts.


List all subscription plans.


Generate settlement batch summaries.


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


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


Manage the transparent redirection of ????.

NOTE: This class needs significant help in documentation.


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.


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

Patches welcome!


Contributions are welcome. The process:


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.


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.

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.


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:


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):


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.


Thanks to the staff at Braintree for endorsing this fork.

Thanks to ZipRecruiter for sponsoring improvements to the forked code.

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.