Octeth v6.0.7 Now Available! See What's New

Stage 9 of 12

Stripe Billing for Your Email Service Provider in Octeth

Octeth runs the plans, subscriptions, invoices and payment retries itself, and uses Stripe to store cards and take payments. This guide covers the Stripe keys and webhook, plans and prices in Octeth, failed payments, sharing a Stripe account, and how vetting keeps spammer disputes off your Stripe account.

By Cem Hurturk, founder of Octeth Updated 12 min read

Skills
  • Stripe setup
  • Webhooks
  • Restricted API keys
On this page
  1. What Stripe does and what Octeth does
  2. Set up Stripe
  3. Map plans to prices
  4. Trials
  5. Failed payments and dunning
  6. Refunds
  7. Sharing a Stripe account
  8. Stripe account risk from spammer disputes
  9. Tax
  10. Go live
  11. Octeth versions this stage relies on

In Octeth, billing is part of the app. Octeth holds the plan catalog, subscriptions, invoices, proration and payment retries. Stripe stores your customers’ cards and takes each payment. Stage 7, plans and sending limits, built a user group for each plan. This stage puts a price on each plan and connects Stripe. Stage 8, abuse prevention, comes first, so you can review senders before they pay.

What Stripe does and what Octeth does

On the versions we checked, Octeth calls these parts of the Stripe API: customers, payment methods and setup intents to save a card, payment intents to charge it, refunds, and a read of the account balance to verify the key. It creates no Stripe products, prices, subscriptions or invoices.

That has three consequences:

  • Prices live in Octeth. You set them in Octeth’s catalog. There is nothing to create in Stripe’s product catalog.
  • Stripe Billing features do not apply. Stripe’s Smart Retries retry failed subscription and invoice payments in Stripe Billing (Stripe: Smart Retries). Octeth’s charges are plain payment intents, so Octeth’s own retry schedule does that job. The failed payments section below covers it.
  • Stripe sees payments, not plans. Use Octeth’s staff billing screens for subscriptions, plan changes and invoices. Use Stripe’s dashboard for payments, refunds and disputes.

Octeth’s billing setup page walks through the screens. Turn billing on with BRAND_FEATURE_BILLING=true in .oempro_env, then run ./cli/octeth.sh docker:up.

Set up Stripe

Do the whole setup in Stripe’s test mode first, then repeat it with live keys. The gateway screen calls the two modes Testing and Live payments. Octeth’s docs call them sandbox and production.

Keys

Octeth needs three values from Stripe:

ValueStarts withWhere it is used
Secret or restricted keysk_ or rk_Octeth’s server
Publishable keypk_The card form in the customer’s browser
Webhook signing secretwhsec_Checks that webhook events come from Stripe

Use a restricted key in live mode. A restricted key can do only what you allow, which limits what a leaked key can do. Stripe recommends restricted keys over the full secret key wherever possible (Stripe: restricted API keys).

These are the permissions Octeth’s billing needs on a restricted key:

Stripe resourcePermission
CustomersWrite
PaymentIntentsWrite
PaymentMethodsWrite
SetupIntentsWrite
RefundsWrite
BalanceRead
DisputesRead
Everything elseNone

Disputes: Read looks unrelated, but listing PaymentIntents needs it. After you create the key, probe each resource with a read request. A denied request names the permission it lacks.

Webhook

Octeth learns about payments, failures and refunds from Stripe’s webhook. Create the endpoint in Stripe at:

https://<your app domain>/ui/webhooks/stripe

The /ui/ part is required. Subscribe the endpoint to these events:

# Payments
- payment_intent.succeeded
- payment_intent.payment_failed
- payment_intent.canceled
- payment_intent.processing
- payment_intent.requires_action
# Charges and disputes
- charge.succeeded
- charge.failed
- charge.refunded
- charge.dispute.created
# Refunds, recorded from Octeth 6.0.1
- refund.created
- refund.updated
- refund.failed
- charge.refund.updated

Octeth’s payment gateways page lists the refund events. An endpoint created before 6.0.1 needs the four refund events added when you upgrade.

Set the endpoint to a current API version. Each Stripe webhook endpoint has its own API version, and Stripe shapes each event’s payload by it (Stripe: webhook versioning). Do not accept an old account default.

