Stripe API client for Elixir
Switch branches/tags
Nothing to show
Clone or download
sikanhe Merge pull request #24 from tngan/master
Add capture/3 to do partial capture
Latest commit dd55898 Dec 29, 2017

Stripe Build Status

Stripe API client for Elixir. Documentation

  • Everything except for Relay features are complete and tested.
  • Looking for more contributors/maintainers for this project, currently need help with documentation.


  1. Add stripe to your list of dependencies in mix.exs:
def deps do
  [{:stripe, "~> 0.8.0", hex: :stripe_elixir}]
  1. (Pre-Elixir 1.4) Ensure stripe is started before your application:
def application do
  [applications: [:stripe]]
  1. Make sure your stripe secret_key is added to your config file:
config :stripe, :secret_key, <YOUR_SECRET_KEY>
  1. Alternatively, you can also set the secret key as an environment variable:

Basic Usage

This lib closely follows the official Ruby Client API.

  • Stripe.{RESOURCE}.create
  • Stripe.{RESOURCE}.retrieve
  • Stripe.{RESOURCE}.update
  • Stripe.{RESOURCE}.list

Returns {:ok, RESPONSE_BODY} when the request is successful.

{:error, %ERROR_STRUCT{}} tuples are returned when there is a request/api error.
See all error types at

Some Basic Examples

Create a customer:

{:ok, %{"id" => "cus_asdfghjkl"} =
    Stripe.Customer.create(email: "")

Note that either KeywordLists or Maps with either String or Atom keys are acceptable for arguments and options. So all of the following would also work:

Stripe.Customer.create(%{email: ""})
Stripe.Customer.create(%{"email" => ""})
Stripe.Customer.create([{"email", ""}])

Retrieve that customer:

{:ok, customer} = Stripe.Customer.retrieve("cus_asdfghjkl")

Update the customer:

{:ok, %{"metadata" => %{"somedata" => "somevalue"}}} =
  Stripe.Customer.update("cus_asdfghjkl", metadata: [somedata: "somevalue"])

Delete the customer:

{:ok, %{"deleted" => true}} = Stripe.Customer.delete("cus_asdfghjkl")

Stripe Connect

To perform a Direct Charge on a connected stripe account, simply pass :stripe_account as an option

Stripe.Charge.create([customer: "cus_asdfghjkl", amount: 400], stripe_account: "acct_sOMeAcCountId")

Generate a Connect authorization url via Stripe.Connect.authorize_url/1.

  redirect_uri: <OPTIONAL CALLBACK URL>,


  • redirect_uri: An optional callback url after authorization succeeds.
  • state: You can protect your request from CSRF attacks by passing a csrf token.
  • client_id: You can pass in an optional client_id to be used for this url. Defaults to STRIPE_CLIENT_ID environment variable or config :stripe, :client_id config value.

Handling Webhooks

Stripe uses webhooks to notify your web app with events. Stripe.Webhook provides construct_event/3 to authenticate the requests, which can be useful in plugs.

payload = # HTTP content body (e.g. from Plug.Conn.read_body/3)
signature = # 'Stripe-Signature' HTTP header (e.g. from Plug.Conn.get_req_header/2)
secret = # Provided by Stripe

case Stripe.Webhook.construct_event(payload, signature, secret) do
  {:ok, event} ->
    # Return 2XX
  {:error, %Stripe.SignatureVerificationError{}} ->
    # Return non-2XX and handle error

The default tolerance is 5 minutes (300 seconds as per official libraries). If your app is rejecting requests because the tolerance is too low, consider passing a higher number to construct_event/4.

Stripe.Webhook.construct_event(payload, signature, secret, 600)