Overview

Handling payments is easy with SphereOne. The first step in the payment workflow is to create a charge.

Creating a Charge

Make sure to have your API Key/Test API Key ready for this step.

The intention of creating a charge is to setup a session where the customer understands what items are being purchased and the amount of cryptocurrency funds are necessary to purchase an item.

Create Charge API Reference

Example

The below examples show how to create a charge for a 1 year game pass to SomeGame that's valued in 11 MATIC and redirect the user to the SphereOne checkout.

curl --location 'https://api-olgsdff53q-uc.a.run.app/createCharge' \
--header 'Content-Type: application/json' \
--header 'x-api-key: your-api-key' \
--data '{
    "chargeData": {
        "symbol": "MATIC",
        "chain": "POLYGON",
        "successUrl": "https://yourwebsite.com/success",
        "cancelUrl": "https://yourwebsite.com/cancel",
        "tokenAddress": "0x0000000000000000000000000000000000000000", 
        "items": [
            {
                "amount": 11,
                "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
            }
        ]
    }
}'

const url = 'https://api-olgsdff53q-uc.a.run.app/createCharge';
const data = {
  chargeData: {
    symbol: 'MATIC',
    chain: 'POLYGON',
    successUrl: 'https://yourwebsite.com/success',
    cancelUrl: 'https://yourwebsite.com/cancel',
    tokenAddress: '0x0000000000000000000000000000000000000000',
    items: [
      {
        amount: 11,
        image: 'https://images.esellerpro.com/3698/I/25/0008557_wenaas-chef-t-shirt-crew-neck-cotton-white.jpeg',
        name: 'Sphereone 1 year game-pass',
        quantity: 1
      }
    ]
  }
};

fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
    'x-api-key': 'your-api-key'
  },
  body: JSON.stringify(data)
})
  .then(response => response.json())
  .then(json => {
    if (json.error) {
      console.error('Error:', json.error);
    } else {
      const paymentUrl = json.data.paymentUrl;
      console.log('Redirecting to:', paymentUrl);
      window.location.href = paymentUrl; // Redirect the user to the payment URL
    }
  })
  .catch(error => console.error('Error:', error));

import requests
import json

url = 'https://api-olgsdff53q-uc.a.run.app/createCharge'
data = {
    'chargeData': {
        'symbol': 'MATIC',
        'chain': 'POLYGON',
        'successUrl': 'https://yourwebsite.com/success',
        'cancelUrl': 'https://yourwebsite.com/cancel',
        'tokenAddress': '0x0000000000000000000000000000000000000000',
        'items': [
            {
                'amount': 11,
                'image': 'https://images.esellerpro.com/3698/I/25/0008557_wenaas-chef-t-shirt-crew-neck-cotton-white.jpeg',
                'name': 'Sphereone 1 year game-pass',
                'quantity': 1
            }
        ]
    }
}

headers = {'Content-Type': 'application/json','x-api-key': 'your-api-key' }

response = requests.post(url, headers=headers, data=json.dumps(data))

if response.status_code == 200:
    json_data = response.json()
    if 'error' in json_data and json_data['error']:
        print('Error:', json_data['error'])
    else:
        payment_url = json_data['data']['paymentUrl']
        print('Redirecting to:', payment_url)
        # Redirect the user to the payment URL, e.g., by updating the browser location
else:
    print('Error:', response.status_code, response.text)

<?php

$url = 'https://api-olgsdff53q-uc.a.run.app/createCharge';
$data = [
    'chargeData' => [
        'symbol' => 'MATIC',
        'chain' => 'POLYGON',
        'successUrl' => 'https://yourwebsite.com/success',
        'cancelUrl' => 'https://yourwebsite.com/cancel',
        'tokenAddress' => '0x0000000000000000000000000000000000000000',
        'items' => [
            [
                'amount' => 11,
                'image' => 'https://images.esellerpro.com/3698/I/25/0008557_wenaas-chef-t-shirt-crew-neck-cotton-white.jpeg',
                'name' => 'Sphereone 1 year game-pass',
                'quantity' => 1
            ]
        ]
    ]
];

$headers = [
    'Content-Type: application/json',
    'x-api-key': 'your-api-key'
];

$options = [
    'http' => [
        'method' => 'POST',
        'header' => implode("\r\n", $headers),
        'content' => json_encode($data),
    ]
];

$context = stream_context_create($options);
$response = file_get_contents($url, false, $context);

if ($response === false) {
    echo "Error: failed to send request";
} else {
    $json_data = json_decode($response, true);
    if (isset($json_data['error']) && $json_data['error']) {
        echo 'Error: ' . $json_data['error'];
    } else {
        $payment_url = $json_data['data']['paymentUrl'];
        echo 'Redirecting to: ' . $payment_url;
        // Redirect the user to the payment URL, e.g., by updating the browser location
    }
}
?>

Web SDK

Another option to create a charge to make a payment transaction within SphereOne is through the SphereOne WebSDK.

