education - Feb 15, 2022

Stripe API keys – Everything you need to know

Are you thinking about using Stripe as your payment gateway on your website? No matter if you plan to use off-the-shelf or custom-built plugins (or other types of Stripe integrations) to accept payments, you’ll need to use Stripe APIs. To access these, you’ll need to get your Stripe API keys so that you can connect your plugin with the payment gateway.

Let’s cover the most important questions: what types of Stripe API keys do exist? How can you get and test them, and how can you keep them safe? Here’s the ultimate guide!

Stripe API keys – Why do you need them?

First things first, let’s discuss why you need Stripe API keys for your payments plugin.

The purpose of using Stripe API keys is to authenticate Stripe API requests. They need to be included when making an API request, otherwise, your request cannot be completed. The Stripe API keys are unique to your account, and this is the only way for the payment gateway to recognize that the API requests were made by your account. If you don’t include your key when making an API request or use an invalid or expired Stripe API key, Stripe returns a 401 – Unauthorized HTTP response code.

Stripe API keys – Types

Stripe API keys can be categorized in two ways:

  1. test or live mode keys;
  2. publishable or secret keys.

Consequently, you’ll always have at least four keys associated with your account.

Let’s see what these mean in practice.

1. Test or live mode keys

All Stripe API requests occur in either test or live mode. It’s important to note that API objects created in one mode aren’t accessible in the other. For instance, a subscription plan created in test mode is not available in live mode, and vice versa.

The question is: when should you use the test mode?

Use this mode when you test your plugin. In this case, payments are not processed by card networks or payment providers. API requests return simulated accounts, payments, customers, charges, refunds, transfers, and subscriptions. Webhooks that were not successfully delivered are attempted three times in a few hours, in contrast to 72 hours in live mode. All this ensures that you don’t accidentally charge money to someone’s account while you’re testing. Therefore, make sure to use test credit cards and accounts while you use your Stripe API keys in test mode.

Also, you need to note that Stripe objects – such as plans, products, coupons, tax rates (EU VAT rates), or shipping rates – created in test mode will not be available in live mode. Therefore, when going live, you need to recreate your products by clicking the “Copy to live mode” button:

Stripe objects created in test mode need to be recreated when going live.

When should you switch your Stripe API keys to live mode?

You’ve probably already guessed the answer: when you launch your app, plugin, or website. In this mode, all transactions will be live and real, test credit cards and accounts will not work anymore, and the API requests will return real customer accounts, payments, and so on. Use this mode only, if you’re really ready for the launch.

2. Publishable or secret keys

Publishable API keys are used to identify your account with Stripe. As the name suggests, these Stripe API keys are publishable; therefore, they can be used on websites available to the public.

Secret API keys have to be stored properly on your own servers to keep them confidential. Secret Stripe API keys can perform any API request.

How to get your Stripe API keys?

In order to get your Stripe API keys, first, you need to create your Stripe account.

Once you’re ready, you can find your Stripe API keys in your Stripe account’s dashboard. If you’re not the account’s owner and cannot see the Stripe API keys, you probably don’t have access to them. In this case, make sure to contact the account’s owner to obtain an administrator or developer role to gain access. Once you’ve proper access, follow these steps:

  • Sign in to your Stripe account.
  • In your dashboard, click “Developers”, then “API keys”.
  • On the “API keys” page, you can find both your publishable and secret keys under “Standard keys”. However, to reveal your secret key, click the “Reveal live key” button.
  • Test payments are called “Test mode” and real payments are called “Live mode” in your Stripe account. To switch between these two, click the “Viewing test data” toggle in the menu. Please note that each mode has different keys.

On the “API keys” page, you can find your publishable and secret Stripe API keys.

Find a short video below on how to obtain your test and live API keys:

How to keep your keys safe

Secret Stripe API keys can be used for API calls such as charging or refunding. Therefore, they should be kept in a safe digital environment. Think of them as passwords. Grant access only to those who need it, and ensure that the key is kept out of any version control system you may be using. To control access to your secret Stripe API key, you might use a password manager, for instance. Make sure to make a note in your dashboard of where you copied the given secret API key:

Always make a note in your dashboard of where you copied your secret Stripe API key.

In case secret Stripe API keys are compromised, one has the option to “roll the key”. This means you can block your key and generate a new one:

In case secret Stripe API keys are compromised, they can be blocked.

When rolling an API key, you can choose to block the old key immediately or allow it to work for 12 hours. The latter option will provide you with time to make the necessary transitions. However, you’ll be able to use the new key immediately in both cases.

Additional security

Secret Stripe API keys can be used for any kind of API request without limitation; therefore, you might want to add another layer of security to keep them safe.

You can create restricted Stripe API keys that enable you to limit access to them. Restricted keys are available to reduce the risks when building or using microservices and they can be revoked anytime if not needed anymore. However, they cannot be used for the development of your Stripe integration. Consequently, use your test API keys during development, and once the integration is live, use your live API keys.

For greater security, you can create restricted Stripe API keys.

Stripe API keys: how to make a test transaction?

Now that you are familiar with the test mode Stripe API keys, let’s take an example of how you can make a test transaction. In our example, we’ll demonstrate how you can test transactions on a WordPress site, using the WP Full Pay payments plugin.

First, follow these steps to configure the WP Full Pay publishable and secret Stripe API keys:

  1. Locate your test Stripe API keys (see above on how to do so).
  2. Copy and paste the test API keys into their respective fields on the “Full Stripe / Settings / Stripe” page in WP admin. (Copy your test publishable key into the “Stripe Test Publishable Key” field, then do the same for your test secret key.)
  3. Make sure that the “API mode” option is set to “Test”.
  4. Save changes.

You can configure the WP Full Pay publishable and secret Stripe API keys on the “Configure Stripe account” page.

Now, you can run a test transaction on any published form, including Stripe checkout pages if you have a payment, subscription, or donation form that is already created and published:

  1. Open the payment page of your website in a browser.
  2. In the card input field of the form, you can only use specific Stripe test cards. Based on the billing country, you may enter:
    • card number: 4242 4242 4242 4242;
    • the expiry date can be any date in the future;
    • use “123” as CVC.
  3. Press the “Pay” button as you would if you were a customer.
  4. And you are done! You should be redirected to the “successful payment” page (or thank you page) on your website.

If you need more details, check out this short video on how to complete a test transaction:

Where to find further information about Stripe API keys?

If you need further assistance on how to configure and test your Stripe API keys, you can find more information in the Stripe Docs or the Stripe API Reference.

Join our VIP list

Stay on top of the latest news about WP Full Pay

Your email address has been added to our mailing list. Thank you.
We couldn’t add you to our mailing list. Please try again.
Enter a valid e-mail address.

Tips & tricks to boost your business

Ready to add payment to your site?