Stripe for Elixir

An Elixir library for working with Stripe.

2.x.x status

Which version should I use?

Below is a list of which Stripe API version recent releases of Stripe Elixir. It only indicates the API version being called, not necessarily its compatibility. See the Stripe API Upgrades page for more details.

Starting with stripity_stripe version 2.5.0, you can specify the Stripe API Version to use for a specific request by including the :api_version option. Note that while this will use a specific Stripe API Version to make the request, the library will still expect a response matching its corresponding default Stripe API Version. See the Shared Options documentation for more details.

Documentation

• Latest HexDocs

Installation

Install the dependency by version:

{:stripity_stripe, "~> 2.0"}

Or by commit reference:

{:stripity_stripe, git: "https://github.com/beam-community/stripity_stripe", ref: "017d7ecdb5aeadccc03986c02396791079178ba2"}

Next, add to your applications:

Not necessary if using elixir >= 1.4

defp application do
  [applications: [:stripity_stripe]]
end

Configuration

To make API calls, it is necessary to configure your Stripe secret key.

import Config

config :stripity_stripe, api_key: System.get_env("STRIPE_SECRET")
# OR
config :stripity_stripe, api_key: "YOUR SECRET KEY"

It's possible to use a function or a tuple to resolve the secret:

config :stripity_stripe, api_key: {MyApp.Secrets, :stripe_secret, []}
# OR
config :stripity_stripe, api_key: fn -> System.get_env("STRIPE_SECRET") end

Moreover, if you are using Poison instead of Jason, you can configure the library to use Poison like so:

config :stripity_stripe, json_library: Poison

Timeout

To set timeouts, pass opts for the http client. The default one is Hackney.

config :stripity_stripe, hackney_opts: [{:connect_timeout, 1000}, {:recv_timeout, 5000}]

Request Retries

To set retries, you can pass the number of attempts and range of backoff (time between attempting the request again) in milliseconds.

config :stripity_stripe, :retries, [max_attempts: 3, base_backoff: 500, max_backoff: 2_000]

Examples

Stripe supports a token based, and intent based approach for processing payments. The token based approach is simpler, but it is not supported in Europe. The intents API is the way forward, and should be used for new development.

Intents

Create a new SetupIntent object in Stripe. The created intent ID will be passed to the frontend to use with Stripe elements so the end user can enter their payment details. SetupIntents are ephemeral. It is best to create a new one each time the user reaches your payment page.

{:ok, setup_intent} = Stripe.SetupIntent.create(%{})

# Return the ID to your frontend, and pass it to the confirmCardSetup method from Stripe elements
{:ok, setup_intent.id}

On the frontend, use the setup intent ID you created in conjunction with Stripe elements confirmCardSetup method.

stripe.confirmCardSetup(setupIntentId, {
  payment_method: {
    ...
  }
})
.then(result => {
  const setupIntentId = result.setupIntent.id
  const paymentMethodId = result.setupIntent.payment_method

  // send the paymentMethodId and optionally (if needed) the setupIntentId
})

With the new payment method ID, you can associate the payment method with a Stripe customer.

Get an existing customer.

{:ok, stripe_customer} = Stripe.Customer.retrieve(stripe_customer_id)

Or create a new one.

new_customer = %{
  email: email,
}

{:ok, stripe_customer} = Stripe.Customer.create(new_customer)

Attach the payment method to the customer.

{:ok, _result} = Stripe.PaymentMethod.attach(%{customer: stripe_customer.id, payment_method: payment_method_id})

Now you can charge the customer using a PaymentIntent from Stripe. Since we used a setup intent initially, the payment intent will be authorized to make payments off session, for example to charge for a recurring subscription.

{:ok, charge} = Stripe.PaymentIntent.create(%{
  amount: cents_int,
  currency: "USD",
  customer: stripe_customer.id,
  payment_method: payment_method_id,
  off_session: true,
  confirm: true
})

Note: Object Expansion

Some Stripe API endpoints support returning related objects via the object expansion query parameter. To take advantage of this feature, stripity_stripe accepts a list of strings to be passed into opts under the :expand key indicating which objects should be expanded.

For example, calling Charge.retrieve("ch_123") would return a charge without expanding any objects.

%Charge{
  id: "ch_123",
  balance_transaction: "txn_123",
  ...
}

However if we now include an expansion on the balance_transaction field using

Charge.retrieve("ch_123", expand: ["balance_transaction"])

We will get the full object back as well.

%Charge{
  id: "ch_123",
  balance_transaction: %BalanceTransaction{
    id: "txn_123",
    fee: 125,
    ...
  },
  ...
}

For details on which objects can be expanded check out the stripe object expansion docs.

Testing

Starting stripe-mock

To run the tests you'll need to install stripe-mock. It is a mock HTTP server that responds like the real Stripe API. It's powered by the Stripe OpenAPI specification, which is generated from within Stripe's API.

The stripe-mock instructions have more details, but if you have docker installed already you can quickly and easily start an instance to test against:

docker run --rm -it -p 12111-12112:12111-12112 stripe/stripe-mock:latest

Running the tests

By default, mix test will start stripe-mock by finding and invoking the stripe-mock executable. If you would prefer to start it yourself, do so and add an env var SKIP_STRIPE_MOCK_RUN to skip starting stripe-mock. Any value will do. Example:

SKIP_STRIPE_MOCK_RUN=1 mix test

To configure your test environment to use the local stripe-mock server, you may need to set the api_base_url field in your config:

config :stripity_stripe,
  api_key: "sk_test_thisisaboguskey",
  api_base_url: "http://localhost:12111"

Documentation for 1.x.x

Contributing

Feedback, feature requests, and fixes are welcomed and encouraged. Please make appropriate use of Issues and Pull Requests. All code should have accompanying tests.

License

Please see LICENSE.md for licensing details.

History

Statement from original author

Why another Stripe Library? Currently there are a number of them in the Elixir world that are, well just not "done" yet. I started to fork/help but soon it became clear to me that what I wanted was

• an existing/better test story
• an API that didn't just mimic a REST interaction
• a library that was up to date with Elixir > 1.0 and would, you know, actually compile.
• function calls that returned a standard {:ok, result} or {:error, message} response

As I began digging things up with these other libraries it became rather apparent that I was not only tweaking the API, but also ripping out a lot of the existing code... and that usually means I should probably do my own thing. So I did.