The payments library provides a PSP-agnostic checkout abstraction.
Swap between Mollie, Stripe, and a development mock by changing a single config value —
no application code changes required.
This library handles the checkout-session flow (create → redirect → webhook → status).
For communication channels (email, SMS), see the external library.
|
| Accepts any webhook as paid. No network calls. Boots only in the |
| Mollie REST API. Webhook via form-POST. No HMAC signing. |
| Stripe Checkout Sessions. Webhook verified with HMAC-SHA256. |
Add one key to your config.edn. There is no default :provider; boot fails without one, and with a blank API key or Stripe webhook secret:
;; resources/conf/dev/config.edn — development
:wagoe/payment-provider
{:provider :mock}
;; resources/conf/prod/config.edn — Mollie
:wagoe/payment-provider
{:provider :mollie
:api-key #env MOLLIE_API_KEY
:webhook-base-url #env APP_BASE_URL} ; e.g. "https://app.example.com"
;; resources/conf/prod/config.edn — Stripe
:wagoe/payment-provider
{:provider :stripe
:api-key #env STRIPE_SECRET_KEY
:webhook-secret #env STRIPE_WEBHOOK_SECRET}Inject it wherever payment operations are needed:
:wagoe/order-service
{:payment-provider #ig/ref :wagoe/payment-provider
...}(require '[wagoe.payments.ports :as psp])
(defn initiate-payment! [payment-provider order]
(let [{:keys [checkout-url provider-checkout-id correlation-id]}
(psp/create-checkout-session payment-provider
{:amount-cents (:total-cents order)
:currency "EUR"
:description (str "Order #" (:id order))
:redirect-url (str base-url "/orders/" (:id order) "/confirmation")
:webhook-url (str base-url "/api/v1/payments/webhook")
:metadata {:order-id (str (:id order))}})]
;; Store both on the order: the webhook echoes correlation-id,
;; get-payment-status takes provider-checkout-id
(save-checkout-ids! order provider-checkout-id correlation-id)
;; Redirect the user to the PSP
checkout-url))Always use integer cents — 11900 for €119,00. Never pass floats.
Currency as ISO 4217 string — "EUR", "USD".
(require '[wagoe.payments.ports :as psp])
(defn payment-webhook-handler [request payment-provider]
;; IMPORTANT: read raw body BEFORE any body-parsing middleware
(let [raw-body (slurp (:body request))
headers (:headers request)]
(if (psp/verify-webhook-signature payment-provider raw-body headers)
(let [{:keys [event-type correlation-id]}
(psp/process-webhook payment-provider raw-body headers)]
(case event-type
:payment.paid (activate-order! correlation-id)
:payment.failed (mark-order-failed! correlation-id)
:payment.cancelled (cancel-order! correlation-id)
nil) ; ignore unrecognized events
{:status 200 :body ""})
{:status 400 :body "Invalid signature"})))Route definition. The PSP has no session, so the route is :public:
["/payments/webhook"
{:post {:handler #(payment-webhook-handler % payment-provider)
:public true
:summary "PSP webhook receiver"}}]| The webhook route must receive the raw body string before body-parsing middleware runs. Stripe computes the HMAC over the raw request body. Parsing it first invalidates the signature. |
| Payment successfully completed |
| Authorized but not yet captured |
| Payment attempt failed |
| Cancelled by user or PSP |
| Checkout expired before payment |
| A verified event with no payment outcome (Stripe disputes, |
Correlate on the :correlation-id that create-checkout-session returned; :provider-checkout-id is in the webhook only when the payload carries it.
Use get-payment-status to poll a payment (e.g. on the confirmation page):
(let [{:keys [status provider-payment-id]}
(psp/get-payment-status payment-provider provider-checkout-id)]
(case status
:paid (render-success-page order)
:pending (render-pending-page order)
:failed (render-failure-page order)
(:cancelled :expired :chargeback) (render-cancelled-page order)))The mock provider is ideal for development and automated tests:
# Mock checkout URL lands on your own handler — add it to your dev routes
GET /web/payment/mock-return?checkout-id=<uuid>;; In tests
(require '[wagoe.payments.shell.adapters.mock :as mock])
(def test-provider (mock/make-mock-provider))Mollie does NOT sign webhooks with HMAC — verify-webhook-signature always returns true.
process-webhook fetches the payment by the id in the body, so the outcome comes from Mollie’s API, not the request. An id this account does not know is acknowledged with a nil event.
:webhook-base-url is your application’s public base URL; the adapter appends /api/v1/payments/webhook unless the checkout passes :webhook-url.
Recurring billing: a checkout with :setup-future-usage is Mollie’s first payment and stores a mandate.
create-off-session-payment charges it later, usually as :pending until SEPA settles.
expire-checkout-session cancels the open payment; the webhook reports :payment.cancelled.
Stripe signs webhooks with HMAC-SHA256 — always call verify-webhook-signature first.
Set STRIPE_WEBHOOK_SECRET from the Stripe dashboard (Webhooks → signing secret).
In development, use the Stripe CLI to forward events to localhost:
stripe listen --forward-to localhost:3000/api/v1/payments/webhookThe CLI prints the webhook signing secret — use it as STRIPE_WEBHOOK_SECRET in dev.
# All payments tests
clojure -M:test :payments
# Only pure function tests
clojure -M:test :payments --focus-meta :unitAlways use the mock provider in tests:
(require '[wagoe.payments.shell.adapters.mock :as mock])
(deftest checkout-test
(let [provider (mock/make-mock-provider)
result (psp/create-checkout-session provider
{:amount-cents 4900
:currency "EUR"
:description "Test order"
:redirect-url "https://example.com/done"})]
(is (string? (:checkout-url result)))
(is (string? (:provider-checkout-id result)))))See libs/payments/AGENTS.md for the full library reference.
Can you improve this documentation? These fine people already did:
Thijs Creemers & thijscreemersEdit on GitHub
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |