Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.spherepay.co/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through embedding the SpherePay Ramp Widget in your web application. The setup requires no package installation — you import a hosted script, add a container element, and initialize the widget with your application ID.

​
Prerequisites

  • A SpherePay merchant account. Request access if you do not have one.
  • Your Merchant Application ID from the Settings page of your SpherePay dashboard.

​
Setup

1

Add a container element to your HTML

Add a <div> element to your page where you want the widget to appear. Give it an ID you’ll reference during initialization.
<div id="container"></div>
2

Import the Ramp Widget script

Add a <script> tag in your <head> that points to the hosted Ramp Widget bundle. Set the onload attribute to call your initializer function once the script loads.
<script
  type="module"
  crossorigin
  src="https://spherepay.co/packages/sphere-ramp/index.js"
  onload="initSphereRamp()"
></script>
3

Implement the initializer function

Define initSphereRamp() in your JavaScript. Create a new RampWidget instance, passing your container ID and Merchant Application ID.
function initSphereRamp() {
  new RampWidget({
    containerId: 'container',
    applicationId: 'YOUR_APPLICATION_ID',
  })
}

​
Full example

Here is a minimal HTML page that embeds the Ramp Widget: 
<html>
  <head>
    <script
      type="module"
      crossorigin
      src="https://spherepay.co/packages/sphere-ramp/index.js"
      onload="initSphereRamp()"
    ></script>
    <script>
      function initSphereRamp() {
        new RampWidget({
          containerId: 'container',
          applicationId: 'YOUR_APPLICATION_ID',
        })
      }
    </script>
  </head>
  <body>
    <div id="container"></div>
  </body>
</html>

​
RampWidget constructor properties

PropertyTypeRequiredDescription
containerIdstringYesThe id of the HTML element where the widget mounts.
applicationIdstringYesYour Merchant Application ID from the SpherePay Settings page.
themeobjectNoCustomizes the widget’s colors, border radius, and logo. See Theming.
debugbooleanNoEnables debug mode for inspecting widget behavior. Disable before production.
customerSupportstringNoURL or email to surface as a customer support contact inside the widget.
allowKybstringNoControls whether business customer KYB onboarding is allowed in the widget.

​
Debug mode

Disable debug mode before deploying to production.
Debug mode lets you inspect the widget’s behavior and explore customization options. To enable it, pass debug: true to the constructor: 
function initSphereRamp() {
  new RampWidget({
    containerId: 'container',
    applicationId: 'YOUR_APPLICATION_ID',
    debug: true,
  })
}
You can also enable debug mode on any Ramp Widget page by appending ?debug=true to the URL.

​
Next steps

Last modified on May 12, 2026