Stripe signs every event in the Stripe-Signature header. The v1 value is an HMAC with SHA-256 of the timestamp, a dot and the raw request body, keyed with the endpoint’s signing secret (Stripe: webhooks). Octeth checks it and refuses an event with a wrong signature. Stripe retries a live event it could not deliver for up to three days.

Check signing in test mode first. Point the test-mode endpoint at your install, then create a test object in the Dashboard, or trigger an event with the Stripe CLI (Stripe: webhooks):

# Test mode only. Creates a test payment intent and sends its events to your test-mode endpoints.
stripe trigger payment_intent.succeeded

The endpoint’s event deliveries in Workbench should show 200. The test purchase below then proves that Octeth acts on the events it receives.

You cannot trigger test events against the live endpoint. Check only that it refuses a request without a valid signature:

curl -s -o /dev/null -w '%{http_code}\n' -X POST "https://<your app domain>/ui/webhooks/stripe" \
  -H 'Content-Type: application/json' -H 'Stripe-Signature: t=1,v1=invalid' --data '{}'
# Expect 401.

Octeth refuses it before it stores anything. The first real purchase is the proof that the live endpoint works.

Connect the gateway

In the staff area, open the Stripe payment gateway. Paste the key, the publishable key and the webhook secret, save, then choose “Use this processor” and confirm. Check that the gateway is active before the test purchase.

Then run a test purchase in test mode: sign up, add Stripe’s test card, change to a paid plan. A passing test shows a prorated charge, a paid invoice, a succeeded payment intent, processed charge.succeeded and payment_intent.succeeded events, and the account moved to the plan’s user group.

Map plans to prices

Each plan in Octeth’s catalog has its prices and a linked user group. The group holds the limits from stage 7. Octeth billing places an account in its plan’s group on every plan change.

What the catalog supports:

  • One flat price per plan and interval. Monthly and yearly intervals work. Make each price tier its own plan.
  • Overage per 1,000 emails. It is a plan setting. Stage 1 covers when billed overage works.
  • Add-ons and credit packs. Per-unit add-ons and one-time credit packs sit next to the plans.
  • Versioned prices. You never edit a price. You create a new version of it in the price editor.

Plans come from the staff catalog screen or from the seeded starter catalog. Run the seeder once, then rename and re-price the seeded plans. To add a plan, duplicate a seeded one so it keeps its price settings.

An upgrade charges the prorated difference at once. A downgrade applies at once, charges nothing and credits the unused difference to the account balance in Octeth. An upgrade from a free plan to a paid plan, for example, charges the prorated part of the paid plan’s monthly price and moves the account to that plan’s group.

Trials

If you want new accounts to try the product before paying, make the signup plan a small free plan and keep each new account under review. We recommend a free plan with a small monthly allowance. Stage 1 covers the choice between a free plan, a trial or neither.

Failed payments and dunning

When a renewal charge fails, Octeth’s hourly dunning job takes over. With the default settings:

StepWhat Octeth doesCustomer access
Renewal failsMarks the subscription past due and emails the customerFull
First retry1 day after the failureFull
Second retry3 days after the first retryFull
Third retry5 days after the second retryFull
Third retry failsSuspends the account, moves it to your suspended group and emails the customerYour suspended group’s limits
Grace period ends unpaidCancels the subscription after 7 days, moves the account to your cancelled group and emails the customerYour cancelled group’s limits

The retries count declined charges. Watch the staff worklist for past-due accounts with no card on file: dunning does not suspend them.

Failed payment and dunning timeline, default settings Days counted from the failed renewal, with Octeth's default settings. Day 0: the renewal fails, Octeth marks the subscription past due and emails the customer. Day 1: first retry. Day 4: second retry. Day 9: third retry. When it fails, Octeth suspends the account, moves it to your suspended group and emails the customer. Day 16: the 7-day grace period ends unpaid, Octeth cancels the subscription, moves the account to your cancelled group and emails the customer. The customer has full access until day 9, your suspended group's limits from day 9, and your cancelled group's limits from day 16. Until cancellation, the customer can pay with Retry payment now on their billing page. A declined manual retry counts as one of the retries. Fullaccess Suspendedgroup'slimits Cancelledgroup'slimits Day 0: Renewal fails, past due Day 1: First retry Day 4: Second retry Day 9: Third retry fails Suspended, moved to yoursuspended group, emailed Day 16: Grace period ends unpaid Cancelled, moved to yourcancelled group, emailed Retry payment now The customer can pay until cancellation
With the default settings, an unpaid account is suspended on day 9 and cancelled on day 16. You set the retry days and the grace period in the staff billing settings.