NOTE: If you haven't read the Quickstart: Login - Web SDK, please do so. The follow section assumes that you have successfully installed the SphereOne WebSDK and signed into SphereOne.

To create a charge in order to proceed with payments within SphereOne, you would need to create a charge object, which contains all the necessary information pertaining to the purchase such as the individual making the purchase, the item of the purchase, the total amount, etc.

To create a charge, we need to invoke the WebSDK's createCharge function.

// importing the initialized WebSDK
import { sphereoneSdk } from "your-imported-file";
// an enum class of Chains that SphereOne supports
import { SupportedChains } from "websdk";

// ...

const [chargeId, setChargeId] = useState("");
const [paymentLink, setPaymentLink] = useState("");

const createCharge = async () => {
  try {
    const charge = await sphereoneSdk.createCharge({
      chain: SupportedChains.SOLANA,
      symbol: "SOL",
      amount: 0.9, // total amount for entire charge
      tokenAddress: "So11111111111111111111111111111111111111112",
      successUrl: "https://your-website.com/success",
      cancelUrl: "https://your-website.com/cancel",
      items: [
        {
          name: "Your Item",
          image: "https://your-image-url.somewhere.com",
          amount: 0.9, // amount of the individual item
          quantity: 1
        }
      ]
    });
    setChargeId(charge.chargeId);
    setPaymentLink(charge.paymentUrl);
  } catch (e: any) {
    console.error(e);
  }
};

// ...

createCharge has a set of parameters that must be set. More info can be found here at SphereOne API references - Create Charge.

In the above code example, a charge is created for a purchase involving SOLANA. To create a successful charge, we must pass a list of items that users want to purchase, the tokenAddress for SOLANA, followed by successUrl and cancelUrl,

NOTE: It's a bit inconvenient right now, but more updates will come to make this easier and more convenient.

If the charge is successful, the response for charge in the above example, should be:

{
  chargeId: "a-charge-id",
  paymentUrl: "https://a-payment-link/a-charge-id"
}

What is absolutely needed is the chargeId returned by createCharge since that is the reference to the actual purchase that's going to be made.

Once the chargeId is retrieved or saved for later usage, you can continue with making payments in SphereOne WebSDK.

To read for integrating payments, please read Quickstart: Integrate Payments - WebSDK for further integrations.

Special case of create charge and pay - Direct transfer to wallet with SDK

In the case you want to create a charge to an external wallet (not your SphereOne wallet) you can use the isDirectTransfer field in the create charge endpoint or WebSDK.

The flag isDirectTransfer allows user to create a charge/transaction to send money to an external wallet that's not recovered within SphereOne's ecosystem.

This is a very specific use-case only for particular users or merchants that need to move funds from their SphereOne Wallets to another wallet that they personally owned.

They can provide a wallet address to the toAddress field in the chargeData, as shown in the example code below, which will dictate the destination of where the funds will be transferred to.

Thus, user would need to set the isDirectTransfer flag to true, and provide a desired wallet address to the toAddress for this operation to work.

const charge = await sphereoneSdk.createCharge({
  chargeData: {
    chain: SupportedChains.SOLANA,
    symbol: "SOL",
    tokenAddress: "So11111111111111111111111111111111111111112",
    successUrl: "https://your-website.com/success",
    cancelUrl: "https://your-website.com/cancel",
    items: [
      {
        name: "Your Item",
        image: "https://your-image-url.somewhere.com",
        amount: 0.9, // amount of the individual item
        quantity: 1
      }
    ],
    toAddress: "0x53107F751291E57120230EFb50B0B67Da7D5bDF2", // the wallet that will receive the tokens
    amount: 0.9 // amount of tokens you are sending
  },
  isDirectTransfer: true // isDirectTransfer: this means that you are sending the tokens to the toAddress and not to your wallet in SphereOne account
});

With this action you can create a charge with your merchant api key and send the tokens to any another wallet. To do so remember that you need a Product Api Key that is only for merchants that have completed our KYB.

Creating test charges with SDK

In the case you want to create a charge in Testnet with the WebSDK you need to use a test Api Key and use the following code:

const charge = await sphereoneSdk.createCharge({
  chargeData: {
    chain: SupportedChains.SOLANA,
    symbol: "SOL",
    tokenAddress: "So11111111111111111111111111111111111111112",
    successUrl: "https://your-website.com/success",
    cancelUrl: "https://your-website.com/cancel",
    items: [
      {
        name: "Your Item",
        image: "https://your-image-url.somewhere.com",
        amount: 0.9, // amount of the individual item
        quantity: 1
      }
    ],
    amount: 0.9 // amount of tokens you are sending
  },
  isTest: true // isTest: you can create a charge in testnet
});

When creating a Test Charge/Transaction, SphereOne only interacts with native tokens for a few chains. So, there are certain limitations to creating test charges.

Further testing with Test Charges can be viewed and interacted with, in the SphereOne Merchant Dashboard, in the merchant's settings.

Unity SDK

TBD

Unreal SDK

TBD