Developers setup quickstart
Every integration is unique, but you can plug Stripe’s development building blocks into your existing environment and tailor Stripe’s products to your business needs. To that end, create a Stripe account (if you haven’t already) and then you can set up your development environment to call the Stripe APIs, and learn about the high level integration fundamentals.
Get your API keys
Every call to a Stripe API must include an API secret key. When you create your Stripe account, we automatically generate a set of API keys (a publishable key and a secret key) for your personal use while in test mode. When you activate your account, you have a separate set of API keys for live mode.
For your convenience, Stripe dynamically populates code examples in our documentation with your test API keys while you’re logged in—assuring only you can see them. Your test API keys for are:
Type | Value | When to use |
|---|---|---|
| Publishable | pk_test_TYooMQauvdEDq54NiTphI7jx | On the client-side. Can be publicly-accessible in your web or mobile app’s client-side code (such as checkout.js) to tokenize payment information such as with Stripe Elements. By default, Stripe Checkout tokenizes payment information. |
| Secret | sk_test_4eC39HqLyjWDarjtT1zdp7dc | On the server-side. Must be secret and stored securely in your web or mobile app’s server-side code (such as in an environment variable or credential management system) to call Stripe APIs. |
Use only your test API keys for testing and development to make sure that you don’t accidentally modify your live customers or charges.
If you can’t see your secret API keys in the Dashboard, this means you don’t have access to them. Contact your Stripe account’s owner and ask to be added to their team as a developer.
Alternatively, you can use the Stripe CLI to call Stripe APIs in test mode directly from your terminal.
Install a Stripe library
Stripe’s server-side libraries provide high-level API abstractions that simplify interacting with Stripe’s platform by reducing the boilerplate code required. Install the Stripe server library that corresponds to your preferred programming language.
Choose your client libraries
In addition to the server libraries, you might need to install the client libraries corresponding to your frontend applications. Stripe provides client libraries for your React web application, as well as iOS, Android and React-native SDKs for your mobile apps. See the Client libraries documentation for more information and installation instructions.
There are also many third-party libraries created by the Stripe community so you can use a language we don’t officially support.
Verify your setup
After you set up your development environment to talk to Stripe, call an API to test it. One simple test is to create a sample product by calling the Prices API from your backend. This example creates both a product and the associated price data for that product:
The response contains the Stripe resource identifier (in id) of the price you just created, and the resource identifier for the product (in product).
{ "id": "price_1KlZelHjiWi4tHHQbusWPPLT", "object": "price", "active": true, "billing_scheme": "per_unit", "created": 1649254583, "currency": "usd", "livemode": false, "lookup_key": null, "metadata": { }, "nickname": null, "product": "prod_LSUeC19sef3vAA", "recurring": null, "tax_behavior": "unspecified", "tiers_mode": null, "transform_quantity": null, "type": "one_time", "unit_amount": 120000, "unit_amount_decimal": "120000" }
The new product you created in test mode appears in the Stripe Dashboard.
Choose your integration foundation
Stripe provides several integration options to support the varying degrees of complexity that you might need. As you’re setting up your payments integration, consider whether an out-of-the-box checkout flow is appropriate or whether you need the flexibility of a custom solution. For a list of all payment integrations, such as creating a subscription, see the Payments guide.
Integration | Branding | Payments | Description |
|---|---|---|---|
| Prebuilt checkout page with client-side and server-side code. Can use it for web apps. | Supports basic customization to match your brand. | Built-in support for one-time, subscription, and future payments for the payment methods you support. | Uses Stripe Checkout. A Stripe-hosted payment form to collect customer payment details and confirm payment, that redirects to your success page after payment. Conversion optimized, localized in supported languages, built-in Tax support, coupons, adjustable quantities, billing and shipping address collection. |
| Custom payment flow with client-side code (only). Can use it for web and mobile apps. | Supports fully-customized branding. | Built-in support for one-time, subscription, and future payments for the payment methods you support. | Uses Stripe Elements. A customizable client-side payment form you can use with your server-side code to collect customer payment details. You need to build the server-side code to create a PaymentIntent, collect payment details, confirm payment, and redirect to your success page after payment. |
Incorporate test flows
Take advantage of Stripe’s payment simulation test cards to validate your error handling and optimize your customers’ buying experience. At a minimum, handle the following payment responses gracefully in your application, using the test cards provided to simulate the response outcome.
Test cards are valid with any CVC, postal code, and future expiration date.
Response | Description | Test Card to Use | Handling |
|---|---|---|---|
200 - OK succeeded | The card payment succeeds and doesn’t require authentication. | 4242424242424242 | Redirect the customer to your success page. |
200 - OK requires_action | The card payment requires Strong Customer Authentication (SCA) for the initial payment and subsequent payments. | 4000002760003184 | Display the 3DS authentication modal so the customer can authenticate and authorize their payment. To learn more, see How intents work. |
402 - Request Failed incorrect_number | The card payment fails because of an incorrect credit card number. | 4000000000009995 | Ask the customer to enter their card again, or try a new credit card number. |
Configure listeners
Use webhooks to consume Stripe’s real-time API events so you can automate your order fulfillment systems or other services that might be downstream of your Stripe payments activity.
Stripe triggers a set of events in response to the Create a session API call for the Prebuilt Checkout page. Here are the typical one-time payment (not recurring) events that the checkout flow triggers.
When events occur | Events |
|---|---|
| When your customer clicks the Checkout button in your app. | Triggers the payment_intent.created event. |
| When your customer clicks the Pay button in the Stripe Checkout URL. | Triggers the payment_intent.succeeded, charge.succeeded, customer.created events. Note: the charge.succeeded event is triggered when a charge transaction is successfully recorded, not when the customer payment succeeded. |
| When your customer’s payment is successful and they’re redirected to your Success page. | Triggers the checkout.session.completed event with a payment_status of paid in the event object payload. |
To test a webhooks integration with the CLI, see Test a webhooks integration with the Stripe CLI.
Get API version notifications
Your first successful API call associates your account with the current API version, which continues to be the default version for your account until you update it. Sign up for the Developer Digest to make sure you’re aware of updates to our APIs so you can take advantage of new features and improvements.