Until the subscription is cancelled, a customer can pay with “Retry payment now” on their billing page. A declined manual retry counts as one of the retries, and on a suspended account it restarts the grace period. You set the retry days and the grace period in the staff billing settings. Octeth’s billing operations page describes the cycle. The grace period starts when the account is suspended and ends in cancellation.

Three things to settle before the first renewal:

  • The app’s mail. Dunning moves the account whether or not its email arrives. If the app’s own mail does not work, customers are suspended and cancelled without a word. Stage 4, installing Octeth, sets up that mail.
  • The suspended group. It decides what a customer who has not paid can still send. Set the suspended and cancelled groups in the billing settings’ lifecycle groups, not on each plan. When a suspended customer pays, the hourly billing check moves the account back to its plan’s group. Octeth keeps an account in any group linked to its plan, so a suspended group linked to the plan would keep a paying account suspended. Give the suspended group a sending limit of 1, because 0 means unlimited. Send that group’s mail from the free plan’s IP. Stage 7 covers the lifecycle groups.
  • Your terms. Write the retry and suspension policy into your terms of service, so a suspended customer has read it.

Include recovery in the test-mode run. Add Stripe’s test card that declines after it is saved (4000 0000 0000 0341), then run billing:run --now=<a date after the period end> and billing:dunning --now=<date> once for each retry day until the account is suspended (billing operations shows how to run the commands). Replace the card with a working test card, click “Retry payment now”, and check that the account is back in the plan’s group.

Dunning only chases renewal invoices. A declined plan change does not enter dunning.

Refunds

Staff refund a payment from the customer’s payments list in Octeth. From 6.0.1 the payment shows as Refunded or Partially refunded. From 6.0.1, Octeth also records refunds from Stripe’s refund events, so a refund made in Stripe’s dashboard shows up too. Subscribe the four refund events above.

A full refund cannot be disputed. A partly refunded payment can be disputed for its full amount (Stripe: dispute prevention). The next section uses that.

Sharing a Stripe account

Stripe’s rule is one account per business. Stripe says to use separate accounts for projects, websites or businesses that operate independently, and that one account should only ever represent one business (Stripe: multiple accounts, Stripe: dispute prevention). The reason is the card statement: every product on one account shows the same business details, and a customer who bought from one brand and sees another brand’s name on the statement may dispute the charge.

So a new ESP brand gets its own Stripe account. A second product of the same business can share one. If you share, check four things:

  • What Octeth does with the other product’s events. Octeth stores every signed event and acts only on its own payments. It matches an event by payment intent ID, or, for a payment that has none, by exact customer and amount within 15 minutes. The other product’s events are ignored, but its customer data lands in Octeth’s database.
  • What the other product does with Octeth’s events. A webhook on all events receives Octeth’s customers and charges. Find out how it handles customers it did not create before you go live.
  • The account’s default API version. Stripe answers a request that names no API version with the account’s default. If the other product upgrades that default, test Octeth against it.
  • Dispute rate. Disputes from both products count against the same account.

When you list a shared account’s webhook endpoints, print the hosts only. Endpoint URLs can contain other services’ secrets.

Stripe account risk from spammer disputes

Card disputes put your Stripe account at risk. An ESP refuses and suspends senders, and a refused sender who paid by card can dispute the charge. Stripe counts every dispute toward your dispute activity, won or lost. The card industry treats activity above 0.75% as excessive, and sudden rises can put a business into a card network monitoring program before it reaches 0.75% (Stripe: measuring disputes). Stripe notes that a business with fewer than 100 payments a month can see its dispute rate move a lot from one or two fraud disputes (Stripe: dispute prevention). A new ESP is that business.

An account still under review can buy a paid plan. Stage 8’s review stops it from sending, not from paying. These steps keep a refused sender from becoming a dispute:

  1. Review before paid volume. New signups land on a free plan and start Untrusted. They have no reason to pay before review approves them. Stage 8 covers the review.
  2. Refund in full when you refuse a payer. If you decline or suspend an account that has paid, a full refund cannot be disputed. Decide in your terms when you refund and when you keep the payment.
  3. Watch disputes in Stripe. When Stripe reports a dispute or an early fraud warning, look up the account in Octeth and review its sending.
  4. Make the charge recognisable. Set the statement descriptor to the brand or domain your customers know. Stripe allows 5 to 22 characters.
  5. Show the policies at checkout. Stripe advises showing your refund and cancellation terms in full and requiring agreement before purchase, so card issuers accept them as evidence.

