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.

Getting started

install the npm package.

npm install @spherelabs/react

Now, 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";
export default function App({
    children,
  }: {
    children: React.ReactNode;
  }) {
    return (
      <html lang="en">
        <Providers>
          <body>{children}</body>
        </Providers>
      </html>
    );
  }
export default function Providers({ children }: { children: React.ReactNode }) {
    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>
    );
  }
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 to communicate with the blockchain.

Connect to Sphere - SphereProvider

However, 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.

Component

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

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.

As you'll notice, the component will return 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).

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().

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!

There are a wide variety of more complex use cases that can be built on-top of the example provided above, but 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 React tutorial.