magnet/payments.stripe

A Duct library that provides an Integrant key for interacting with the Stripe API.

Table of contents

• Installation
• Usage
  • Configuration
  • Obtaining a Stripe record
  • Available methods

Installation

Usage

Configuration

To use this library add the following key to your configuration:

:magnet.paymets/stripe

This key expects a configuration map with one unique mandatory key, plus another three optional ones. These are the mandatory keys:

• :api-key : API key to authenticate requests

These are the optional keys:

• :timeout: Timeout value (in milli-seconds) for an connection attempt with Stripe.
• :max-retries: If the connection attempt fails, how many retries we want to attempt before giving up.
• :backoff-ms: This is a vector in the form [initial-delay-ms max-delay-ms multiplier] to control the delay between each retry. The delay for nth retry will be (max (* initial-delay-ms n multiplier) max-delay-ms). If multiplier is not specified (or if it is nil), a multiplier of 2 is used. All times are in milli-seconds.
• :webhook-tolerance : Used when verifying webhook headers. Maximum difference in seconds allowed between the header's timestamp and the current time. Default value is 300 seconds.
• :idempotent-post-reqs?: Boolean value that determines whether idempotency keys should be used in POST requests or not. The default value is true.

Key initialization returns a Stripe record that can be used to perform the Stripe operations described below.

Configuration example

Basic configuration:

  :magnet.payments/stripe
   {:api-key #duct/env ["STRIPE_API_KEY" Str :or "pk_test_TYooMQauvdEDq54NiTphI7jx"]}

Configuration with custom request retry policy:

  :magnet.payments/stripe
   {:api-key #duct/env ["STRIPE_API_KEY" Str :or "pk_test_TYooMQauvdEDq54NiTphI7jx"]
    :timeout 1000
    :max-retries 3
    :backoff-ms [10 500]}

Obtaining a Stripe record

If you are using the library as part of a Duct-based project, adding any of the previous configurations to your config.edn file will perform all the steps necessary to initialize the key and return a Stripe record for the associated configuration. In order to show a few interactive usages of the library, we will do all the steps manually in the REPL.

First we require the relevant namespaces:

user> (require '[integrant.core :as ig]
               '[magnet.payments.core :as core])
nil
user>

Next we create the configuration var holding the Stripe integration configuration details:

user> (def config {:api-key #duct/env ["STRIPE_API_KEY" Str :or "pk_test_TYooMQauvdEDq54NiTphI7jx"]})
#'user/config
user>

Now that we have all pieces in place, we can initialize the :magnet.payments/stripe Integrant key to get a Stripe record. As we are doing all this from the REPL, we have to manually require magnet.payments.stripe namespace, where the init-key multimethod for that key is defined (this is not needed when Duct takes care of initializing the key as part of the application start up):

user> (require '[magnet.payments.stripe :as stripe])
nil
user>

And we finally initialize the key with the configuration defined above, to get our Stripe record:

user> (def stripe-record (->
                       config
                       (->> (ig/init-key :magnet.payments/stripe))))
#'user/stripe-record
user> stripe-record
#magnet.payments.stripe.Stripe{:api-key #duct/env ["STRIPE_API_KEY" Str :or "pk_test_TYooMQauvdEDq54NiTphI7jx"]
                               :timeout 2000,
                               :max-retries 10,
                               :backoff-ms [500 1000 2.0]}
user>

Now that we have our Stripe record, we are ready to use the methods defined by the protocols defined in magnet.payments.core namespace.

Available methods

This are the methods available to interact with the Stripe API. The mapping for the methods is one to one, so refer to the Stripe official documentation for details.

• Balance

  • (get-balance stripe-record)

• Balance Transaction

  • (get-balance-transaction stripe-record bt-id)
  • (get-balance-transactions stripe-record opt-args)

• Card

  • (create-card stripe-record customer-id card)
  • (get-card stripe-record customer-id card-id)
  • (get-all-cards stripe-record customer-id opt-args)
  • (update-card stripe-record customer-id card-id card)
  • (delete-card stripe-record customer-id card-id)

• Charge

  • (create-charge stripe-record charge)
  • (get-charge stripe-record charge-id)
  • (get-all-charges stripe-record opt-args)
  • (update-charge stripe-record charge-id charge)

• Customer

  • (create-customer stripe-record customer)
  • (get-customer stripe-record customer-id)
  • (get-all-customers stripe-record opt-args)
  • (update-customer stripe-record customer-id customer)
  • (delete-customer stripe-record customer-id) (get-customer-tax-id stripe-record customer-id tax-id)
  • (create-customer-tax-id stripe-record customer-id tax-id)
  • (delete-customer-tax-id stripe-record customer-id tax-id)

• Ephemeral Keys

  • (create-ephemeral-key stripe-record {:customer customer-id} OR {:issuing_card issuing-card-id})

  Does not have offical docs, but there are some examples in some of the guides, such as this one.

• Invoice

  • (create-invoice stripe-record invoice)
  • (get-invoice stripe-record invoice-id)
  • (get-all-invoices stripe-record opt-args)
  • (update-invoice stripe-record invoice-id invoice)
  • (delete-invoice stripe-record invoice-id)

• Plan

  • (create-plan stripe-record plan)
  • (get-plan stripe-record plan-id)
  • (get-all-plans stripe-record opt-args)
  • (update-plan stripe-record plan-id plan)
  • (delete-plan stripe-record plan-id)

• Product

  • (create-product stripe-record product)
  • (get-product stripe-record product-id)
  • (get-all-products stripe-record opt-args)
  • (update-product stripe-record product-id product)
  • (delete-product stripe-record product-id)

• Subscription

  • (create-subscription stripe-record subscription)
  • (get-subscription stripe-record subscription-id)
  • (get-all-subscriptions stripe-record opt-args)
  • (update-subscription stripe-record subscription-id subscription)
  • (cancel-subscription stripe-record subscription-id)

• PaymentMethod

  • (get-payment-method stripe-record payment-method-id)
  • (get-customer-payment-methods stripe-record customer-id payment-method-id opt-args)
  • (attach-payment-method stripe-record payment-method-id customer-id)
  • (detach-payment-method stripe-record payment-method-id)

• UsageRecord

  • (create-usage-record stripe-record subscription-item-id usage-record)
  • (get-usage-record-summaries stripe-record subscription-item-id opt-args)

• Checkout Session

  • (create-checkout-session stripe-record checkout-session)

• Events

  • (list-events stripe-record event-types opt-args)

• Webhook

  • (verify-header stripe-record payload signature-header secret)

• PaymentIntents

  • (create-payment-intent [this payment-intent])
  • (get-all-payment-intents [this opt-args])
  • (get-payment-intent [this payment-intent-id])
  • (update-payment-intent [this payment-intent-id payment-intent])
  • (confirm-payment-intent [this payment-intent-id opt-args])
  • (capture-payment-intent [this payment-intent-id opt-args])
  • (cancel-payment-intent [this payment-intent-id opt-args])

All the responses will include a :success? key. When :success? is false, :reason and error-details keys will be also included. The possible reasons are: :bad-request, not-found, access-denied and error. The error-details will include a map with the error information provided by the Stripe API.

License

Copyright (c) 2019 Magnet S Coop.

This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at https://mozilla.org/MPL/2.0/