Stripe Radar screens every payment with its default rules. If your Radar plan supports custom rules, as Radar for Fraud Teams does, you can add your own, for example to block card countries you do not serve (Stripe: Radar rules).

Tax

Settle how you will charge VAT, sales tax or GST before the first paid invoice. It is one of the business planning decisions in stage 1.

Go live

Switch to live once test mode has passed and stage 8’s review is running.

  1. Cancel and delete every test account. Their test-mode Stripe IDs fail under live keys.
  2. Create the restricted key in live mode and probe its permissions.
  3. Create the live webhook on a current API version with the events above. Store the signing secret in your password manager.
  4. In the gateway screen, open the Live payments tab, paste the live key, publishable key and signing secret, and save. Then choose “Switch to live payments” and confirm. Check that Stripe is still the active processor.
  5. Send the request without a valid signature to the live endpoint. Expect 401.
  6. Make the first real purchase yourself. Check the payment, the paid invoice, the processed webhook events and the account’s move to the plan’s group.

Octeth versions this stage relies on

FeatureOcteth version
Billing with Stripe, plans linked to user groups, proration6.0.0
Signed Stripe webhook at /ui/webhooks/stripe, restricted keys6.0.0
Dunning with retry days and grace period in the staff settings, “Retry payment now”6.0.0
Staff refunds stored, refunds recorded from Stripe refund events6.0.1
Declined plan changes void their proration invoice, staff void action6.0.2

This stage needs 6.0.2 or later. Stages 7 and 8 already need 6.0.5 and 6.0.6. Then run the test purchase in this guide on the version you install, and repeat it after each Octeth upgrade.

Before you move on

  • Vetting from stage 8 works before the first paid plan goes on sale.
  • The ESP has its own Stripe account, or a shared account carries only products of the same business and brand.
  • The statement descriptor shows the brand your customers signed up to.
  • Every plan's price, interval and linked user group are set in Octeth's catalog, and the plan bullets match them.
  • Test mode passed end to end: card added, plan changed, invoice paid, webhook events processed, account moved to the plan's group.
  • In test mode, an account suspended by failed renewals paid with Retry payment now and went back to the plan's group.
  • Test accounts are deleted before you switch to live keys.
  • Octeth uses a restricted key with only the permissions it needs, and each one was probed.
  • The live webhook points to /ui/webhooks/stripe, runs a current API version and carries the payment, charge, dispute and refund events.
  • Test-mode events reach Octeth with status 200, and the live endpoint returns 401 to a request without a valid signature.
  • The Stripe gateway shows as active before the test purchase.
  • The app's own mail works, because dunning emails go out with every state change.
  • You chose your retry days and grace period and wrote them into your terms.
  • You know how you will handle tax before the first paid invoice.
  • Someone watches Stripe for disputes and early fraud warnings, and checks the account in Octeth when one arrives.
  • You run Octeth 6.0.2 or later for this stage. Stages 7 and 8 already need 6.0.5 and 6.0.6.

What we've seen go wrong

A live webhook on a 2014 API version

When we created a live webhook, the endpoint was first set to Stripe API version 2014-03-28, older than the PaymentIntent objects Octeth reads. We recreated it on a current version before the first live payment. Each Stripe webhook endpoint has its own API version, so check it when you create the live endpoint.

A restricted key that could not list payments

When we moved an install from the full secret key to a restricted key, listing PaymentIntents failed until the key also had Disputes: Read. Stripe's error named the missing permission. Probe every permission with a read request before you put the key in Octeth.

Test accounts break under live keys

Accounts created in test mode keep test-mode Stripe customer and card IDs, and those fail under live keys. Cancel and delete the test accounts before you switch.

Your customers in another product's webhooks

When Octeth shares a Stripe account with another app whose webhook subscribes to every event, that app receives Octeth's customers and charges too. Check before go-live how it treats customers it did not create. Octeth stores the other app's events and ignores them, but they carry that app's customer data into Octeth's database.

Related glossary terms

We build ESPs

Rather have us build this?

We connect Stripe billing to your Octeth plans as part of the setup.