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:
- Price ID: This corresponds to a product and price that you’ve already created in Stripe.
- 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 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.

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:

// 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 = 'price_aaaaaaaaaaaa'

  // Determine which price_id the user has selected
  const selectedProduct = userData.selected_plan === 'advanced' ? 'price_bbbbbbbbbbbb' : 'price_cccccccccccc'

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

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

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.

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 }),
  });
}

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

To collect these IDs:

To send them to your backend:

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

Keys and IDs that you’ll need

Setting up Stripe

Optional: Additional Stripe configurations