If you would prefer to create your own frontend checkout experience, we offer a React SDK for you to embed Sphere's payments logic into your own components. Check these examples for more details.

You can also just use Sphere's backend logic and create your own frontend by using the API directly.

Getting started

Assumptions: React ^16.0.0, Node.js, Solana.

Install the npm package.

npm install @spherelabs/react

yarn add @spherelabs/react

Let's take a look at a minimal example of a React App.

import {
  ConnectionProvider,
  WalletProvider,
} from "@solana/wallet-adapter-react";
import { useWallet } from "@solana/wallet-adapter-react";
import {
  WalletModalProvider,
} from "@solana/wallet-adapter-react-ui";
import { WalletMultiButton } from "@solana/wallet-adapter-react-ui";
import { SphereProvider } from "@spherelabs/react";
import { useSphere } from "@spherelabs/react";

// Bare-bones React app.
export default function App({
    children,
  }: {
    children: React.ReactNode;
  }) {
    return (
      <html lang="en">
        <Providers>
          <body>{children}</body>
        </Providers>
      </html>
    );
  }
  
// Wrap our app in the appropriate providers for wallet and Sphere functionality.
export default function Providers({ children }: { children: React.ReactNode }) {
  
    // Provide a Solana RPC provider URL endpoint to connect to the blockchain.
    const endpoint = "https://rpc.helius.xyz/?api-key=5b61f350-4c99-4f81-8331-246906ba53dc"
  
    return (
      <html lang="en">
        <ConnectionProvider endpoint={endpoint}>
          <WalletProvider wallets={[]} autoConnect>
            <WalletModalProvider>
              <SphereProvider
                paymentLinkId="paymentLink_6d19b52de8eb4aa69ce0310b5b561251"
              >
                <body>
                    <Component/>
                </body>
              </SphereProvider>
            </WalletModalProvider>
          </WalletProvider>
        </ConnectionProvider>
      </html>
    );
  }
  
// Example component that uses the SDK to create a proprietary frontend.
export default function Component() {
  
  const { connected } = useWallet()
  
  const { setLineItemQuantity, lineItems, pay, subtotal } =
    useSphere();
  if (!connected || !lineItems) {
    return (
      <main>
        <WalletMultiButton/>
      </main>
    );
  }
  
  return (
    <main>
      <div>
        Total: {subtotal?.rawAmountWithTaxAndFeesFormatted}
      </div>
      <input onChange={(e) => {
        setLineItemQuantity(parseInt(e.target.value), lineItems[0].id);
      }}>
      </input>
      <button
        onClick={async () => {
          const txId = await pay();
          console.log(txId);
        }}
      >
        Pay
      </button>
    </main>
  );
}

Connect to Blockchain - Standard Providers (Connection, Wallet, WalletModal)

You'll notice that this is a Solana example (EVM coming soon), which means that you'll need the standard providers wrapped around your app and an appropriate RPC endpoint to communicate with the blockchain.

Connect to Sphere - SphereProvider

Nested inside the standard providers is the <SphereProvider/>.

The <SphereProvider/> is how your frontend will communicate with our API.

You'll need to pass in the id of the payment method that you would like to embed the backend logic for into your frontend into this provider. Here, we used a payment link.

Component

We've made a minimal component to give you an example of how you might use the React SDK in your app.

Main Hook Variables

There are four main variables that the useSphere() hook gives back:

setLineItemsQuantity: function Adjusts the default quantity for a lineItem inside the lineItems field of the provided payment method.
- Allows your customers to choose the quantity of the products that they are purchasing.
- It is only relevant if the lineItem has quantityMutable set to true.
- It takes in two arguments:
  - 1. selectedQuantity: number the updated quantity that the customer has selected.
    2. selectedLineItem: string the id of the lineItem being adjusted.
lineItems: object Returns the lineItems field inside the provided payment method. Needed for reference when using setLineItemsQuantity() to allow your customers to adjust default quantity.
pay: function Builds a blockchain transaction that will appear to your users as a wallet approval in their browser. Returns the string ID of their transaction.
subtotal: object Contains information about fees related to the checkout.
- totalFeesFormatted: number Describes all platform fees.
- totalTaxFormatted: number Describes all included taxes.
- rawAmountWithTaxFormatted: number Describes total amount (for products) + taxes.
- rawAmountWithTaxAndFeesFormatted: number Describes total amount + taxes + platform fees.

Displaying total cost

As you'll notice, the component will render a <WalletMultiButton/> if there is no wallet connected, or the payment method that was passed in does not have any line items.

Otherwise, it will display the subtotal, including the total cost for products, taxes, and fees.

Formatted to decimals (base-10) instead of the default raw unit amounts for a given token (e.g., a total of 1 SOL = 1 instead of 1,000,000,000 and a total of 1 ETH = 1 instead of 10^e18).

Allowing your users to adjust quantity

There is an <input/> to demonstrate how users might select an updated quantity for a given line item.

It will call the setLineItemsQuantity() function onChange().

Embedding payment logic into a button

Last, there is a <button/> to demonstrate how you might embed the payments logic into a button.

The pay() function is called asynchronously, and will build the relevant transaction for you — meaning that your users will see an approval dialog appear in their browser's connected wallet.
There is also a console.log() of the returned transaction ID string for your reference.

And that's it! Congratulations, you've used the React SDK to create your own custom frontend checkout.

There are a wide variety of more complex use cases that can be built on-top of the example provided above. However, this should give you a good idea of what a minimal example of using the React SDK looks like.

If you're interested in learning more, we suggest checking out the example repo or the create your own frontend payments flow in-depth guide.