Embedded payment management

Embedded Payment Management components enable your customers to manage their payment methods (add, update, and delete) without leaving your website. By keeping the entire experience on-page, you reduce friction, maintain brand consistency, and prevent the drop-off often associated with external redirects.

When a customer clicks an Update payment method link on your site, the component initializes securely. After the customer makes changes, FastSpring automatically updates the records associated with their subscription.

Step 1: Create and customize

Use the FastSpring app to generate, configure, and style your payment components.

Customize styling

Click anywhere on a component card to open the styling editor. The editor provides a side-by-side preview of your changes. The preview is a static example and may not match the exact interactive behavior of the live component on your site.

Step 2: Implementation

Once customized, you must integrate the component into your website. This process involves whitelisting your domain for security, adding the EPML library script, and initializing the session with the customer's authenticated data.

2.1 Whitelist your domain

For security, the component will only load on domains you have explicitly approved.

1. In the FastSpring app, go to Developer Tools > Payment Component. Locate the component card you want to whitelist.
2. Click Implement on your component card. The Implementation page opens.
3. In the Whitelist your domain text area, enter your domain(s) (e.g., https://www.example.com). Make sure to include https:// at the beginning.
4. Click Save.

2.2 Embed the script

Copy the EPML script from the Implementation page and paste it into the header or footer of your website.

<script src="https://epml.onfastspring.com/epml/epml.min.js"
        data-payment-component-id="your-unique-component-id"
        id="fsc-epml">
</script>

With the above script included, two methods (init and paymentManagementComponent) will be exposed in the fastspring.epml namespace.

2.3 Initialize the library

After the script loads, the fastspring.epml namespace exposes the init method. Call this method to authenticate the session.

// The parameter is the Authenticated Account Management URL
fastspring.epml.init('https://yourstore.onfastspring.com/account/{account_id}/authenticate');

How to get the URL: Use the Retrieve authenticated account management URL endpoint (/accounts/{account_id}/authenticate) to generate this link server-side.

2.4 Trigger the component

Add a subscription management link or button at an appropriate location on your site. Call the paymentManagementComponent method when the button is clicked. This method will open the embedded payment management component in a pop-up.

// Parameter 1: Subscription ID (Required)
// Parameter 2: ISO Language Code (Optional, defaults to 'en')
fastspring.epml.paymentManagementComponent('subscription-id-123', 'en');

2.5 Test the component

To test the component without processing real payments, initialize the library using a test-mode URL.

1. Generate the authenticated URL as described in Step 2.3.
2. Modify the URL by appending .test to your checkout subdomain.
   • Live: https://yourstore.onfastspring.com/...
   • Test: https://yourstore.test.onfastspring.com/...
3. Pass this test URL to the fastspring.epml.init() method.

This loads the component in test mode, allowing you to use FastSpring test card numbers to add and update payment methods.

Customer experience

The component allows customers to view a list of all saved payment methods. The method associated with the current subscription is marked as Default and appears at the top.

• Manage Existing: Customers can view and manage credit cards, PayPal, Amazon Pay, ACH, and SEPA accounts saved on file.

• Add New: Customers can add new Credit Cards (global), PayPal, and Amazon Pay accounts.

  Note: ACH and SEPA cannot be added as new methods here.

• Update Default: Customers can switch their default payment method. The new default will be charged at the next rebill.

  Note: ACH and SEPA cannot be set as default.

• Edit: Update details for Credit Cards and PayPal (ACH/SEPA/Amazon Pay cannot be edited).

• Delete: Remove unused methods. The current Default method cannot be deleted until a new default is selected.

FAQs