Skip to main content
Loading…

Advanced Embedded Payment Widget

  • Updated

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

  1. Customer fills your form.
  2. Customer enters card details in the SubscriptionFlow widget.
  3. Customer clicks your button.
  4. Payment is processed.
  5. You receive a success or error response.
  6. 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 Subscription Product Details page by clicking the Web Checkout button. Please see the screenshot below.
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.

Related articles

Comments

0 comments

Please sign in to leave a comment.