As you begin to integrate Stripe into your website or app, you'll want to know about the following account features and processes:
Test and live modes
Every account is divided into two universes: one for testing and one for running live transactions. All API requests exist in one of those two universes, and objects—customers, plans, coupons, and so forth—in one universe cannot be manipulated by objects in the other.
The test and live modes were designed to function almost identically, with a few necessary differences:
- In test mode, credit card transactions are not processed through the actual card networks and only our test card numbers can be used
- Test mode allows you to fake having a Stripe balance in order to test (fake) payouts
- Some payment methods using Sources have a more nuanced flow in live mode, with more steps required than those in test mode
- Disputes also have a more nuanced flow in live mode, and a simpler testing process
- Webhooks that were not successfully received are retried for up to five hours (as opposed to 72 hours for live mode)
Specific values to use and steps to take for testing purposes are on our testing page.
Related to these universes are your API keys, available through the Dashboard. Each key exists either in the live universe or in the test universe, and this is how Stripe tells what universe you are interacting with. You should only use your test API keys for testing. This will make sure that you don't accidentally modify your live customers or charges.
If you cannot see your API keys in the Dashboard, this means that you are not an administrator for the account, and have only Read & Write or Read Only access. You will need to contact your Stripe account's administrator to request access to view the API keys.
In addition to live and test mode, there are also two types of API keys: publishable and secret.
Secret API keys should be kept confidential and only stored on your own servers. Your account's secret API key can perform any API request to Stripe without restriction.
Keeping your keys safe
Your secret API key can be used to make any API call on behalf of your account, such as creating charges or performing refunds. You should only grant access to your API keys to those that need them. Ensure they are kept out of any version control system that you may be using.
If an API key is compromised, roll the key in the Dashboard to block it and generate a new one.
When rolling an API key, you can choose to block the old key immediately or allow it to work for 12 hours, providing you with time to make the transitions. In either case, the new key can be used immediately.
Restricted access keys
Your account’s secret API keys can be used to perform any API request without restriction. For greater security, you can create restricted API keys that limit access to, and permissions for, different areas of your account data. These take the place of your secret API key and should be used if you’re working with microservices that interact with the Stripe API on your behalf.
A restricted key allows only the minimum level of access that the service needs while protecting account data it doesn’t need. For example, you can create a restricted key that grants read-only access to dispute data, then use it with a dispute monitoring service.
If you no longer need a restricted key (or you suspect it has been compromised), you can revoke it at any time. Restricted keys can also be rolled, or edited to change its level of access.
Restricted keys are intended to reduce the risk when using or building microservices. They are not be used as an alternative to your account’s API keys during development of your Stripe integration—restricted keys cannot interact with many parts of Stripe’s API. Use your test API keys during development and live API keys once your integration is live.
Activating your account
Before activating your account, you can only interact with Stripe in test mode. All of Stripe's features are available in test mode, though no live charges using the card networks can be created.
Activating your account is a simple process: you fill out a form requesting some basic information about your product, your business, and your own personal relationship to your business. Once you've activated your account, you can immediately start using the live API and charge real cards.
Your account details are reviewed internally to ensure they comply with our terms of service. If we see a problem, we'll get in touch right away to resolve it as quickly as possible.
Public business information
The following details are provided to the card issuer whenever a payment is made. This information appears on card or bank statements to identify or further explain it.
- Business URL
- Phone number
- Business address
- Statement descriptor text
You can set how your business information appears on statements when you activate your account, and it can be updated at any time in your account’s Business Settings. Make sure your statement descriptor text and business information can be clearly associated with you. If a customer cannot recognize one of your payments, they may dispute it. Statement descriptors are limited to between 5 and 22 characters. They must contain at least 5 letters and cannot use the special characters
You can also set a dynamic statement descriptor when creating a charge so that each payment has its own custom statement descriptor text.
Giving team members access to your account
You can invite members of your team to access a Stripe account while protecting your sensitive information or restricting what actions they can perform. Manage your team within your account’s business settings and invite multiple users at the same time by separating their email addresses with a comma or space.
There are five user roles that you can choose from when adding a team member to your account, each with increasing restrictions on the actions they can take:
|Administrator||The user has the same level of access as the account owner and can view API keys, change account settings, invite new users, etc. Administrators cannot delete or make changes to the account owner. Only owners and administrators can connect the Stripe account to Connect platforms.|
|Developer||The user cannot manage team members on your Stripe account, update bank account information, or edit payout settings.|
|Analyst||The user cannot access any account settings or view API keys.|
|Support Specialist||The user cannot access any account settings or view API keys. They also cannot view summarized financial reports, aggregate payment information, inspect payouts from Stripe to your bank account, or view and make changes to Radar settings.|
|View Only||The user has read-only access to all payment information in your account but cannot access any account settings or view API keys. They also cannot view summarized financial reports, aggregate payment information, or inspect payouts from Stripe to your bank account, or view and make changes to Radar settings.|
If an invited user doesn’t have a Stripe account, they receive an invitation to join your account via email. A user with an existing account is prompted to log in, and can then switch between accounts.
You can keep track of recent activity on your Stripe account in the security history section of your Dashboard. This lists recent actions from all of your team members—from password and bank account changes to logins or data exports. You can also see in your account’s logs which of your team members performed any given action through the Dashboard (e.g., issued a refund).
Keeping your account safe
Once you've set up your account, you'll want to keep it safe. Here are some recommendations:
Keep private information private. Your password should be known only to you, and your secret API keys kept confidentially on your own servers. As a reminder, Stripe employees will never ask you for them.
Don't reuse your Stripe password. Your password should be unique to Stripe. If you use your password on another site and that site is compromised, an attacker could use those stolen credentials to take over your account.
Update your computer and browser regularly. We recommend configuring your computer to automatically download and install updates. (OS X, Windows) This helps protect your system against automated attacks and malware.
Beware of phishing. All genuine Stripe sites use the stripe.com domain and are HTTPS. If you get an email from us that you don't expect, go directly to our site to log in. Do not enter your password after clicking a link in email. If you're ever not sure it's really us, here's what to do.
Add your mobile number to your account. If you do, we'll text you a short numeric code when you attempt to log in from a new device which you'll need to provide to complete the login process. This means even if someone steals your username and password, they won't be able to log in. To use this feature, go to your user settings and enable two-step verification.
Managing multiple accounts
You can have multiple Stripe accounts associated with your email address. Each account is one you have either created or been given access to as a team member. To switch the account you’re currently viewing in the Dashboard, click on the name of your current Stripe account at the upper-left corner and then select the account to switch to.
You can create additional Stripe accounts at any time, each of which operates independently from one another. Check out our support documentation to learn more about using separate Stripe accounts for different projects or businesses.
Receiving email notifications
You can receive an email notification when any of the following occur:
- A successful payment is received
- An application fee is collected from connected account
- A payment is disputed by a customer
- A payment is marked as elevated risk by Stripe or a custom Radar rule
Email notifications be enabled or disabled in your user settings and apply on a per-user basis. If other members of your team access your account, they can also choose what email notifications they receive.
Specifying the time zone in the Dashboard
The default time zone for your Dashboard is the one you are located in when you signed up to Stripe. You can change this at any time in your account settings. If you are creating a new account while logged into an existing account, the new account inherits its time zone.
Changing the time zone only applies to the Dashboard. Reports exported from the Dashboard, information returned by the API, and the timing of your subscriptions and payouts remains in UTC (Coordinated Universal Time).