> ## Documentation Index
> Fetch the complete documentation index at: https://docs.9pic.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Stripe Key Setup

> Create a Stripe restricted key for 9Pic Checkout and add it to Payment Configuration.

> [!WARNING]
>
> 9Pic Checkout is a **Business plan** feature. Create Stripe keys only in the Stripe account and mode you intend to use for the event.

## Overview

A Stripe restricted key lets 9Pic Checkout use only the Stripe permissions it needs instead of a full-access secret key. Create the key in Stripe first, then paste it into **Payment Config -> Add Gateway -> Stripe** in 9Pic.

Use the downloadable [Stripe Restricted API Key Setup Guide](https://photos.9pic.ai/assets/common/Stripe%20Restricted%20API%20Key%20Setup%20Guide.pdf) as your external checklist while following this dashboard guide.

![Stripe Developers API keys page showing the Restricted keys section and Create restricted key button with existing key values redacted](https://assets.9pic.ai/docs/dashboard-guide/payment-config/stripe-api-keys-page-redacted.webp)

Stripe API keys page

## Before You Start

Make sure you have:

| Requirement | Why it matters |
| - | - |
| **Stripe admin access** | You need permission to create restricted keys. |
| **Correct Stripe account** | Keys belong to one Stripe account. Check the account switcher before creating one. |
| **Correct mode** | Use test mode for setup checks and live mode only when you are ready to accept real payments. |
| **A secure storage plan** | Stripe shows the new key value once. Store it in your team's approved password manager or secret store before adding it to 9Pic. |

> [!WARNING]
>
> Never place restricted keys in a public repository, frontend/mobile app, browser script, email, or chat message. Treat them like passwords.

## Create the Restricted Key in Stripe

**1. Open API keys**

Sign in to Stripe and open **Developers -> API keys**. In the **Restricted keys** section, click **Create restricted key**.

**2. Choose the purpose**

When Stripe asks how you will use the key, select **Powering an integration you built**, then click **Continue**.

![Stripe Create a restricted key panel showing the Powering an integration you built option](https://assets.9pic.ai/docs/dashboard-guide/payment-config/stripe-key-purpose.webp)

Choose how the restricted key will be used

**1. Choose your own permissions**

Select **Choose your own** so you can grant only the permissions 9Pic Checkout needs.

**2. Name the key**

Use a clear name such as `9Pic Checkout Restricted Key`. If you maintain separate test and live keys, include that in the name.

![Stripe Create restricted API key page showing the key name field and the permissions table](https://assets.9pic.ai/docs/dashboard-guide/payment-config/stripe-permissions-start.webp)

Restricted key name and permission table

## Required Stripe Permissions

Set only the rows 9Pic needs, and leave unrelated resources on **None**.

| Stripe resource | Permission | Used for |
| - | - | - |
| **Checkout Sessions** | Write | Opening Stripe Checkout for buyers and checking session status. |
| **Customers** | Write | Creating or updating buyer customer records for checkout and invoices. |
| **Payment Intents** | Write | Completing and checking card payments created through Checkout. |
| **Payment Methods** | Write | Supporting payment methods used by Stripe Checkout. |
| **Charges and Refunds** | Write | Stripe groups these together in the permission table. Choose Write so charge-related checkout workflows are not blocked. |
| **Balance** | Read | Reading balance-related Stripe information when needed for payment checks. |
| **Events** | Read | Reading Stripe event information for payment status checks. |
| **Files** | Read | Supporting Stripe-hosted payment or invoice file references when Stripe returns them. |
| **Invoices** | Read (Write also works) | Reading the invoice Stripe issues with each payment when **Include Stripe invoice** is on. Earlier invoices created by 9Pic used Write. |
| **Tax Rates** | Read | Listing your active Stripe tax rates for **A tax rate from your Stripe account**. Needed only if you use **Stripe gateway tax**. |
| **Tax Settings** | Read | Checking that Stripe Tax is set up for **Stripe Tax (automatic)**. Needed only if you use Stripe Tax. |
| **Tax Registrations** | Read (optional) | Showing how many active Stripe tax registrations you have. Stripe Tax works without it. |

New Stripe invoices are created by Stripe as part of the payment page, so 9Pic no longer uses **Invoice Items** for them. If your existing key already grants it, you can leave it.

> [!NOTE]
>
> Exact permission labels can vary by Stripe account and change over time, and 9Pic hasn't confirmed every label above on a live account. 9Pic flags a missing permission where it's found: **Payment Configuration** for checkout and invoice reads, and **Tax Configuration → Stripe gateway tax** for tax reads. Stripe may also rename or combine rows over time. For example, some accounts show **Charges and Refunds** as one row. If Stripe shows a permission-denied message later, edit the restricted key, add the missing resource permission, save, and test again.

![Stripe permissions table showing Charges and Refunds, Customers, Events, and Files rows](https://assets.9pic.ai/docs/dashboard-guide/payment-config/stripe-core-permissions.webp)

Core permissions in Stripe

![Stripe permissions table showing Payment Intents, Payment Method Configurations, Payment Method Domains, and Payment Methods rows](https://assets.9pic.ai/docs/dashboard-guide/payment-config/stripe-payment-permissions.webp)

Payment permissions in Stripe

## Set Up Participant Invoices

After setting up your key, follow [Stripe Invoice Setup](https://docs.9pic.ai/account/payment-gateways/stripe-invoices.md) to review your business details, invoice currency, tax rate, and invoice PDF layout. The guide includes a 10% inclusive GST example in Australian dollars (AUD) and explains what to change for your country.

> [!WARNING]
>
> Creating a tax rate in Stripe doesn't apply it to 9Pic purchases by itself. Choose it for the gateway in **Payment Configuration → Tax Configuration → Stripe gateway tax**, then set **Package prices** and, if participants need a Stripe invoice, **Include Stripe invoice** in the event's **Checkout → Configuration → Payments → Stripe purchases**. Stripe charges a fee for each invoice it creates. See **Using this with 9Pic Checkout** in the guide.

## Save the Key Safely

**1. Review before creating**

Confirm the key name, Stripe account, test/live mode, and permissions before you click **Create key**.

**2. Create and copy once**

Click **Create key**. Stripe shows the restricted key value only once. Copy it immediately and store it securely.

**3. Do not share it casually**

Do not paste the key into email, chat, screenshots, task tickets, public documents, or browser-side code.

> [!WARNING]
>
> Do not create a live key until the Stripe account is ready for real payments. Test the setup with an `rk_test_` key first, then create a separate `rk_live_` key for production.

## Add the Key to 9Pic

**1. Open Payment Config**

In 9Pic, open **Payment Config** from the dashboard sidebar.

**2. Add a Stripe gateway**

Click **Add Gateway**, choose **Stripe**, and paste the restricted key into the **Stripe Secret Key** field. The field stores the protected Stripe credential for your organisation, even when the key starts with `rk_test_` or `rk_live_`.

**3. Create the gateway**

Click **Create Gateway**. 9Pic checks the key with Stripe straight away. The message after saving tells you the result, and the gateway list shows it under **Secrets**. When everything is in place, you see **Key accepted**.

**4. Assign Stripe to your events**

For each event that should use Stripe, open the event's **Checkout** product, go to the **Configuration** tab and, in **Payments**, assign the Stripe gateway on the **Payment gateways** row.

## Key Check After Saving

When you save the key, 9Pic asks Stripe whether it accepts the key and whether the key can read **Checkout Sessions**, **Customers**, **Payment Intents** and **Invoices**. The check only reads from your Stripe account, so nothing is created and nobody is charged. It runs again whenever you save a new key in **Edit**.

| Secrets shows | What it means |
| - | - |
| **Key accepted** | Stripe accepted the key, and it can read all four. **Checked** and the date appear under it. |
| **Missing permissions** | The key can't use one or more of those rows. A note above the list names them, for example **Checkout Sessions, Invoices**. |
| **Key not accepted** | Stripe refused the key. Buyers can't pay through this gateway until you save a working key. |
| **Configured**, with **Couldn't check the key** | 9Pic couldn't reach Stripe. Select **Check key** to try again. |

> [!NOTE]
>
> 9Pic can't check whether a key can **write** without creating a payment, so your first test payment confirms write access. If a row is set to Read instead of Write, you can still see **Key accepted**, and the first payment or invoice then shows **Payments blocked** or **Invoices blocked**. Set every row in the table above to the access it lists.

After you change the key's permissions in Stripe, select **Check key** next to **Edit** on the gateway to check it again. The check is for your information only: the gateway is saved whatever the result, and it never stops buyers paying.

## Verify the Setup

Before using Stripe for a live event:

| Check | What to confirm |
| - | - |
| **Key accepted** | The Stripe gateway shows **Key accepted** under **Secrets** in **Payment Config**. |
| **Test payment opens** | A buyer can open Stripe Checkout from a test event. |
| **Payment completes** | A test payment returns to 9Pic and marks the order as paid. |
| **Invoice support works** | If buyers need invoices, turn on **Include Stripe invoice** and make a test purchase with your own Stripe test key; the purchase shows **Download invoice**. |
| **Stripe gateway tax works** | If you use **Stripe gateway tax**, the choice saves without a permission message and the test payment page shows the expected tax. |
| **Blocked access stays blocked** | Unrelated Stripe resources should remain inaccessible to this restricted key. |
| **Logs look normal** | Review Stripe logs for permission errors after the test run. |

## Troubleshooting

> [accordion] Stripe says the key does not have permission.
>
> Open the restricted key in Stripe, find the resource named in the error message, set the needed permission, save, and retry the test payment. For an invoice, ask the participant to select **Check again** on their purchase.

> [accordion] Payment Config says Key missing permissions on my Stripe gateway.
>
> When 9Pic checked the key, Stripe said it can't use some of the rows 9Pic Checkout needs. The note above the gateway list names them, for example **Checkout Sessions, Invoices**, and the **Secrets** column shows **Missing permissions**. Buyers may not be able to pay or get invoices through this gateway.
>
> In Stripe, open **Developers -> API keys**, edit the restricted key, set those rows to **Write** and save. You don't need a new key. Then select **Check key** on the gateway in **Payment Config**. **Secrets** shows **Key accepted** once Stripe allows it.

> [accordion] Payment Config says Key not accepted on my Stripe gateway.
>
> When 9Pic checked the saved key, Stripe didn't accept it. The key may have been copied incompletely, or deleted, rolled or expired in Stripe. Buyers can't pay through this gateway until you save a working key.
>
> Paste the key again from where you stored it, or create a new restricted key with the permissions above. Select **Edit** on the gateway in **Payment Config**, paste the key and save. 9Pic checks it again when you save. If a buyer's payment was already refused, you see **Key rejected** instead (see below).

> [accordion] Payment Config shows Payments blocked on my Stripe gateway.
>
> Stripe refused to open a payment page for a buyer because the restricted key is missing a permission, usually **Checkout Sessions: Write**. The buyer was told payment isn't set up correctly for the event and wasn't charged. The warning on **Payment Config** (and on the event's **Payment gateways** card in Checkout configuration) names the permission, when it was last refused and the purchase number.
>
> In Stripe, open **Developers -> API keys**, edit the restricted key, set the named resource to **Write** (Write includes Read), and save. You don't need a new key. The warning clears after the next payment page opens on that gateway, or when you save a new key in 9Pic.

> [accordion] Payment Config shows Payment checks blocked on my Stripe gateway.
>
> Stripe refused to check or cancel a buyer's existing payment because the restricted key is missing a permission, usually **Checkout Sessions**. Nothing is lost: those orders stay pending and are never marked failed or paid because of this. Buyers are told the payment can't be checked right now and that you've been told.
>
> Set the named resource to **Write** on the restricted key in Stripe and save. Pending orders update the next time they are checked, and the warning clears after the next successful check.

> [accordion] Payment Config says Key rejected on my Stripe gateway.
>
> Stripe no longer accepts the saved key, usually because it was deleted, rolled or expired in Stripe. Buyers can't pay through this gateway (they are told payment isn't set up and aren't charged), and pending payments can't be checked until the key is replaced. The gateway shows **Key rejected** and **New key needed**.
>
> Create a new restricted key in Stripe with the permissions above, then select **Edit** on the gateway in **Payment Config**, paste the new key and save. The warning clears when you save it, and pending orders update the next time they are checked.

> [accordion] Payment Config shows Invoices blocked on my Stripe gateway.
>
> 9Pic tried to read the invoice Stripe issued with a buyer's payment, and Stripe refused because the restricted key is missing a permission, usually **Invoices** (Read). The buyer's payment is complete and their downloads work; their purchase keeps saying the invoice is being prepared. The warning on **Payment Config** (and on the event's **Payment gateways** card in Checkout configuration) names the missing permission. The warning text may still mention **Get invoice**, which buyers no longer use for Stripe purchases.
>
> In Stripe, open **Developers -> API keys**, edit the restricted key, set the named resource to the shown access level, and save. You don't need a new key. 9Pic checks pending invoices again automatically, or the buyer can select **Check again**; the warning clears after the next invoice is read on that gateway, or when you save a new key in 9Pic.

> [accordion] Stripe gateway tax says my Stripe key needs another permission.
>
> The key can't read your tax rates (**Tax Rates: Read**) or your Stripe Tax settings (**Tax Settings: Read**). Add the named permission to the restricted key in Stripe and save. If you replaced the key instead, save the new key in **Payment Config**. Then select **Check again** in **Payment Configuration → Tax Configuration → Stripe gateway tax**.

> [accordion] I copied the key but lost it before adding it to 9Pic.
>
> Create a new restricted key, store it securely, add the new value to 9Pic, then revoke the unused key in Stripe.

> [accordion] Should I use the same key for test and live payments?
>
> No. Keep separate keys for test mode and live mode. This reduces mistakes and makes rotation easier.

> [accordion] The 9Pic field says Stripe Secret Key. Can I paste a restricted key?
>
> Yes. Paste the restricted key value there. Stripe restricted keys start with `rk_test_` in test mode and `rk_live_` in live mode.

## Next Steps

> [card] [Payment Config](https://docs.9pic.ai/account/payment-gateways.md)
>
> Create and manage organisation-level gateway configurations.

> [card] [Checkout Setup](https://docs.9pic.ai/products/checkout/configuration.md)
>
> Assign a gateway to an event, publish plans, and enable Checkout.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.