Set Up the SpherePay Ramp Widget

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

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>

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>

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

Property	Type	Required	Description
`containerId`	string	Yes	The `id` of the HTML element where the widget mounts.
`applicationId`	string	Yes	Your Merchant Application ID from the SpherePay Settings page.
`theme`	object	No	Customizes the widget’s colors, border radius, and logo. See Theming.
`debug`	boolean	No	Enables debug mode for inspecting widget behavior. Disable before production.
`customerSupport`	string	No	URL or email to surface as a customer support contact inside the widget.
`allowKyb`	string	No	Controls 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

Customize the appearance — apply colors, border radius, and a custom logo to match your brand

Introduction

Get Started

Set Up the SpherePay Ramp Widget

Prerequisites

Setup

Full example

RampWidget constructor properties

Debug mode

Next steps

​Prerequisites

​Setup

​Full example

​RampWidget constructor properties

​Debug mode

​Next steps

Prerequisites

Setup

Full example

RampWidget constructor properties

Debug mode

Next steps