Project type: Developer Tooling

Jump to Content[v1.0
Log InMoon (Dark Mode)Sun (Light Mode)v1.0[API EndpointsIntroductionSearchJUMP TO## Sphere API
+ Create a productpost
+ Retrieve a productget
+ Update a productpost
+ Delete a productdelete
+ List all productsget
+ Create a pricepost
+ Retrieve a priceget
+ List all pricesget
+ Creates a payment linkpost
+ Retrieve a payment linkget
+ Update a payment linkpost
+ Delete a payment linkdelete
+ List all payment linksget
+ Retrieve a subscriptionget
+ List all subscriptionsget
+ Retrieve a paymentget
+ List all paymentsget
+ Create a webhookpost
+ Retrieve a webhookget
+ Update a webhookpost
+ Delete a webhookdelete
+ List all webhooksget
+ Retrieve an eventget
+ List all eventsget
+ Create a walletpost
+ Delete a walletdelete
+ List all walletsget
+ Create a couponpost
+ Retrieve a couponget
+ Update a couponpost
+ List all couponsget
+ Create a promotion codepost
+ Retrieve a promotion codeget
+ Update a promotion codepost
+ Delete a promotion codedelete
+ List all promotion codesget
+ Create a customerpost
+ Retrieve a customerget
+ List all customersget
+ Create a usage recordpost
+ List all usage records for a subscription itemget
+ Create a tax ratepost
+ Retrieve a tax rateget
+ Update a tax ratepost
+ Delete a tax ratedelete
+ List all tax ratesget
+ Retrieve a tax categoryget
+ List all tax categoriesget
+ Create a new bank accountpost
+ Retrieve a bank accountget
+ Delete a bank accountdelete
+ List all bank accountsget
+ Create a payoutpost
+ Retrieve a payoutget
+ Delete a payoutdelete
+ List all payoutsget
JUMP TO## Sphere API
+ Create a productpost
+ Retrieve a productget
+ Update a productpost
+ Delete a productdelete
+ List all productsget
+ Create a pricepost
+ Retrieve a priceget
+ List all pricesget
+ Creates a payment linkpost
+ Retrieve a payment linkget
+ Update a payment linkpost
+ Delete a payment linkdelete
+ List all payment linksget
+ Retrieve a subscriptionget
+ List all subscriptionsget
+ Retrieve a paymentget
+ List all paymentsget
+ Create a webhookpost
+ Retrieve a webhookget
+ Update a webhookpost
+ Delete a webhookdelete
+ List all webhooksget
+ Retrieve an eventget
+ List all eventsget
+ Create a walletpost
+ Delete a walletdelete
+ List all walletsget
+ Create a couponpost
+ Retrieve a couponget
+ Update a couponpost
+ List all couponsget
+ Create a promotion codepost
+ Retrieve a promotion codeget
+ Update a promotion codepost
+ Delete a promotion codedelete
+ List all promotion codesget
+ Create a customerpost
+ Retrieve a customerget
+ List all customersget
+ Create a usage recordpost
+ List all usage records for a subscription itemget
+ Create a tax ratepost
+ Retrieve a tax rateget
+ Update a tax ratepost
+ Delete a tax ratedelete
+ List all tax ratesget
+ Retrieve a tax categoryget
+ List all tax categoriesget
+ Create a new bank accountpost
+ Retrieve a bank accountget
+ Delete a bank accountdelete
+ List all bank accountsget
+ Create a payoutpost
+ Retrieve a payoutget
+ Delete a payoutdelete
+ List all payoutsget
Sphere is a payments API for digital currencies.
Sphere's mission is to accelerate the development of digital currencies.
To enable people from around the world to transact on cheaper, faster, and more accessible payment rails, we've begun with stablecoins and other digital currencies on decentralized networks.
Sphere provides an end-to-end payments experience — from on-ramp, to multi-chain and fiat transactions, to off-ramp — with best-in-class compliance, accounting, taxes, tooling, and billing reconciliation.
0.3% flat fee on all payments, excluding network fees (wire, gas, etc.) which we pass at cost.
We support one-time and recurring billing through payment links and subscriptions.
You have the flexibility to create your own frontend and UX, or use our pre-built checkout pages.
For subscriptions, you may choose between:
1. **Escrowed**, where funds are locked up and periodically withdrawn from (traditional).
2. **Escrowless**, where funds are automatically withdrawn from your customer's wallet each billing period.
Subscriptions don't require wrapping and unwrapping of tokens.
We support a variety of pricing models: including flat, per-seat, volume, graduated, and customer chooses.
Automated Invoices will be rolled out in Q1 2024.
Smart contracts are natively held on Solana and Ethereum. *L2s, and side-chains coming soon.*
# How it works
Sphere uses three core objects for payments:
1. **`product`** — the goods and services you're selling.
2. **`price`** — the cost, defined by amount and currency, of those products.
3. **`paymentLink`** or **`invoice`** — the payment method for a given set of product and price.
Fundamentally, you as the developer will:
1. Create a `product`.
2. Create and attach a `price` to your `product`.
3. Create a `paymentLink` or `invoice` and attach them to a given set of product and price.
4. The API will respond with a `url` for a pre-built checkout to redirect customers to, or build your own.
5. A `payment` object will be auto-generated when a customer tries to pay.
6. Create a `webhook` and listen for events on the `payment` object to carry out your business logic.
And that's it! Our guides give more details on specific examples and more complex use cases.
A `payment` object is auto-generated each time a customer tries to pay for one of your products through a payment method — whether one-time vs. recurring, or via payment link vs. invoice.
It contains key information about the purchase, such as the customer, transaction, and involved line items, for you to consume on your backend and apply the appropriate business logic upon a purchase.
`subscription` objects are auto-generated when your customers purchase products with a recurring price. Developers do not need to create `subscription` objects on their own.
This object contains useful information about the subscription, such as the remaining number of billing periods, amounts billed, and the start-and-end date of the current period.
At the end of each billing period, the `subscription` objects are billed by Sphere, and `payment` objects are created to record the recurring withdrawals from either the escrow account or customer wallet address.
If you are using metered billing, then you will need to submit usage records to bill for usage.
Webhooks are available for you to listen to a wide selection of events. For example, you may listen to the `payment.successful` event to credit a customer on your backend after a successful purchase.
If there is additional information you'd like to include in a given object, for your own reference or to use later elsewhere, we provide a `meta` field for storing arbitrary JSON in most of our objects.
Some use-cases could be to include your own pre-existing `id` tags for reconciliation purposes, or to temporarily reference during a user flow instead of creating a new data model inside of your database.
### Real-Time Price Updates
Sphere uses the Pyth oracle network to provide real-time updated price data to our smart contracts across all major supported chains. Whenever one of our programs that you invoke via API, or in select cases directly via cross-smart contract call, requires an exchange rate (e.g., to correctly price HNT/USDC), Pyth's streamed updates guarantee best pricing.
* Table of Contents
+ How it works