Most web applications you want to build will include billing at some point. While it’s relatively straightforward to incorporate Stripe using one of their official SDKs, it isn’t for languages like Common Lisp. Sure, you can just handle everything via the REST API directly but chances are that if you’re just starting out with Common Lisp that you already have your hands full grokking other concepts and want to write minimal code for basic things. Ideally, we’d have some resource that you can look over and copy-paste.
Well, sorry to burst your bubble, but said resources don’t exist. I tried to look up how others have added billing to their projects but I couldn’t find anything.
The most common sentiment I’ve read is that it’s not hard and most just interact with the API directly. Sure, it’s not hard but sharing how others go on about building their projects would be helpful to newcomers.
So I’m going to share how I approached it.
First things first, we want to see which libraries are available for our use case. As it turns out, this Awesome Common Lisp repo is a great resource for finding good libraries that are used within the community.
Under the Third-party APIs section we’ll find that there are two Stripe libraries. Yes, just two, although neither is polished and one is a wrapper around various payment processors. There are more libraries available outside of this list but they’re not working with the latest API version.
I would recommend the other library, which was originally created by Michael Fiano. However, he has since quit the community, and I’ve taken over maintenance. This transition allows us to bring the library up to speed with the latest API features, including webhook support.
git clone https://github.com/boogsbunny/stripe
You have to have a Stripe account with an API key and should read through how to receive Stripe events in your webhook endpoint.
These are the libraries we’ll be using to get started:
Before diving into the billing flow, let’s first store the Stripe API key and webhook signing secret.
We’ll do this by reading in the environment variables that you’ll have to set.
(defmacro env-var (name var)
"Define a function that retrieves the value of an environment variable."
`(defun ,name ()
(or (uiop:getenv ,var) "")))
(env-var stripe-secret-key "STRIPE_SECRET_KEY")
(env-var stripe-webhook-secret "STRIPE_WEBHOOK_SECRET")
Next, we need to set the API key:
(setf stripe:*api-key* (stripe-secret-key))
Let’s focus on user subscriptions specifically, where customers are making recurring payments to access your product. Here’s an article by Stripe on how subscriptions work.
I’ll keep it simple for my use case. I have a landing page with a pricing section describing different tiers of my product with varying price points. The user can click on any of these sections to subscribe to that tier.
Our frontend needs to include this script element:
After they select a tier, we want to redirect them to the checkout page. Facilitating this process is called a session. We need to add buttons for each subscription tier that hit our API endpoint to redirect them to our session URL.
Here’s the function that handles the redirection:
(defun redirect-to (url &optional (format-control "Redirected") format-args)
"Redirects the client to the specified URL with an optional message."
(setf (getf snooze::*clack-response-headers* :location) url)
(snooze:http-condition 302 (format nil "~?" format-control format-args)))
Now, we’ll define the `add-subscription` function, which creates a checkout session with Stripe and redirects the user to the appropriate URL:
(defun add-subscription ()
"Redirects the user to the Stripe checkout session URL for the selected plan."
(redirect-to
(stripe:session-url
(stripe:create-session
:cancel-url ""
:line-items '(("price" "" "quantity" 1))
:mode "subscription"
:payment-method-types '("card")
:success-url ""))))
Stripe provides webhook notifications to inform your application about events like payments or subscription status changes. We need to handle these events by processing the incoming JSON data.
Let’s start by defining a utility function `parse-stream` that reads the contents of a stream and returns it as a vector of unsigned bytes:
;;;; Original code provided by Eitaro Fukamachi.
;;;; Copyright (c) 2014 Eitaro Fukamachi
;;;; github.com/fukamachi/http-body
(defun parse-stream (stream &optional content-length)
"Reads the contents of a stream and returns it as a vector of unsigned bytes.
- `stream`: The input stream from which to read.
- `content-length`: If provided, specifies the exact number of bytes to read."
(if (typep stream 'flexi-streams:vector-stream)
(coerce (flexi-streams::vector-stream-vector stream) '(simple-array (unsigned-byte 8) (*)))
(if content-length
(let ((buffer (make-array content-length :element-type '(unsigned-byte 8))))
(read-sequence buffer stream)
buffer)
(apply #'concatenate
'(simple-array (unsigned-byte 8) (*))
(loop with buffer = (make-array 1024 :element-type '(unsigned-byte 8))
for read-bytes = (read-sequence buffer stream)
collect (subseq buffer 0 read-bytes)
while (= read-bytes 1024))))))
Next, we’ll define a macro `with-parsed-json` to handle JSON parsing in our webhook handler:
(defmacro with-parsed-json (&body body)
"Parses the JSON body of an incoming HTTP request and binds it to a local
variable `json`.
Within BODY, the variable `json` will contain the parsed JSON object."
`(let* ((content-type (getf snooze:*clack-request-env* :content-type))
(content-length (getf snooze:*clack-request-env* :content-length))
(raw-body (getf snooze:*clack-request-env* :raw-body))
(json-stream (parse-stream raw-body content-length))
(raw-json (babel:octets-to-string json-stream
:encoding (detect-charset content-type :utf-8)))
(json (handler-case (com.inuoe.jzon:parse raw-json)
(error (e)
(format t "Malformed JSON (~a)~%!" e)
(http-condition 400 "Malformed JSON!")))))
(declare (ignorable json))
,@body))
Now, let’s define the `handle-webhook-event` function, which validates and processes incoming webhook events from Stripe:
(defun handle-webhook-event ()
"Handles incoming webhook events from Stripe webhooks."
(with-parsed-json
(let* ((is-valid-webhook (stripe:validate-webhook-payload
json-stream
(gethash "stripe-signature" (getf snooze:*clack-request-env* :headers))
(stripe-webhook-secret)))
(event (stripe:construct-webhook-event
json-stream
(gethash "stripe-signature" (getf snooze:*clack-request-env* :headers))
(stripe-webhook-secret)
:ignore-api-version-mismatch t))
(event-type (gethash "type" json)))
(if is-valid-webhook
(progn
(format t "Valid webhook received.~%")
(cond ((string= "payment_intent.created" event-type)
(format t "Payment intent created!~%")
;; TODO: Proceed with creating a user or processing the payment intent here
)
((string= "customer.subscription.created" event-type)
(format t "Subscription created!~%")
;; TODO: Handle subscription creation
)
((string= "invoice.payment_succeeded" event-type)
(format t "Payment succeeded for invoice!~%")
;; TODO: Handle the successful payment
)
;; etc.
(t
(format t "Unhandled event type: ~a~%" event-type))))
(format t "Invalid webhook signature.~%")))))
Lastly, we define the route to handle webhook requests:
(snooze:defroute webhook (:post :application/json)
(handle-webhook-event))
That’s it. I hope I left you off in a better position than before and you have a clearer idea of how to add billing to your next Common Lisp app.
I’m impartial to syntax highlighting in code since it can be a source
of distraction more often than not, however, I tend to use the favored
major mode for the language I’m writing in Emacs paired with
eglot. Lately though, this has become a pain point when working with
all-things JavaScript on large files. My quick solution was to forego
eglot and web-mode, which improved the editing speed tremendously.
It looks like the latter is a common reason for the slowdown when
working with TSX files. I figured this is a good reason to finally get
tree-sitter in my Emacs setup working as I’ve failed previously.
Tree-sitter is a parser generator tool that can build a concrete syntax tree for a source file and efficiently update the tree during edits. Syntax highlighting is one of those features that can leverage this tool. Code navigation is another, though we’ll only talk about syntax highlighting.
Syntax highlighting tools usually rely on custom regular expressions, so using Tree-sitter is faster and has better highlighting since it’s more context-aware.
I’ve had trouble installing the language grammars manually before on my Guix system, so I figured it’s better to install the packages from Guix.
I use Guix Profiles to group package installations together e.g., a default profile, an Emacs profile, a Common Lisp profile etc. and make them available on login.
In this case I’m adding the relevant packages to my default profile:
;; guix-default-manifest.scm
;; default packages but example only includes Tree-sitter ones
(specifications->manifest
'("tree-sitter"
"tree-sitter-bash"
"tree-sitter-css"
"tree-sitter-dockerfile"
"tree-sitter-go"
"tree-sitter-html"
"tree-sitter-javascript"
"tree-sitter-json"
"tree-sitter-python"
"tree-sitter-typescript"))
Then I run:
guix package --manifest=/home/boogs/.package-lists/guix-default-manifest.scm --profile=/home/boogs/.guix-extra-profiles/default/default
to update my default profile to include these packages.
Now we’ve installed the tool and the language grammars. Next, we need to tweak our Emacs configuration slightly to know where to find the language grammars.
(setq treesit-extra-load-path '("~/.guix-extra-profiles/default/default/lib/tree-sitter"))
(add-to-list 'auto-mode-alist '("\\.js\\'" . js-ts-mode))
(add-to-list 'auto-mode-alist '("\\.json\\'" . json-ts-mode))
(add-to-list 'auto-mode-alist '("\\.ts\\'" . typescript-ts-mode))
(add-to-list 'auto-mode-alist '("\\.tsx\\'" . tsx-ts-mode))
(add-to-list 'auto-mode-alist '("\\.html\\'" . html-ts-mode))
(add-to-list 'auto-mode-alist '("\\.css\\'" . css-ts-mode))
(add-to-list 'auto-mode-alist '("\\.go\\'" . go-ts-mode))
The load path may vary depending on how you install the packages. If
you install them to the current profile, then the path starts with
"~/.guix-profile/lib/tree-sitter".
With Tree-sitter set up via Guix, editing large JavaScript,
TypeScript, or TSX files in Emacs should feel snappier, thanks to
efficient parsing and context-aware highlighting. This setup not only
resolves slowdowns from modes like web-mode but also opens the door to
advanced features like structural editing.
If you encounter issues (e.g., missing grammars or incompatible Emacs versions), check the Tree-sitter GitHub repository or the Guix Codeberg repository. Happy hacking!