Skip to main content
Loading…

Embedded In-App Widgets

  • Updated

Embedded Widgets: Checkout, Payment Method Update, and Customer Portal

SubscriptionFlow's Embed SDK allows you to integrate SubscriptionFlow directly into your own website without redirecting customers to a hosted SubscriptionFlow page.

Using a single JavaScript SDK, you can embed:

  • Embedded Checkout
  • Payment Method Update
  • Customer Portal

Loading the SDK

Add the SubscriptionFlow Embed SDK to your page.

<script src="https://<tenant>.subscriptionflow.com/modules/paymentsflow/js/embed.js"></script>

Example

<script src="https://demo.subscriptionflow.com/modules/paymentsflow/js/embed.js"></script>

The SDK exposes a global object named:

SubscriptionFlow

Available Widgets

WidgetDescriptionMount Method
Embedded CheckoutEmbeds a Hosted Payment Page or Public Checkout Page directly into your website.SubscriptionFlow.mount()
Payment Method UpdateAllows customers to securely update their saved payment method.SubscriptionFlow.mount()
Customer PortalEmbeds the SubscriptionFlow self-service customer portal.SubscriptionFlow.mountPortal()

HTTPS Requirement

Payment forms are displayed inside an iframe. For production environments, your website must use HTTPS. Modern browsers block payment submissions from insecure HTTP pages.

Embedded Checkout

The Embedded Checkout widget allows customers to complete payments directly from your website.

HTML Container

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

Mount the Checkout Widget

const checkout = SubscriptionFlow.mount("#sf-checkout", {
    checkoutUrl:
    "https://<tenant>.subscriptionflow.com/en/hosted-page/<PAGE_ID>"
});

Please follow the screenshot below to find the <PAGE_ID>

image (10).png

setFields()

Prefill customer information before payment.

checkout.setFields({

    ai_firstName: "John",
    ai_lastName: "Doe",
    ai_email: "john@example.com",
    ai_phone: "+1123456789",

    ai_company: "SubscriptionFlow",

    ai_billing_address1: "Street 1",
    ai_billing_city: "New York",
    ai_billing_state: "NY",
    ai_billing_country: "US",
    ai_billing_zip: "10001",

    currency: "USD",

    coupon_code: "WELCOME10"

});

submit()

checkout.submit().then(function(result){

    console.log(result);

});

Events

checkout.on("ready", callback);

checkout.on("fieldsApplied", callback);

checkout.on("success", callback);

checkout.on("error", callback);

Complete Checkout Example

<!DOCTYPE html>
<html>

<head>
    <title>Embedded Checkout</title>
</head>

<body>

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

<button id="payNow">Pay Now</button>

<script src="https://<tenant>.subscriptionflow.com/modules/paymentsflow/js/embed.js"></script>

<script>

const checkout = SubscriptionFlow.mount("#sf-checkout",{

    checkoutUrl:"https://<tenant>.subscriptionflow.com/en/hosted-page/<PAGE_ID>"

});

checkout.on("ready",function(){

    checkout.setFields({

        ai_firstName:"John",

        ai_lastName:"Doe",

        ai_email:"john@example.com",

        ai_phone:"+1123456789",

        ai_billing_country:"US",

        coupon_code:"WELCOME10"

    });

});

document.getElementById("payNow").onclick=async function(){

    const result=await checkout.submit();

    if(result.status==="success"){

        if(result.redirectUrl){

            window.location=result.redirectUrl;

        }else{

            alert("Payment Successful");

        }

    }else{

        alert(result.message);

    }

};

</script>

</body>
</html>

Payment Method Update

The Payment Method Update widget allows existing customers to securely update their saved payment method.

HTML Container

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

Mount Widget

const widget = SubscriptionFlow.mount("#sf-update",{

    checkoutUrl:
    "https://<tenant>.subscriptionflow.com/en/public-checkout/payment-method-update/<CUSTOMER_ID>"

});

Please follow the screenshot below to find the <CUSTOMER_ID>

image (12).png

Events

widget.on("ready", callback);

widget.on("success", callback);

widget.on("error", callback);

Complete Payment Method Update Example

<!DOCTYPE html>
<html>

<head>
<title>Payment Method Update</title>
</head>

<body>

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

<button id="updateCard">
Update Payment Method
</button>

<script src="https://<tenant>.subscriptionflow.com/modules/paymentsflow/js/embed.js"></script>

<script>

const widget=SubscriptionFlow.mount("#sf-update",{

checkoutUrl:
"https://<tenant>.subscriptionflow.com/en/public-checkout/payment-method-update/<CUSTOMER_ID>"

});

widget.on("success",function(result){

alert("Payment Method Updated");

console.log(result);

});

document.getElementById("updateCard").onclick=async function(){

const result=await widget.submit();

console.log(result);

};

</script>

</body>
</html>

Customer Portal

The Customer Portal widget embeds the complete SubscriptionFlow customer portal inside your website.

Prerequisites

  • Whitelist your website in Portal Manager → InApp Portal.
  • Use a valid OAuth Client ID.
  • The customer must have Portal Access enabled.
  • Your website must use HTTPS.

HTML Container

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

Mount Portal

const portal = SubscriptionFlow.mountPortal("#sf-portal",{

    baseUrl:"https://<tenant>.subscriptionflow.com",

    clientId:"YOUR_CLIENT_ID",

    email:"customer@example.com",

    route:"root"

});

Portal Events

portal.on("ready", callback);

portal.on("error", callback);

portal.on("close", callback);

Complete Customer Portal Example

<!DOCTYPE html>
<html>

<head>
<title>Customer Portal</title>
</head>

<body>

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

<script src="https://<tenant>.subscriptionflow.com/modules/paymentsflow/js/embed.js"></script>

<script>

const portal = SubscriptionFlow.mountPortal("#sf-portal",{

baseUrl:"https://<tenant>.subscriptionflow.com",

clientId:"YOUR_CLIENT_ID",

email:"customer@example.com",

route:"root"

});

portal.on("ready",function(){

console.log("Portal Ready");

});

portal.on("error",function(error){

console.error(error);

});

portal.on("close",function(){

console.log("Portal Closed");

});

// portal.destroy();

</script>

</body>
</html>

Troubleshooting

IssueResolution
Portal does not loadVerify that your website URL is whitelisted in Portal Manager → InApp Portal.
Invalid Client IDVerify the OAuth Client ID exists and has not been revoked.
Customer cannot access the portalEnsure Portal Access is enabled for the customer.
Widget never loadsVerify the checkoutUrl points to a valid Hosted Payment Page, Public Checkout Page, or Payment Method Update URL.
Payment fails on productionEnsure your production website uses HTTPS.

Related Documentation

  • Hosted Payment Pages
  • Public Checkout Pages
  • Customer Portal
  • Portal Manager
  • API Authentication

Related articles

Comments

0 comments

Please sign in to leave a comment.