Advanced Embedded Payment Widget – SubscriptionFlow

The Embedded Payment Widget allows you to collect customer information using your own form while SubscriptionFlow securely handles payment processing inside an embedded checkout.

Instead of redirecting customers to a separate checkout page, everything happens on a single page.

Typical Flow

Customer fills your form.
Customer enters card details in the SubscriptionFlow widget.
Customer clicks your button.
Payment is processed.
You receive a success or error response.
Redirect customer or continue your workflow.

Before You Start

You will need:

Your SubscriptionFlow domain
A Hosted Payment Page (HPP) checkout URL
A page where you want to display the payment widget
You can get the checkout URL from the product page: click Web Checkout on the plan, then copy the link on the URL tab of the Share Web Checkout drawer. The plan ID and product ID are part of this URL.

image (3) (1).png

Example checkout URL:

https://YOUR-DOMAIN.subscriptionflow.com/en/hosted-page/subscribe/PLAN_ID/product/PRODUCT_ID

Step 1: Add a Container for the Widget

Place a container anywhere on your page where you want the payment form to appear.

<div id="sf-checkout"></div>

Step 2: Add Your Own Form

You can use any form system such as WordPress, Elementor, WPForms, Gravity Forms, Shopify, Wix, React, Vue, Laravel, or a custom HTML form.

<form id="customer-form">
    
        <input
            type="text"
            name="first_name"
            placeholder="First Name"
            required
        >
    
        <input
            type="email"
            name="email"
            placeholder="Email Address"
            required
        >
    
        <button type="submit">
            Pay & Subscribe
        </button>
    
    </form>

Step 3: Load the SubscriptionFlow SDK

Add the SDK script before the closing body tag.

<script src="https://YOUR-DOMAIN/modules/paymentsflow/js/embed.js"></script>

Step 4: Mount the Payment Widget

Initialize the widget using your Hosted Payment Page URL.

const widget = SubscriptionFlow.mount('#sf-checkout', {
        checkoutUrl: 'YOUR_CHECKOUT_URL'
    });

Once loaded, the payment fields will appear inside the container.

Step 5: Pass Customer Data

Before processing payment, send customer information to SubscriptionFlow.

widget.setFields({
        ai_firstName: 'John',
        ai_lastName: 'Doe',
        ai_email: 'john@example.com',
        ai_billing_country: 'US'
    });

Available Parameters

The following parameters can be passed using widget.setFields().

  widget.setFields({
  
    /* Customer Information */
  
    ai_firstName: "John",
    ai_lastName: "Doe",
    ai_email: "john@example.com",
    ai_phone: "+123456789",
    ai_notes: "Customer notes",
  
    /* Billing Information */
  
    ai_billing_name: "John Doe",
    ai_billing_email: "john@example.com",
    ai_billing_address1: "Street 1",
    ai_billing_address2: "Suite 100",
    ai_billing_address3: "",
    ai_billing_city: "New York",
    ai_billing_state: "NY",
    ai_billing_country: "US",
    ai_billing_zip: "10001",
  
    /* Shipping Information */
  
    ai_shipping_name: "John Doe",
    ai_shipping_email: "john@example.com",
    ai_shipping_address1: "Street 1",
    ai_shipping_address2: "",
    ai_shipping_address3: "",
    ai_shipping_city: "New York",
    ai_shipping_state: "NY",
    ai_shipping_country: "US",
    ai_shipping_zip: "10001",
  
    /* Gift Subscription */
  
    gift_firstName: "Jane",
    gift_lastName: "Doe",
    gift_email: "jane@example.com",
    gift_company: "ABC Inc",
    gift_personalPhone: "+123456789",
    gift_workPhone: "+987654321",
    gift_addrLine1: "Gift Address",
    gift_addrLine2: "",
    gift_addrLine3: "",
    gift_city: "Dallas",
    gift_state: "TX",
    gift_country: "US",
    gift_zip: "75001",
  
    /* Pricing & Discounts */
  
    currency: "USD",
  
  
  });

charge_prices

Override individual charge amounts by charge ID and currency. In a hosted-page URL this is expressed as query parameters; in the embed widget, pass the same structure via setFields().

To get the Charge Price ID, click the Edit icon and copy the Charge Price ID. Please refer to the screenshot below.

image (4).png

// URL:  &charge_prices[<chargeId>][USD]=<totalPrice>
// becomes:
widget.setFields({
  charge_prices: {
    [chargeId]: { USD: totalPrice }
  }
});

Multiple charges:

widget.setFields({
  charge_prices: {
    'chargeId': { USD: '50.00' },
    'chargeId': { USD: '10.00' }
  }
});

You can provide only the fields you need. Any omitted fields will use their default values.

Step 6: Process Payment

const result = await widget.submit();

SubscriptionFlow will:

Create the customer
Process payment
Create the subscription
Generate the invoice

Step 7: Handle Success or Failure

const result = await widget.submit();
    
    if (result.status === 'success') {
    
        window.location.href = '/thank-you';
    
    } else {
    
        alert(result.message);
    
    }

Complete Example

<div id="sf-checkout"></div>
    
    <form id="customer-form">
    
        <input
            type="text"
            name="first_name"
            placeholder="First Name"
        >
    
        <input
            type="email"
            name="email"
            placeholder="Email Address"
        >
    
        <button type="submit">
            Pay & Subscribe
        </button>
    
    </form>
    
    <script src="https://YOUR-DOMAIN/modules/paymentsflow/js/embed.js"></script>
    
    <script>
    
    const widget = SubscriptionFlow.mount('#sf-checkout', {
        checkoutUrl: 'YOUR_CHECKOUT_URL'
    });
    
    document
        .getElementById('customer-form')
        .addEventListener('submit', async function(e){
    
            e.preventDefault();
    
            widget.setFields({
                ai_firstName: this.first_name.value,
                ai_email: this.email.value,
                ai_billing_country: 'US'
            });
    
            const result = await widget.submit();
    
            if(result.status === 'success') {
    
                window.location.href = '/thank-you';
    
            } else {
    
                alert(result.message);
    
            }
    
        });
    
    </script>

Supported Platforms

WordPress
Elementor
Divi
WPForms
Gravity Forms
Shopify
Wix
Squarespace
React
Vue
Angular
Laravel
CodeIgniter
ASP.NET
PHP Applications
Custom HTML Websites

Any platform that supports JavaScript can use the widget.

Security

Card information is entered directly into the SubscriptionFlow iframe.

Your website never handles card details, helping maintain PCI compliance while allowing full control over the customer experience.

What Happens After Payment?

When payment succeeds, SubscriptionFlow automatically:

Creates the customer
Creates the subscription
Creates the invoice
Processes payment
Returns a success response

You can then:

Redirect to a thank-you page
Submit your own form
Trigger an automation
Call your API
Display a success message

Need More Control?

Advanced integrations can use the following events:

widget.on('ready')
    widget.on('success')
    widget.on('error')
    widget.on('resize')

These events allow deeper customization of the checkout experience.