kempo-payments
v0.4.5
Published
Payment processing for kempo — provider-agnostic payment intents, capture and refunds, with Stripe built in
Readme
kempo-payments
A payment-processing extension for the kempo CMS. Take a payment, capture an authorisation, issue a refund — without the code doing it knowing which processor is behind it.
Stripe is the processor that ships. It is not the one the rest of the extension is written against:
everything goes through a small provider interface, and adding PayPal or Square later is a new file
in server/providers/, not a change to anything that ever called createPayment.
This kempo (CMS) extension depends on no other kempo extension. Taking money does not require a
product catalog, so there is no dependency on kempo-commerce — the arrow points the other way. That is also what makes it usable
for anything else that needs to charge a card: a subscription, a donation, a one-off invoice.
What it is for
Other kempo (CMS) extensions. kempo-payments has no checkout of its own and no idea what anybody is buying.
It knows how to move money and how to tell you it moved.
import { createPayment } from 'kempo-payments/sdk';
const [error, { payment, clientSecret }] = await createPayment({
amount: 4999, // minor units, always — 4999 is $49.99
currency: 'usd',
owner: 'kempo-commerce', // who is asking
reference: order.id, // their own id for what is being paid for
userId: user?.id, // null for a guest
customerEmail: order.email,
description: `Order ${order.number}`,
});Hand clientSecret to the browser, mount the payment form against it, and then stop watching the
browser. Fulfilment hangs off the payment:succeeded hook, which is fired from the processor's
webhook — see Hooks for why that distinction is the whole design.
Install
npm install kempo-paymentsThen install it from the admin panel, or:
import installExtension from 'kempo/server/utils/extensions/installExtension.js';
await installExtension({ name: 'kempo-payments' });Requires kempo 4.2.40 or later — the first release with the encrypted secret setting type that
every credential here is stored as.
SETTINGS_ENCRYPTION_KEY is required
Every credential this extension stores is a kempo secret setting, encrypted at rest. kempo cannot
encrypt anything without a key, so without one no credential can be saved at all — the settings
screen refuses, and installing prints a warning rather than leaving you to find out later.
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"Put it in the site's environment as SETTINGS_ENCRYPTION_KEY and restart. Back it up in the same
place as DATABASE_URL: losing it makes every stored secret on the site unrecoverable, and rotating
it means re-entering every one of them.
Connecting Stripe
Everything below is on the extension's own admin screen at
/admin/extension/kempo-payments/ → Settings.
- Get the keys. Stripe dashboard → Developers → API keys. In test mode these begin
pk_test_andsk_test_. The secret key is shown once. - Paste both in and save. The screen says which mode the keys are for, read off the key prefixes rather than a switch — a switch can disagree with the keys, and "the toggle said test" is an expensive sentence.
- Add the webhook endpoint. The screen shows the URL and the exact list of events to subscribe
it to. Stripe gives you a signing secret (
whsec_…) when you create it; paste that in too. - Take a test payment. The Take a payment tab runs the whole path — an intent created with
the secret key, the real payment form built with the publishable key, a confirmation from the
browser, and then the webhook coming back. Card
4242 4242 4242 4242, any future expiry, any CVC.
If step 4 ends at "Paid, but nothing came back", the charge worked and the webhook did not. That is the failure worth catching before launch, because in production it means orders that are paid for and never fulfilled.
Webhooks on localhost
Stripe cannot reach a development machine, so forward events to it instead:
stripe login
stripe listen --forward-to localhost:9876/payments/api/webhooks/stripestripe listen prints its own signing secret, different from the dashboard endpoint's. That is
the one to paste into the settings screen while developing.
Wallets and buy-now-pay-later
Apple Pay, Google Pay, Klarna, Afterpay, Cash App Pay and Amazon Pay are not separate providers
here and never will be. <k-pay-form>'s Express Checkout button row offers whichever of them are
available to a given customer, drawn and driven entirely by Stripe — no extra integration, no
separate merchant account, and no code in this extension to add one. Modelling any of them as its
own provider module would duplicate an integration that is already done.
"Available" is a dashboard setting, not a code path: Apple Pay and Google Pay need the site's domain registered with Stripe (Settings → Payment methods → Apple Pay, and HTTPS — neither works over plain HTTP, which is why they are absent in local development); Klarna, Cash App Pay and Amazon Pay need to be switched on the same way. Stripe shows the not-yet-activated ones anyway in test mode, as a preview of what turning them on would look like — genuinely useful for building a checkout, worth knowing it means nothing about what a real customer will see until the dashboard step is done.
Two of them are not iframes at all. Tapping the Apple Pay or Google Pay button opens the native OS payment sheet — Face ID, the device's own card picker — not anything this extension or Stripe draws; the wallet encrypts the card on-device and only ever hands Stripe an already-encrypted token. Klarna, Afterpay and similar hand the customer to a screen that has to stay the provider's: they are running a soft credit check or an underwriting decision that only they can make. There is no "backend only" version of that step, which is also why this extension has no custom UI of its own for any of them — Stripe's Express Checkout button, tapped, is the entire integration.
Roadmap processors
Real second and third integrations, each with its own SDK, settlement and dispute model. Not sequenced yet:
- PayPal — its Checkout SDK now covers what Braintree used to, which is why Braintree is not on this list rather than an oversight.
- Square — the obvious pairing for a site with a physical till.
- Mollie — European coverage Stripe prices differently.
- Amazon Pay.
Adyen was considered and excluded: its onboarding is enterprise, application-based and account-manager-mediated, which does not fit a self-serve platform a small seller installs.
The payment form
A reusable custom element, served from this extension:
<script type="module" src="/payments/components/PaymentForm.js"></script>
<k-pay-form
client-secret="pi_3..._secret_..."
return-url="https://example.com/thank-you"
submit-label="Pay $49.99"
></k-pay-form>For a payment on a connected account add connected-account="acct_…" — see
Payments on a connected account.
It shows two things, either of which may be absent depending on what is available:
- Express Checkout — a row of wallet buttons (Apple Pay, Google Pay, Link, and PayPal or Amazon Pay if enabled), drawn and managed entirely by Stripe. Automatically hidden when nothing is available for that customer's browser/account, with no gap left behind.
- Card fields — number, expiry, CVC and a plain ZIP/postal input, laid out and labelled by this
extension's own markup. Each of the three card fields is a small iframe belonging to the
processor; typing sends the digits from the customer's browser straight to it, never through this
server, which is what keeps a kempo site out of PCI scope. There is no supported way to collect a
card number in a plain kempo-ui
<input>without taking on PCI scope yourself; this is as close as a card field gets to looking like the rest of the form.
Neither half of the modern appearance API reaches these three fields — confirmed by testing,
twice over, not assumed. Their box — background, border, radius, padding, focus ring — is real CSS
on the wrapper <div> (a .k-pay-field class this component injects once, copied property-for-
property from kempo-css's own input rule), because these particular Stripe fields render with a
transparent, unpadded iframe by design — the caller's page has always been expected to draw the
box — and appearance.rules (which does restyle Stripe's newer elements, Express Checkout
included) does not reach them at all. Their text colour uses the style option instead —
style.base.color / style.base['::placeholder'], Stripe's original, pre-appearance styling
mechanism for exactly this element family — because appearance.variables.colorText doesn't reach
them either, the same silent no-effect failure one layer deeper.
On a page that places the order first (a checkout)
A checkout wants the card on the same page as everything else, but the payment does not exist until the
customer presses the button, so there is no client secret to mount with. Add deferred:
<k-pay-form deferred></k-pay-form>The card fields mount on their own. A deferred form has no button of its own, no Express Checkout (wallets
need the payment to exist) and no ZIP box (set postalCode on the element from the page's own address
field). The page runs the sequence:
const form = document.querySelector('k-pay-form');
if(!form.complete) return showError('Enter your card details'); // number, expiry and CVC all valid
const [error, payment] = await createThePayment(); // your own server call
const { error: declined, paymentIntent } = await form.confirm({ clientSecret: payment.clientSecret });confirm() resolves with what the processor said ({ error, paymentIntent }) and fires the usual events
as well; after a decline the form is ready to be confirmed again with the same or a new secret.
card-change fires, with detail.complete, as the card becomes complete or stops being. A form with a
client-secret works exactly as before. Do not host a deferred form inside another <form> of
its own: it renders a plain <div> so that the page's form can hold it.
Do not put
<k-pay-form>inside a shadow root. Stripe's fields do not mount in one — they reserve their height and render nothing, with no error anywhere. If a checkout shows an empty box where a card field should be, this is why: something in the chain of custom elements above it is using shadow DOM. Everything hosting the form has to be light DOM.
Klarna, Afterpay, Cash App Pay and Amazon Pay are not excluded — see
Wallets and buy-now-pay-later for how they appear through Express
Checkout the same as Apple Pay and Google Pay do, gated by dashboard activation rather than by
anything in this component. What this rewrite did trade away is Stripe's unified, all-methods,
single-tabbed-widget layout (the previous version of this component) in exchange for owning the
card fields' own look. Wanting that back is one component, not a rewrite: mount
elements.create('payment') instead of the split card fields and Express Checkout Element — the
server side of this extension does not care which client-side widget produced the confirmation.
| Event | When |
|---|---|
| payment-succeeded | the processor confirmed it in this browser |
| payment-processing | accepted, still settling — normal for bank debits |
| payment-failed | declined, or the details were rejected |
Use these to move the customer along. Do not use them to fulfil an order. A browser closed at the wrong moment fires nothing at all, and a browser under someone's control fires whatever they like.
Saved cards
A signed-in customer can keep the card they pay with for next time. It is opt-in: a "Save this card for next time" box under the card fields, off until they tick it. Guests cannot save a card; the form tells them an account can, with a link to create one (signup-url, default /register, returning to the page).
- How: the first payment a signed-in account makes creates a Stripe customer for it (
kempoPaymentCustomerholds onlyuser -> customer id, one per Stripe test/live mode), and every payment for that account carries the customer. Ticking the box makes the form confirm withsetup_future_usage: 'on_session', and Stripe keeps the card on the customer. Nothing but the brand, last four digits and expiry ever reaches this site. - Paying: the form offers "Pay with Visa ending 4242, expires 12/30" (the newest saved card, chosen) with "Use a different card", and a trash icon to forget the one shown. Paying with a saved card needs no card fields, and
completeis true. - Only the signed-in account's own cards:
GET /payments/api/saved-methodsandDELETE /payments/api/saved-methods/:idtake the user from the session, never the request, and a card that is not that customer's is a 404. The server SDK haslistSavedCards({ userId })andremoveSavedCard({ userId, methodId })for an account page. - Off: the
save_cardssetting (a switch under Settings → Defaults → Saved cards) turns it all off. A payment on a connected account never offers it (a customer lives on one Stripe account, a direct charge is made on another). - If the customer cannot be made (Stripe is unreachable), the payment still goes ahead, just without saved cards.
Hooks it fires
Registered by consumers in their own kempo-config.json, the same as any other kempo hook:
"hooks": {
"payment:succeeded": "hooks/payment-succeeded.js"
}| Event | Data | When |
|---|---|---|
| payment:created | { payment } | an attempt has been started; no money has moved |
| payment:authorized | { payment } | held on the customer's card, waiting to be captured |
| payment:succeeded | { payment } | taken — this is the one to fulfil against |
| payment:failed | { payment, error } | the processor refused it — once per decline, so a card declined three times fires it three times |
| payment:canceled | { payment } | abandoned, or the hold released |
| payment:refunding | { payment, amount, reason, issuedBy } | a guard, before a refund reaches the processor — throw { code, msg } to refuse it |
| payment:refunded | { payment, refund } | some or all of it given back |
| payment:disputed | { payment, disputed, reason } | a chargeback opened, or closed |
payment:refunding is the one guard: it runs in bail mode, so a handler that throws stops the refund
with its own error before the processor is contacted — how the extension that took a payment refuses a
refund it cannot honour (kempo-credits, for credits already spent). A refund made in the processor's
own dashboard never passes through it, so payment:refunded can still arrive for one.
payment:succeeded fires once per payment, on the transition into that state and nowhere else.
Redelivered webhooks, polling and admin screens all pass through the same place and produce no
transition, so nothing downstream sends a second confirmation email or ships a second box.
Capture: automatic or manual
Automatic charges the card the moment the customer confirms. Right for anything delivered immediately.
Manual places a hold and takes nothing until somebody captures it. Right for anything that ships, where the amount can change or the order can be cancelled before it goes out. The hold expires on its own — typically after seven days — and an authorisation nobody captured is money the customer had reserved and the merchant never received.
The site-wide default is a setting; any individual payment can override it.
A capture method is never guessed at. Manual and MANUAL are read as manual — case and
stray spaces are forgiven — but anything else (hold, authorize, a typo) is refused with a 400
naming the two that exist, before any processor is contacted. The alternative was falling back to
automatic, which turns "reserve this card" into "charge this card" for every mistyped word. The
same rule applies to the setting on the settings screen.
Refunds and cancellations
They are not the same thing and the extension will not let them be confused:
- A payment that is authorised but not captured has had nothing taken. Releasing it is a cancel. Asking to refund it is refused, with that sentence rather than the processor's.
- A payment that succeeded can be refunded, in full or in part, repeatedly, until nothing is left outstanding.
The refunded total is recomputed from the individual refund rows rather than incremented, and every refund is keyed by the processor's own reference. An admin refund and the webhook reporting the same refund a second later are one row and one total — which is what stops a payment claiming twice the money went back.
Refunds made directly in the processor's dashboard arrive by webhook and are recorded here too.
Stripe's charge.refunded event reports only the new running total, not which refunds make it up,
so the extension asks Stripe for the refunds on that payment before recording them. Check with
Stripe on a payment's screen reconciles the same way, and will pick up a refund whose webhook was
missed entirely.
A refund amount larger than what is left is refused with the remaining amount in the payment's own
currency (Only $5.00 is left to refund on this payment).
Payments on a connected account (Stripe Connect)
A payment can be taken on somebody else's Stripe account rather than the site's — a Connect direct charge. This is what kempo-payouts uses to let one user pay another (a guest tipping a DJ) while the site keeps a fee. kempo-payouts onboards the accounts; this extension takes, records, refunds and webhook-syncs the payments, so there is one payment record and one set of hooks whichever account the money went to.
const [error, { payment, clientSecret }] = await createPayment({
amount: 500, // $5.00, minor units as always
currency: 'usd',
owner: 'kempo-payouts',
reference: tip.id,
connectedAccount: 'acct_1Nv0FGQ9RKHgCVdK', // whose account the money goes to
applicationFee: 25, // the site's cut, in the same minor units
});<k-pay-form client-secret="…" connected-account="acct_1Nv0FGQ9RKHgCVdK"></k-pay-form>- Both new fields are optional, and stored on the payment (
connectedAccount,applicationFee). A site that never passes them behaves exactly as before. Refused with a 400 before any processor is asked: a fee with no account, an account id that is notacct_…, and a fee that is negative, not whole, or not less than the payment. A fee of 0 takes no fee. - Every later call reads the account off the payment — capture, cancel, refund, sync, the client secret — and never from a caller. An intent on a connected account cannot be found without it, and Stripe's error when it is missing ("No such payment_intent") points nowhere near the cause.
- The browser needs the account too.
<k-pay-form connected-account="…">initialises Stripe.js with{ stripeAccount }; without it the form loads and every confirm fails.getClientSecretreturnsconnectedAccountalongside the secret for this reason. - A refund can carry an
idempotencyKey(any payment, connected or not), sent to the processor, so a retry after a timeout returns the refund already made instead of making a second one. - Refunds give the site's fee back by default.
refundPayment(id, { refundApplicationFee })defaults totruefor a payment that took a fee: the fee is returned in proportion to the refund — all of it on a full refund. Passfalseto keep it, in which case the connected account pays the whole refund. (Stripe's own default is the opposite, so this extension always sends one or the other.) The admin refund form has a checkbox for it; the HTTP route takesrefundApplicationFee. - Statuses and hooks are unchanged.
payment:succeededand the rest fire as before, withconnectedAccountandapplicationFeeon the payment so a listener can tell. - The admin screen shows which account a payment went to and the site's fee.
Webhooks for connected accounts — receiveVerifiedEvent
Stripe does not send connected-account events to this extension's endpoint. They go to a separate Connect endpoint with its own signing secret, which kempo-payouts owns. After verifying an event against that secret, kempo-payouts passes it to:
import { receiveVerifiedEvent } from 'kempo-payments/sdk';
await receiveVerifiedEvent({ event }); // provider defaults to 'stripe'which applies it through exactly the same path as this extension's own webhook — the same idempotency (by event id), the same refund and dispute handling, the same hooks.
receiveVerifiedEventdoes no signature check. Whatever reaches it is believed. Passing a request body to it without verifying the signature first lets anybody on the internet mark any payment paid. Only kempo-payouts should call it.
One check does remain on every event, on both entry points: an event is applied only to a payment made on the account it came from — a connected account's event to that account's payment, the platform's own event to the platform's. Anything else is recorded and left alone.
Updating an existing site
The two columns are added by update.js (ALTER TABLE … ADD COLUMN IF NOT EXISTS), since kempo
never alters an existing table. Every existing payment reads back with both null, which is what it
was: a payment into the site's own account.
Proving it against Stripe's test mode
npm test never calls Stripe. The connected-account calls are proved against a real test-mode
Connect account by a script that runs this extension's own code on an in-memory database:
STRIPE_TEST_SECRET_KEY=sk_test_… STRIPE_TEST_PUBLISHABLE_KEY=pk_test_… \
STRIPE_TEST_CONNECTED_ACCOUNT=acct_… node scripts/connect-test-mode.jsIt refuses anything but test keys. It creates a payment with a fee on the account and checks the
intent is there (and not on the platform), confirms it with a test card, syncs it, checks the site
received the fee, refunds part with the fee (checks the fee was refunded in proportion) and part
without (checks it was kept), retries a refund with the same idempotency key (checks it was made
once), reads every refund back, captures a held payment, cancels an unpaid
one, and finally runs a real payment_intent.succeeded event — read back from the account, not
written by hand — through receiveVerifiedEvent. Without STRIPE_TEST_CONNECTED_ACCOUNT it uses the
first connected account that can take card payments. Last run 2026-10-15: 14 of 14 on an Express
Dashboard account, and 13 of 13 on a full Stripe Dashboard account before the idempotency check was
added.
Wallets on a connected account (Apple Pay in particular) need the site's domain registered on that
account — Stripe's payment method domains, created with the account's Stripe-Account header. That
is kempo-payouts' job when it onboards an account, not something this extension can do.
Disputes
Admin → Payments → Disputes lists the disputes (chargebacks) on the processor's account: the soonest deadline first, with whether each needs a response or is being decided, the amount, why the customer says they disputed it, the sale it was about when this site made it, and a button that opens that dispute in Stripe's dashboard (the test or the live one, by the key).
It is read-only on purpose. A dispute is answered where the evidence form, the file uploads and the deadline emails already are, and evidence can only be sent once, so a second form here would only be a way to get it wrong. The list is read from the processor each time rather than copied into a table, so it is never behind; what this site keeps is the yes/no disputed flag on the payment (set by the webhook), which other extensions react to through payment:disputed.
- Needs a Stripe key that can read disputes (a full secret key can; a restricted one needs Disputes: read).
- Shows the site's own account. A payment taken on a connected account (kempo-payouts) has its dispute on that account.
- A test dispute to look at: pay with the test card
4000 0000 0000 0259.
When an event cannot be applied
The webhook marks an event handled only after it has been applied. If applying it fails — the database would not write — the endpoint answers with an error, the claim on that event is released, and Stripe's retry is processed rather than being answered "duplicate" and dropped. Text that contains a NUL byte (which Postgres cannot store) is refused with a 400 when a caller supplies it and stripped when the processor does, since by then the money has already moved.
Permissions
| Permission | Allows |
|---|---|
| payments:view | See payments, what they were for, and what happened to them |
| payments:create | Take a payment — start a new charge over the API |
| payments:capture | Capture or cancel a payment that was only authorised |
| payments:refund | Refund a payment, in full or in part |
| payments:settings | Change the payment provider and its API credentials |
Two groups ship with them: kempo-payments:operator handles payments day to day — looking them
up, capturing, refunding — without being able to see or change credentials, and
kempo-payments:administrator adds connecting the site to a processor.
payments:create is deliberately not held by an ordinary visitor. The HTTP route that starts a
payment takes the amount from the request body, so an open version of it would let anybody decide
what they owe. A customer-facing checkout computes the amount on its own server and calls the SDK.
Settings
| Setting | Default | Meaning |
|---|---|---|
| provider | stripe | Which processor money goes through |
| currency | usd | Used when the caller does not name one |
| capture_method | automatic | See Capture |
| save_cards | true | Whether a signed-in customer can choose to save a card and pay with a saved one. See Saved cards |
| stripe_publishable_key | — | pk_test_… / pk_live_…; public by design |
| stripe_secret_key | — | sk_test_… / sk_live_…; encrypted, never leaves the server |
| stripe_webhook_secret | — | whsec_…; without it, no payment is ever confirmed |
Server SDK
import {
createPayment, capturePayment, cancelPayment, refundPayment,
getPayment, getPaymentByRef, paymentsForReference, listPayments,
syncPayment, getClientSecret, refundableAmount, formatAmount,
receiveVerifiedEvent, refundOptionsFor,
} from 'kempo-payments/sdk';createPayment also takes connectedAccount and applicationFee, refundPayment takes
refundApplicationFee, and listPayments filters by connectedAccount — see
Payments on a connected account.
Every one returns kempo's [error, data] tuple. None of them checks a permission — the HTTP routes
do that, and anything importing this is server-side code that has already decided it is allowed.
paymentsForReference(owner, reference) is the lookup a consumer wants: it knows its order number,
not a payment id.
HTTP API
Served under the extension's public scope, /payments/.
| Route | Permission | |
|---|---|---|
| GET /payments/api/config | none | Provider and publishable key, for the payment form |
| GET /payments/api/payments | payments:view | Filtered, paged list |
| POST /payments/api/payments | payments:create | Start a payment |
| GET /payments/api/payments/:id | payments:view | One payment, its refunds and its event log |
| GET /payments/api/payments/:id/client-secret | payments:create | Re-mount a form against a payment in flight |
| POST /payments/api/payments/:id/capture | payments:capture | |
| POST /payments/api/payments/:id/cancel | payments:capture | |
| POST /payments/api/payments/:id/refund | payments:refund | |
| POST /payments/api/payments/:id/sync | payments:view | Re-read from the processor |
| GET /payments/api/saved-methods | session | The signed-in customer's own saved cards (brand, last four, expiry). A guest gets a 401 |
| DELETE /payments/api/saved-methods/:id | session | Forget one of their own saved cards |
| GET /payments/api/summary | payments:view | Counts and totals per currency |
| GET /payments/api/disputes?status=open\|closed\|all | payments:view | The processor's disputes, read live |
| GET/PUT /payments/api/settings | payments:settings | Never returns a credential, only whether one is set |
| POST /payments/api/webhooks/:provider | signature | The processor's own endpoint |
Amounts are integers
Always the currency's smallest unit. 4999 is $49.99. 1200 is ¥1,200, because yen have no minor
unit at all — and a Kuwaiti dinar has three decimal places, not two.
Floats are refused rather than converted. A caller passing 49.99 meant $49.99 and would be
charging five cents; the processor would accept that instruction without complaint. toMinor() is
exported for the places where a human genuinely typed a decimal into a box.
Adding a provider
One file in server/providers/, exporting name, label, webhookPath, webhookEvents,
signatureHeader, credentialFields, and the functions status, clientConfig, createIntent,
retrieveIntent, capture, cancel, refund, verifyEvent and interpretEvent. Add its
credential settings to kempo-config.json and register it in server/providers/index.js.
The contract is documented in full at the top of server/providers/index.js. Statuses coming out of
it must be kempo's, not the processor's — mapping is the provider module's job, precisely so the
rest of the extension has one vocabulary rather than one per processor.
What this does not do
- Subscriptions and recurring billing. A separate concern with its own state machine, dunning and proration. This extension is the thing one would be built on.
- Charging a saved card later, without the customer there (subscriptions, off-session). Cards are saved for the customer to use again while they are on the site (
on_session); recurring billing is a separate extension. - Payouts, balances and reconciliation. The processor's dashboard is the ledger. Paying other users — onboarding their accounts, a fee policy, a page for them — is kempo-payouts; this extension only takes the payment on their account.
- Answering disputes. They are flagged and listed here (Payments → Disputes) and answered in the processor's dashboard — evidence submission is a processor-specific workflow with deadlines attached.
- Tax. That is
kempo-tax, deliberately separate: "compute what is owed" and "move money" are orthogonal, and merging them would stop anybody swapping in their own tax calculator. - A checkout. No cart, no order, no idea what is being bought. That is
kempo-commerce.
Uninstalling
The tables are dropped, which loses this site's record of every payment it has taken. That record is a copy — the charges themselves live at the processor and are entirely unaffected, and any of them can still be refunded from its dashboard.
Uninstalling names any payment still authorised and uncaptured on the way out. Those are holds on real cards that nothing will capture or release once the extension is gone.
Development
npm install
npm run link:local # symlinks sibling kempo checkouts
docker compose up -d # test database on port 5439
DATABASE_URL=postgresql://kempo:kempo@localhost:5439/kempo_payments_test npx drizzle-kit push --force
npm testThe database suites (data layer, lifecycle, webhooks) skip themselves when no database is
reachable, and a skip reads as a pass — check for (SKIPPED) before believing a green run covered
them. They also skip themselves when DATABASE_URL names a database that does not end in _test,
because they empty the payment tables first: pointing one at a real site's database would
delete its payments. The webhook suite additionally needs SETTINGS_ENCRYPTION_KEY (any 64 hex
characters will do) to store the signing secret it verifies against.
Saved cards also have a manual procedure against Stripe's test mode (the unit suite proves the table, the setting, the guest and unconfigured cases and the 401s; creating a customer and saving, listing and removing a card need Stripe): with test keys connected, sign in, open Payments → Take a payment, tick "Save this card for next time" and pay with 4242 4242 4242 4242; start another payment and the card is chosen for you; pay with it; remove it with the trash icon and the list is empty again. Never run it with live keys.
No Stripe account is needed for any other test: every provider response in the suite is a literal, and webhook events are signed with Stripe's own test-signature helper, because a suite that needs an account is a suite nobody runs.
License
MIT
Dashboard widget
Adds a Payments widget to the kempo admin dashboard showing money captured and refunded per currency, the payment count and any disputes, with a View payments button. It is declared in widgets in kempo-config.json and registered when the extension is installed or updated; people only see it if they hold its permission, and can hide, reorder or resize it from the dashboard's Customize dialog. Needs a kempo with the dashboard (see kempo's docs/dashboard.md); on an older kempo the entry is ignored.
