Accepting Stripe Payments in Embeddables

Payments in Embeddables are handled via Stripe, with a dedicated Stripe component that is integrated deeply into our platform.

Keys and IDs that you’ll need

Your Stripe Publishable Key
A Restricted Key generated in Stripe, with the following scopes/permissions:
- Customers: Write
- Payment Intents: Write
- Setup Intents: Write
- Checkout Session: Write
- Credit notes: Read
- Subscriptions: Write
Any Price IDs for specific products you want to offer

Setting up Stripe

The following are the minimum steps required to add a Stripe component to your Embeddable:

Generate and share the necessary Stripe keys

Get your Publishable Key, and generate a Restricted Key with the scopes/permissions listed above, from the API Keys section of your Stripe Dashboard.
Pass these keys to the Embeddables Team (make sure to share the Restricted Key in a secure way).

Add a Stripe component to your Embeddable

In the Builder, switch to the checkout page that should contain the Stripe component.
Select a Container to insert the Stripe component into, or a copmonent that it should be added next to.
Open the + left-hand sidebar, and select Stripe from the list of components.

Choose the type of payment you want to accept

Under Checkout mode, select one of the following options:
- Payment: If you’re accepting only one-time payments, or want to place a hold on a user’s card.
- Setup: For setting up a user’s payment method to take payments in the future.
- Subscription: If your line items will include at least one recurring payment.

Please note that Stripe only supports placing a hold on one-time payments, not recurring payments.

Choose which payment methods you want to accept

Under Payment methods, select the payment methods you want to accept, from the following options:
- Credit card
- Link (Stripe’s own quick purchase login system)
- US Bank Account
- Buy now, pay later services: Afterpay/Clearpay, Klarna, Affirm

You need to have the relevant payment methods enabled in your Stripe account in order for them to appear for users.

Add line items to the checkout

There are two different types of line item that you can add:
1. Price ID: This corresponds to a product and price that you’ve already created in Stripe.
Make sure to grab the Price ID from Stripe, rather than the Product ID.
How to find the Price ID
- Go to the Product Catalog section of your Stripe Dashboard.
- Select the product you want to use.
- Click on the more options (three dots) icon button in the Price that you want to use.
- Select Copy price ID.
1. Custom line item: This lets you manually enter an amount, currency and name for the line item in Embeddables.
Both types of line item require you to enter a quantity.

If you need your line items to be dynamic (i.e. change based on the user’s answers, like what plan they select), see the Add dynamic line items section below.

Include the customer email address (and, optionally, phone number)

To insert the user’s given email address into the Stripe checkout, add the key name of the component you use to collect the user’s email, using Templating (e.g. {{email}}).
You can optionally collect a user’s phone number, using the same method.

By default, Stripe’s credit card fields will also include Country and Zipcode / Postal Code fields.These are all Stripe needs for a customer billing address, so you don’t need to provide any billing address fields.

Optional: Additional Stripe configurations

These features are not required in order to successfully accept payments, but they can be useful in different scenarios.

Collect shipping information

Add dynamic line items

Sometimes you need your line items to be dynamic - i.e. change based on the user’s answers, such as the plan that they select.To do this:

