Quickstart: On-Ramp

How to perform On-Ramping in SphereOne

SphereOne has integrated with some On-Ramp Providers, made available in the SphereOne Wallet site. Currently ready and available On-Ramp Providers are:

More On-Ramp Providers are still being integrated with SphereOne and will be made available in the near-future.

With the currently available On-Ramp Providers in SphereOne, we will discuss where and how to do On-Ramping.

On-Ramping Options

In the SphereOne Wallet site, you can find the available On-Ramp Providers on the 'Buy' screen, which will redirect you to the 'CheckoutOnramp' URL, as shown in the screenshots below. You can also access directly to the SphereOne Checkout site

Note: You can update your location by clicking on the top right corner of the site.

Note: You can update your location by clicking on the top right corner of the site.

SphereOne considers the user's geographical location when determining which On-Ramp Providers to display. Why? Because certain On-Ramp Providers can only support specific countries, meaning that not all countries are supported. However, as SphereOne continues to integrate with more On-Ramp Providers in the near future, more countries will have the option for on-ramping.


Start On-Ramping

As mentioned earlier, users can access the list of available Payment methods on the 'Checkout Onramp' screen. The available On-Ramp Providers may vary based on the users' geographical locations.

As a merchant, you have the ability to customize the on-ramping process for your users. One way you can do this is by adding the user's wallet to your platform if you want the funds to arrive there. Additionally, you can limit the scope of available chains to the chain where your platform is located and choose a default token. These changes can be made by passing parameters to either the SphereOne SphereOne Checkout site or SphereOne Wallet site. the parameters available are chain & token (they go together) and wallet. For example: https://checkout.sphereone.xyz/?chain=DFK&token=JEWEL&wallet=0xc0644041E08718F388100DbfcfA16c779d1Bf46c

Step 1: Select the Desired Chain and Currencies

To start, we will choose the blockchain we want to use on the left side of the screen. While SphereOne has support for a lot of blockchains and tokens, the On-Ramp Providers have limited support for certain blockchains or locations. As a result, if a user desires a blockchain that's not supported by the selected On-Ramp Provider, for now, the user will be stuck and need to choose another provider.

We will select 'POLYGON' as our desired blockchain. Next, we will choose the token.

Like the limitations for blockchain support by an On-Ramp Provider, only certain tokens are supported per selected blockchain. More will be elaborated in next sections on how SphereOne can help alleviate.

For what's supported and offered by the selected On-Ramp Provider, users can proceed to select the desired token. Let's go with 'MATIC' and specify the amount as 3.

There is a lowest buying limit that users need to be aware of. This means, users need to buy at or above a certain amount of tokens for the On-Ramp Providers to accept for processing the transaction. The lowest buying limit will differ based on the selected On-Ramp Provider.

After a few seconds, we can see the total amount in USD. Additionally, we can click the 'Show payment details' button to access extra information about the payment

In this example, the user is attempting to on-ramp 3 MATIC tokens in Polygon chain. But when 3 MATIC tokens are converted into USD, it only amounts to 2.54 USD, resulting in the error message at the left side of the screen, as shown in the screenshot below.

In order to proceed, SphereOne will create an order for the minimum amount for that specific payment.

In order to proceed, SphereOne will create an order for the minimum amount for that specific payment.

Step 2: Select On-Ramping Options

For this example, let's assume a user is located in the United States and has chosen the 'POLYGON' blockchain with the 'MATIC' token, specifying an amount of 50. Initially, they will be presented with various payment methods to choose from as available options. In this case, we will select 'Card' as the desired payment method and then proceed to click 'Buy'.

Onramper provider example

Onramper provider example

The user is now expected to see content similar to the one shown above. In this example, we will use the 'Onramper' provider. This provider allows you to choose between different options, but by default, it will offer the best possible payment.

Please note that the default option may vary depending on the available provider and the user's location_For now, Payment Currency is available in other currencies, but SphereOne would prefer to remain with US Dollar_s.


Token On-Ramp

As mentioned above, if users try to on-ramp a token that's not supported by an On-Ramp Provider, then users will be stuck and choose a different available On-Ramp Provider.

