Stripe setup

Connect Dunity to Stripe with a restricted key

You never share your secret key. You create a restricted key in Stripe with eight permissions, paste it into Dunity, and Dunity adds its own webhook. Here is each step, and what to do if one fails.

Get startedSee pricing
  • $29/month, flat
  • Cancel anytime
  • Restricted Stripe key only

The steps

  1. In Dunity

    Subscribe, then open Connect Stripe

    The Connect Stripe page opens once you have a Dunity subscription. It lists the permissions your key needs and has the field where you paste it.

  2. In Stripe

    Start a restricted key

    On Stripe’s API keys page, click Create restricted key and start from zero permissions. Give it a name you’ll recognise, such as Dunity. Stripe explains restricted keys in its documentation.

  3. In Stripe

    Set the eight permissions

    Give each resource in the list below the access shown, and leave everything else on None.

  4. In Stripe

    Create the key and copy it

    Click Create key, complete Stripe’s two-factor check and copy the key. It starts with rk_test_ in test mode or rk_live_ in live mode. Treat it like a password.

  5. In Dunity

    Paste it in and press Verify and Connect

    Paste the key into the Stripe restricted key field. You can also paste your publishable key, which starts with pk_. It is optional, but it gives customers Dunity’s card-update page, and win-back offers need it.

  6. Automatic

    Dunity checks the key and adds its webhook

    Dunity tests each of the eight permissions and, if one is missing, tells you which. Then it registers a webhook in your Stripe account with the same key. The webhook listens for three events: invoice.payment_failed, invoice.payment_succeeded and invoice.paid.

The eight permissions

Set exactly these on the key. Each row says what Dunity uses it for.

  • Webhook Endpoints · WriteSets up the webhook that tells Dunity when a payment fails, and removes it when you disconnect.
  • Invoices · WriteRetries the charge on an invoice your customer already owes.
  • Payment Intents · ReadReads why a payment failed, so the next retry can be timed to the decline reason.
  • Customers · WriteSaves the new card a customer enters as their default, so the next retry uses it.
  • Checkout Sessions · WriteOpens the secure Stripe page where a customer enters a new card.
  • Setup Intents · ReadConfirms which card was saved on that page.
  • Payment Methods · ReadReads a card’s brand, last four digits and expiry for card-expiry reminders. Never the full number.
  • Credit Notes · WriteApplies the win-back discount you choose, as a credit on the unpaid invoice.

Stripe treats Write as including Read, so a resource that shows Write where Dunity asks for Read is fine. The full reasoning is on the security page.

Try it in test mode first

The connection’s mode follows the key. An rk_test_ key connects in test mode, and the Connect page shows a Test mode badge. Stripe’s own documentation recommends building and testing in a sandbox first.

If you add a publishable key, it has to match: pk_test_ with rk_test_, and pk_live_ with rk_live_. A Dunity account holds one Stripe connection, so to move from test to live you disconnect and connect again with the live key.

If a step fails

What you might see when you press Verify and Connect, and what to do.

  • Your restricted key is missing Customers, Write. Add it to the key in Stripe, then try again.

    The key lacks a permission, and the message names it. Edit the key in Stripe, add the named permission, and press Verify and Connect again.

  • That restricted key looks invalid or has already been revoked in Stripe.

    Stripe rejected the key: it was copied wrongly, expired or revoked. Create a new restricted key and paste that one.

  • A message that your restricted key is in live or test mode and the publishable key must match.

    The publishable key is from the other mode. Paste the publishable key from the same mode as the restricted key, or leave it blank and add it later.

  • You already have a connected Stripe account.

    A Dunity account holds one Stripe connection at a time. Disconnect on the Connect page first, then connect the new key.

  • Could not register the webhook right now. Try again in a moment.

    Stripe didn’t let Dunity create the webhook, or was slow to answer. Press Verify and Connect again. If it repeats, check that Webhook Endpoints is set to Write on the key.

  • An active subscription is required to connect Stripe.

    The Connect page opens after you subscribe. Subscribe first, then connect.

Disconnecting

Choose Disconnect on the Connect page. Dunity removes its webhook from your Stripe account and deletes the stored key. This works even if your subscription has lapsed.

Removing the webhook is a best effort: if the key was already revoked, Stripe may refuse, and you can delete the webhook in Stripe yourself. To cut access off from Stripe’s side too, open the key’s overflow menu on Stripe’s API keys page and expire it, as Stripe’s documentation describes.

Stripe setup questions

The details people ask before they connect.

Does Dunity need my Stripe secret key?

No. Dunity only accepts a restricted key, one that starts with rk_, and asks for eight permissions. None of them can refund, pay out or transfer money.

Can I try it in Stripe test mode?

Yes. Connect with an rk_test_ key and the Connect page shows a Test mode badge. Stripe’s own documentation recommends building and testing in a sandbox first. A Dunity account holds one connection, so to move to live mode you disconnect and connect again with a live key.

Do I have to add the publishable key?

Not to connect. Without it, customers’ failed-payment emails link to Stripe’s own invoice page, and win-back offers aren’t sent. Add it now or later from the Connect page, and it has to match the restricted key’s mode.

What does Dunity change in my Stripe account?

It adds one webhook endpoint. With the key it retries invoices, saves the new card a customer enters as their default, and, if you turn on win-back offers, creates a credit note on the unpaid invoice.

How long does setup take, and do I need a developer?

A few minutes, and no. The only step that needs a developer is the optional payment wall, which is one script tag in your app.

How do I remove Dunity’s access?

Choose Disconnect on the Connect page. See the section on disconnecting below for what that removes, and how to cut access off from Stripe’s side as well.