Use a Computed Field` to generate the JSON for the line items.
Refernce the key of that Computed Field in the Line Items section of the Stripe component.

In order for the Stripe component to still work when the Embeddable is in test mode, you need to ensure that the Computed Field handles test mode correctly by returning a test price_id.

Example Computed Field code:

// @TODO: Delete one of these based on whether you're charging a recurring or one-time payment
const TEST_PRICE_ID = 'price_1JMwNRIQ3JVMlttKsvCn3lK3' // This is a recurring Embeddables-provided test price ID
const TEST_PRICE_ID = 'price_1KGqjRIQ3JVMlttKzJ059opF' // This is a one-time Embeddables-provided test price ID
// @TODO: Replace these constants
const PRICE_ID_PLAN_1 = 'price_aaaaaaaaaaaaaaaaaaaaaaaa'
const PRICE_ID_PLAN_2 = 'price_bbbbbbbbbbbbbbbbbbbbbbbb'

// All Computed Fields must contain a function called result()
function result(userData) {
  // Determine whether we're in test mode
  const url = new URL(window.location)
  const isTestMode = url.searchParams.get('savvy_test') === 'true'
    || (!url.searchParams.get('savvy_test') && url.searchParams.get('savvy_env'))
    || (!url.searchParams.get('savvy_test') && url.host.endsWith('embeddables.com'))
  const testPriceId = TEST_PRICE_ID

  // Determine which price_id the user has selected
  const selectedPriceId = userData.selected_plan === 'advanced' ? PRICE_ID_PLAN_2 : PRICE_ID_PLAN_1

  // If we're in test mode, use the test price_id, otherwise use the selected product's price_id
  const priceId = isTestMode ? testPriceId : selectedPriceId

  // Return the line items
  return [
    {
      price: priceId, 
      quantity: 1,
    },
  ];
}

Set values based on dynamic data

Control Stripe prices from the Embeddables CMS

Apply coupons and promo codes

Place a hold on the customer's card

Automatically set default payment methods in Stripe

Add a custom success message

Choose a layout for the Stripe component

Set up Apple Pay and Google Pay

Set up Stripe Link

Trigger actions on payment events

You can trigger Actions on the following payment events:

Event	Triggered when
Payment attempted	The user clicks the Pay button (regardless of success or failure)
Payment successful	The payment is completed
Payment failed	The payment is declined

To do this:

Create a new Action and type the JavaScript code you want to run.
Add a Trigger to the Action that fires on one of the above payment events.

Collect Stripe IDs to send to your backend

You can collect the following IDs that Stripe provides when a payment is completed:

Stripe ID	Provided for
Customer ID	All payment types
Invoice ID	All payments except on-hold payments and collecting card details
Payment Intent ID	One-time payments only
Subscription ID	Recurring payments only

To collect these IDs:

Specify a User Data key to store the ID in, in the relevant field in the Stripe component options.
Add that key to the Registered Keys in the Embeddable-wide settings.

To send them to your backend:

Set up an Action that’s triggered when the payment is completed, as specified above in Trigger actions on payment events.
Use the relevant keys in userData, provided in the Action function’s first argument.

Example Action code:

// All Actions must contain a function called output()
// Trigger this Action when the payment is completed
function output(userData) {
  // Extract the relevant IDs from the userData object
  const { customer_id, invoice_id, subscription_id } = userData;
  console.log(customer_id, invoice_id, subscription_id);

  // Send these IDs to your backend
  fetch('https://your-backend-url.com/', {
    method: 'POST',
    body: JSON.stringify({ customer_id, invoice_id, subscription_id }),
  });
}

Store the selected plan/product and payment status in User Data

Send custom metadata to Stripe

Troubleshooting

I'm getting an error about a missing publishable key

I'm getting an error about a missing restricted key

Error: You must provide one of `price` or `price_data` for each line item when using prices.

Error: No such price: 'price_xxxxxx'; a similar object exists in test mode, but a live mode key was used to make this request.

Error: No such price: 'price_xxxxxx'

I'm seeing test mode errors on a live link

I'm seeing live mode errors on a test link

Get Started

Features

Guides & Best Practices

How To's

About These Docs

Accepting Stripe Payments in Embeddables

Keys and IDs that you’ll need

Setting up Stripe

Optional: Additional Stripe configurations

Google Pay

Apple Pay

To collect these IDs:

To send them to your backend:

Storing the plan or product

Storing the payment status

Troubleshooting

Get Started

Features

Guides & Best Practices

How To's

About These Docs

​Keys and IDs that you’ll need

​Setting up Stripe

​Optional: Additional Stripe configurations

​Troubleshooting

Keys and IDs that you’ll need

Setting up Stripe

Optional: Additional Stripe configurations

Troubleshooting