SphereOne implemented Token On-Ramping, where SphereOne would allow users to first on-ramp to a different token on the same blockchain that users have originally selected. Users would then proceed to on-ramp to the different token, and once on-ramping is complete, SphereOne will perform a token swap to convert the on-ramped token to the desired token.

However, this solution has currently and only been implemented for one token - PZP. Even then, the solution has some limitations.

Some limitations are:

  • The desired token needs to be on a blockchain that's supported by the selected On-Ramp Provider.
  • Some blockchain may not be available in all the countries that the On-Ramp Provider supports.
  • The current implementation isn't a smooth process for users with little knowledge in crypto.

But to perform Token On-Ramping, which is only implemented for the PZP token on the Binance blockchain, users would need to be outside of the United States, and use Banxa as the selected On-Ramp Provider. There seems to be some support issues for Binance blockchain in the United States. And amongst the current available On-Ramp Providers in SphereOne, only Banxa offer support for Binance blockchain in other countries but the United States.

To proceed with the PZP onramp, the merchant needs to create a charge for PZP first and share the paymentUrl link with the user. If the user has funds (as in the following example), it will be swapped to the destination; otherwise, the user will be prompted to onramp the 'USDC' token with a provided payment method, which will later be converted to PZP.

NOTE: This is a temporary workaround while this new feature is being updated in the checkout process.

curl --location 'https://https://api-g2eggt3ika-uc.a.run.app/createCharge' \
--header 'Content-Type: application/json' \
--header 'x-api-key: your-api-key' \
--data '{
    "isTest": false,
    "chargeData": {
        "symbol": "PZP",
        "chain": "BINANCE",
        "successUrl": "https://sphereone.xyz/",
        "cancelUrl": "https://sphereone.xyz/consumer",
        "tokenAddress": "0x6ad9E9c098a45B2B41b519119C31c3DcB02ACcB2",
        "items": [
            {
                "name": "PZP",
                "image": "https://bscscan.com/token/images/playzap_32.png?=v82",
                "amount": 10
                "quantity": 1
            }
        ],
        "amount": 10 // the amount of tokens that the final wallet should receive
        "toAddress": "0x999f704ba8e24BB190a382783A78BE62C4ae132c" // the wallet where you need the tokens to be received
    },
    "isDirectTransfer":true // required for a direct transfer
    }
}'

This charge will return a response like this:

{
    "data": {
        "paymentUrl": "https://sphereonetesting.page.link/1suqahkZSKg2L3p7A",
        "chargeId": "iJHxe2FHaKZOGP9lrqmv"
    },
    "error": null
}

Now, when the user enters the paymentUrl, they will see something similar to the image below:

After this payment is completed, the user will be able to track the status of the transaction in the 'Activity' tab. Once the tokens arrive, the user will be able to see them on the 'Home' screen token list.

Onramper provider example

Onramp to user wallet

If you want to facilitate onramps to your users wallets in the app you're developing we bring you two options. One is opening our onramp website and passing down as query parameters wallet and wallet_label like this: https://checkout.sphereone.xyz/?wallet=0xB448eD138e0394e27DA59a3E37691D3358568A23&wallet_label=SphereOnewhich would allow a more flexible onramp.

Or create a charge with toAddress like this:

curl --location '{base url}/createCharge' \
--header 'x-api-key: {your api key}' \
--header 'Content-Type: application/json' \
--data '
{
	"isTest": false,
    "chargeData": {
        "symbol": "PZP",
        "chain": "BINANCE",
        "successUrl": "https://sphereone.xyz/",
        "cancelUrl": "https://sphereone.xyz/consumer",
        "tokenAddress": "0x6ad9E9c098a45B2B41b519119C31c3DcB02ACcB2", 
        "toAddress": "0xB448eD138e0394e27DA59a3E37691D3358568A23",
        "items": [
            {
                "amount": 100,
                "image": "https://images.esellerpro.com/3698/I/25/0008557_wenaas-chef-t-shirt-crew-neck-cotton-white.jpeg",
                "name": "SomeGame 1 year game-pass",
                "quantity": 1
            }
        ]
    }
}'

where the wallet label will be your merchant account business name.


Whatโ€™s Next

Get more information about charges in Quickstart: Charges