Sign in Talk to us Free trial
Free trial

Design and software studio
Colour

Set up Stripe so card payments land on the invoice

Add your business's Stripe webhook address and signing secret so a card payment marks the invoice paid or partly paid on its own.

For
Owner
Hosting
Any hosting
Devices
All devices
Business
All businesses

Checked against Pop Dispatch 0.1.0

When a customer pays an invoice on Stripe's page, Stripe tells Pop Dispatch, and Pop Dispatch records the card payment on the invoice. You will be able to add the webhook address in your Stripe account, save its signing secret, and see paid and partly paid invoices update without anyone typing the payment in.

Before you start #

  • You are the owner. Only the owner saves or removes the signing secret.
  • Your Stripe secret key is already saved and you can make payment links (see "Take card payments on invoices with your own Stripe account").
  • Your public base address is saved in settings, because Stripe must be able to reach your server from the internet.

Steps #

  1. Ask the server for your webhook address: the owner's request GET /settings/payments/stripe/webhook returns it. It is your public base address followed by /api/v1/payments/stripe/webhook/ and your business name. The Settings, Payments screen in the apps does not show it yet.
  2. In Stripe, open Developers, then Webhooks, then Add endpoint.
  3. Paste the webhook address. Choose two events: checkout.session.completed and checkout.session.async_payment_succeeded. Save the endpoint.
  4. Stripe now shows a signing secret that starts with whsec_. Choose Reveal and copy it.
  5. Save it with the owner's request PATCH /settings/payments/stripe/webhook and the field signing_secret. Only the last four characters are shown afterwards.
  6. Make a payment link for a small test invoice with a Stripe test key, pay it with a Stripe test card, and open the invoice. It shows the card payment and a lower balance, or Paid when nothing is left.

What happens after each payment:

  • The invoice shows a card payment with Stripe as the source.
  • A payment that covers the balance marks the invoice paid. A smaller one leaves it partly paid with the balance that remains.
  • The audit log has an entry named "card payment confirmed".
  • If your webhook endpoints subscribe to invoice.paid, that message goes out once the invoice is settled.
Technical details
  • Routes: GET, PATCH and DELETE /settings/payments/stripe/webhook (owner only), and POST /payments/stripe/webhook/:tenant (public, signed by Stripe).
  • The signing secret is sealed with a key derived from the vault's data key and tied to your business, like the Stripe key. It is left out of answers, logs, audit entries and backup files.
  • Stripe's signature header carries a time and one or more v1 values. Pop Dispatch computes HMAC-SHA256 over the time, a period and the raw request body with your signing secret, compares in constant time, and accepts a time up to five minutes from the server's clock. Anything else gets the same plain refusal, whether the business is unknown, no secret is saved or the signature is wrong.
  • Each Stripe event id is kept once, so a repeated delivery changes nothing. A checkout session that arrives in two different events is one payment.
  • Only a checkout session that Pop Dispatch made a payment link for is accepted, and only when Stripe reports it paid, in US dollars.
  • If the invoice was settled or cancelled before the card payment arrived, nothing is added to it. The audit log gets "card payment needs a refund" so you can refund it in Stripe. If the card payment is larger than the remaining balance, the balance is applied and the audit entry names the difference to refund.
  • A durable outbox entry named invoice.card_payment is written in the same step as the payment.

On the web console #

  1. The owner opens Settings, then "Online payments", types the Stripe secret key and chooses "Save the key". The page then shows the mode and the last four characters, and never the key itself. "Replace the key" and "Remove the key" are on the same page.
  2. Open an invoice with a balance. Under Payments, choose "Make a payment link". The page address appears with "Copy the address".
  3. When no key is saved, the page says to save one in Settings, Payments first. When the invoice has nothing left to pay, no link is made.
  4. In the demo the link opens a sample customer page with the invoice and its balance. The card step on that page waits for a real payment service connection.

If something goes wrong #

  • Stripe shows the endpoint failing with a 400: the signing secret in Pop Dispatch does not match the one for that endpoint. Copy the secret again from Stripe and save it.
  • The invoice stays as it was after a payment: check that the endpoint lists both events, that the public base address opens from outside your office, and that the payment came from a link made in Pop Dispatch.
  • "Only the owner can change how the business takes payments": sign in as the owner.