Get Started

Introduction

Learn how to embed a pre-built transfer user interface in your website to accept on/off ramps from your customers. We'll walk you through using our Ramp Widget solution, which manages the on/off ramp process.

Overview

SphereRamp simplifies the process of adding Sphere's comprehensive feature set to merchant applications. It provides everything needed right away, making the setup process effortless for engineers and eliminating the need for direct API connections.

Additionally, SphereRamp takes care of regulatory, security, and privacy concerns on behalf of the merchants.

Everything happens within the widget and Sphere's infrastructure, providing a secure and compliant service environment.

How it works

SphereRamp is hosted on a CDN as a JavaScript bundle.

Installation comes down to initializing the widget within your app adding the associated HTML element ID to the target element.

The following quickstart will show you everything you need to integrate.

Before you start

Make sure you have an account with SpherePay.

Visit the Settings page and copy the Merchant Application Id

Live Testing

Important

Although designed for experimentation, the SphereRamp widget loaded under the special /ramp route is still connected to our production environment.

You can experiment with SphereRamp without writing any code. Just visit the RampDemo page and sign up for an account where you can

You can even enable the Debug Mode by adding debug=true as an extra parameter.

Setup

Import the SphereRamp script into your application.

Add a script tag that points to the SphereRamp's bundled source code URL.

Ensure you have a root HTML element in place for SphereRamp to mount on.

<html>
  <head>
    <script type="module" crossorigin src="https://spherepay.co/packages/sphere-ramp/index.js"></script>
  </head>
  <body>
    <!-- ... Your App Code ... -->
    <div id="container"></div>
    <!-- ... Your App Code ... -->
  </body>
</html>

Assign an onload property to the script tag to call a function that initializes the widget.

<script
  type="module"
  crossorigin
  src="https://spherepay.co/packages/sphere-ramp/index.js" // [!code highlight]
  onload="initSphereRamp()"
></script>

Implement the initializer function.

function initSphereRamp() {
  new SphereRamp({
    containerId: 'container',
    applicationId: 'YOUR_APPLICATION_ID',
  })
}

SphereRamp Properties

The SphereRamp constructor accepts the following properties:

Prop	Type	Default
`allowKyb?`	`string`	`string`
`customerSupport?`	`string`	`string`
`debug?`	`boolean`	-
`theme?`	`object`	`{}`
`applicationId`	`string`	`string`
`containerId`	`string`	`string`

Debug mode

Only for Development

Ensure this option is disabled before deploying to production.

SphereRamp provides a debug mode for inspecting the application's behavior and exploring customization options.

To enable debug mode, pass debug: true to the configuration object of the SphereRamp instance:

new SphereRamp({
  // ...
  debug: true,
  // ...
})

You then should be able to see the debugger beneath the widget:

Debug Mode

new SphereRamp({
  theme: {
    // ...
  },
})

API Reference

/** The widget's primary color */
type ThemeColor =
  | 'default'
  | 'zinc'
  | 'slate'
  | 'stone'
  | 'gray'
  | 'neutral'
  | 'red'
  | 'rose'
  | 'orange'
  | 'green'
  | 'yellow'
  | 'violet'

/** The widget's border radius size */
type ThemeRadius = 'default' | 'none' | 'sm' | 'lg' | 'xl'

interface ThemeComponents {
  /**
   * The URL to a custom logo.
   * We suggest using 56px x 56px images due to height constraints, but wider images should also work fine.
   */
  logo: string
}

interface Theme {
  color: ThemeColor
  radius: ThemeRadius
  components: ThemeComponents
}

Example

const theme = {
  color: 'zinc',
  radius: 'none',
  components: {
    logo: '...',
  },
}

new SphereRamp({
  theme,
})

Changelog

This page details the changes to the Sphere Pay API.