How to create a Stripe restricted key for Zendesk
By Jake Marsh · Updated
To connect Stripe to Zendesk with Tillwell, create a restricted key in the Stripe Dashboard under Developers > API keys > Create restricted key, name it "Tillwell for Zendesk", set Read on the six resources below and Write only where you want actions, and leave everything else at None. Copy the rk_live_... value, then paste it into Stripe restricted key in Tillwell's settings in Zendesk.
Why a restricted key
A restricted key can do only what you allow. Stripe recommends restricted keys over secret keys for anything you hand to another service, and Tillwell never asks for a secret key. You decide, resource by resource, whether Tillwell may read or also write.
Steps
- Open API keys in the Stripe Dashboard (Developers > API keys) and click Create restricted key.
- Name it "Tillwell for Zendesk", so it's easy to find and revoke later.
- Set the permissions from the table below. Leave every other resource at None.
- Create the key and copy its value. Stripe asks for two-step verification and shows the full value only at this point, so copy it now.
- Paste it into Zendesk. In Admin Center > Apps and integrations > Apps > Zendesk Support apps, open Tillwell, paste the key into Stripe restricted key and set Account name (for example your company name). Save.
- Test it. Open a ticket from a paying customer. Their Stripe customer should appear in the sidebar.
Which permissions to set
| Stripe permission | Level | What it's for in Tillwell |
|---|---|---|
| Customers | Read | Finding the customer by email, customer id or metadata |
| Products | Read | Product names on subscriptions |
| Payment Disputes | Read | Dispute alerts with the response deadline |
| Charges and Refunds | Read, or Write for Refund and Email receipt | Payments, refunded amounts, failed payments, lifetime value |
| Subscriptions | Read, or Write for Cancel at period end, Keep subscription, Pause payments, Resume payments | The subscription list |
| Invoices | Read, or Write for Email invoice | The invoice list |
All six at Read gives a fully working sidebar with no actions. You can raise one resource to Write later with Edit key on the key in Stripe.
Live mode and test mode
Use a live-mode key (rk_live_...) in production. A test-mode key (rk_test_...) works for a trial run: customers then show "(test mode)" and Open in Stripe goes to your test dashboard.
More than one Stripe account
Fill in the key and name for account 2 and 3 in the same settings page. Brands for this account takes Zendesk brand ids (Admin Center > Account > Brand management > Brands; the id is in the brand's URL). A ticket opens the account that lists its brand, otherwise the account with no brand list, otherwise account 1. Each account needs its own restricted key.
Error messages and fixes
| The sidebar says | Fix |
|---|---|
| "Stripe did not accept the API key" | The key was deleted or rolled in Stripe. Create a new restricted key and paste it in the settings. |
| "The restricted key cannot do this ... charge_write" | Add the permission Stripe names to the key. Here that's Charges and Refunds: Write. |
| "Metadata match skipped" | Stripe's customer search isn't available for the account, or the key lacks Customers: Read. Email matching still runs. |
| No customer found | The requester's email doesn't match Stripe. Use the lookup box, or map a user field or metadata key. |
Match customers who use another email
Two optional settings help when emails don't line up:
- User field with the Stripe customer id: the key of a Zendesk user field (Admin Center > People > Configuration > User fields) that holds a
cus_...id. - Stripe metadata key with the Zendesk user id: if your signup flow stores the Zendesk user id or external id in the Stripe customer's metadata (for example
zendesk_user), Tillwell finds the customer by it with Stripe's customer search.
What it costs
Tillwell is $5 per agent per month on the Standard plan, billed monthly by Zendesk, with a 14-day free trial. Zendesk asks for a card at install. See the Tillwell documentation for every setting and Stripe's own guide to restricted API keys.
Tillwell
Stripe customer sidebar: refund, cancel or pause from the ticket, with every action logged. $5 a month per agent.
Questions
Can I use my Stripe secret key instead?
Use a restricted key. It limits Tillwell to the resources you pick, and you can revoke it without touching your own integrations.
Where is the key stored?
In Zendesk's secure settings. It never reaches an agent's browser, and Zendesk only sends it to api.stripe.com.
I lost the key value. Can I see it again?
Stripe shows it once. Create a new restricted key with the same permissions and paste that one.
What should I do when we stop using the app?
Uninstall it in Zendesk, which deletes the stored keys, then delete the restricted key in Stripe.
More Tillwell guides
- How to cancel or pause a Stripe subscription from Zendesk
- How to refund a Stripe payment from a Zendesk ticket