README.md

Braintree

A native Braintree client library for Elixir.

Installation

Add braintree to your list of dependencies in mix.exs:

def deps do
  [{:braintree, "~> 0.13"}]
end

Once that is configured you are all set. Braintree is a library, not an application, but it does rely on hackney, which must be started. For Elixir versions < 1.4 you'll need to include it in the list of applications:

def application do
  [applications: [:braintree]]
end

Within your application you will need to configure the merchant id and authorization keys. You do not want to put this information in your config.exs file! Either put it in a {prod,dev,test}.secret.exs file which is sourced by config.exs, or read the values in from the environment:

config :braintree,
  environment: :sandbox,
  master_merchant_id: {:system, "BRAINTREE_MASTER_MERCHANT_ID"},
  merchant_id: {:system, "BRAINTREE_MERCHANT_ID"},
  public_key:  {:system, "BRAINTREE_PUBLIC_KEY"},
  private_key: {:system, "BRAINTREE_PRIVATE_KEY"}

Furthermore, the environment defaults to :sandbox, so you'll want to configure it with :production in prod.exs.

You may optionally pass directly those configuration keys to all functions performing an API call. In that case, those keys will be used to perform the call.

You can optionally configure Hackney options with:

config :braintree,
  http_options: [
    timeout: 30_000, # default, in milliseconds
    recv_timeout: 5000 # default, in milliseconds
  ]

Usage

The online documentation for Ruby/Java/Python etc. will give you a general idea of the modules and available functionality. Where possible the namespacing has been preserved.

The CRUD functions for each action module break down like this:

alias Braintree.Customer
alias Braintree.ErrorResponse, as: Error

case Customer.create(%{company: "Whale Corp"}) do
  {:ok, %Customer{} = customer} -> do_stuff_with_customer(customer)
  {:error, %Error{} = error}    -> do_stuff_with_error(error)
end

Searching

Search params are constructed with a fairly complex structure of maps. There isn't a DSL provided, so queries must be constructed by hand. For example, to search for a customer:

search_params = %{
  first_name: %{is: "Jenna"},
  last_name: %{
    starts_with: "Smith",
    contains: "ith",
    is_not: "Smithsonian"
  },
  email: %{ends_with: "gmail.com"}
}

{:ok, customers} = Braintree.Customer.search(search_params)

Or, to search for pending credit card verifications within a particular dollar amount:

search_params = %{
  amount: %{
    min: "10.0",
    max: "15.0"
  },
  status: ["approved", "pending"]
}

{:ok, verifications} = Braintree.CreditCardVerification.search(search_params)

Telemetry

If the telemetry application is running, the library will emit telemetry events.

Immediately before the HTTP request is fired, a start event will be fired with the following shape:

 event name:    [:braintree, :request, :start]
 measurements:  %{system_time: System.system_time()}
 meta data:     %{method: method, path: path}

Once the HTTP call completes, a stop event will be fired with the following shape:

 event name:    [:braintree, :request, :stop]
 measurements:  %{duration: duration}
 meta data:     %{method: method, path: path, http_status: status}

If Hackney returns an error, an error event will be fired with the following shape:

 event name:    [:braintree, :request, :error]
 measurements:  %{duration: duration}
 meta data:     %{method: method, path: path, error: error_reason}

If an exception is raised during the Hackney call, an exception event will be fired with the following shape:

 event name:    [:braintree, :request, :exception]
 measurements:  %{duration: duration}
 meta data:     %{method: method, path: path, kind: error_type, reason: error_message, stacktrace: stacktrace}

Testing

You'll need a Braintree sandbox account to run the integration tests. Also, be sure that your account has Duplicate Transaction Checking disabled.

Merchant Account Features

In order to test the merchant account features, your sandbox account needs to have a master merchant account and it needs to be added to your environment variables (only needed in test).

Your environment needs to have the following:

• Add-ons with ids: "bronze", "silver" and "gold"
• Plans with ids: "starter", "business"
• "business" plan needs to include the following add-ons: "bronze" and "silver"

PayPal Account Testing

PayPal testing uses the mocked API flow, which requires linking a sandbox PayPal account. You can accomplish that by following the directions for linked paypal testing.

Testing Using Only localhost

You can optionally configure the sandbox endpoint url to point towards a local url and port for testing which does not need to call out to the Braintree sandbox API. For example, in your config.exs

config :braintree, :sandbox_endpoint, "localhost:4001"

In conjuction with a libary such as Bypass you can use this config to define test-specific returns from Braintree calls without hitting the Braintree sandbox API.

License

MIT License, see LICENSE.txt for details.