Introduction

A transfer is the movement of funds from a source to a recipient. The transfer object will allow you to move money from bank accounts to wallets and vice versa.

The following guide will walk you through the process of:

• Initiating Sphere KYC/B for both business and individual customers.
• Creating and validating wallets and bank accounts for your customers.
• Orchestrating and executing transfers on behalf of your customers.

1. Create a Customer

Every transfer is created on behalf of a customer. To create a transfer, customers must have a kycStatus and tosStatus of approved. Requirements for KYB/C vary based on the type of the underlying customer.

To start onboarding you must first create a customer by specifying the type of customer, their operating residence address.country (ISO 3166-1) and address.state (ISO 3166-2 subdivision code).

The following curl requests demonstrate the process for both individual and business customers respectively.

curl https://api.spherepay.co/v1/customer \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "individual",
    "address": {
        "country": "USA",
        "state": "IL"
    }
}'

curl https://api.spherepay.co/v1/customer \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "business",
    "name": "Shape Co",
    "email": "shapeco@test.com"
  }'

2. Terms of Service

The Sphere Terms of Service process involves the generation of a unique tosLink for your customers.

To generate a Terms of Service link for your customer, use the following curl request.

curl -X POST https://api.spherepay.co/v1/customer/customer_8f86b648a14540a39498fe42112cf10e/tosLink \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{}'

When the customer has accepted Sphere's Terms of Service, their tosStatus will update to approved.

Terms of Service can be accepted at any time after customer creation.

3. Know Your Customer

The Sphere KYC/B process involves the generation of a unique kycLink url that you can use to onboard your customers.

KYC links yield a url that you can use send or redirect your customers to so that they can complete the KYC/B process. The Sphere KYB Links contains a more rigorous form for onboarding relative to KYC.

To generate a KYC link for your customer, use the following curl request.

curl -X POST https://api.spherepay.co/v1/customer/customer_8f86b648a14540a39498fe42112cf10e/kycLink \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{}'

After the customer has completed the KYC/B process, their kycStatus will update to approved.

4. Create a Wallet

Wallets can be owned by customers and are used to send or receive funds.

curl https://api.spherepay.co/v1/wallet \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "customer_8f86b648a14540a39498fe42112cf10e",
    "network": "sol",
    "address": "BTkpRfK8L5Yy7A8wimA4CXra2GhFxdSWK944Ap6dPKCu"
  }'

You can retrieve a list of wallets associated with a specific customer. This is useful for displaying available wallets to your users or for administrative purposes.

The following curl request demonstrates how to list wallets for a customer:

curl --location 'https://api.spherepay.co/v1/wallet?customer=customer_8f86b648a14540a39498fe42112cf10e' \
--H 'Authorization: Bearer {token}'

5. Create a Bank Account

Bank Accounts are owned by your customers and are used to send or receive funds.

All bank accounts are created with a status of pending. If validated successfully bank account will be updated to active.

The following curl request demonstrates the process for creating a bank account.

curl https://api.spherepay.co/v1/bankAccount \
    -H "Authorization: Bearer {token}" \
    -H "Content-Type: application/json" \
    -d '{
      "customer": "customer_8f86b648a14540a39498fe42112cf10e",
      "accountName": "Example bank account",
      "bankName": "Bank of America",
      "accountType": "checking",
      "accountNumber": "123456789",
      "routingNumber": "987654321"
  }'

In cases where bank accounts are associated with refunded transfers, they may be deactivated, with a status of inactive.

You can retrieve a list of bank accounts associated with a specific customer. This is useful for displaying available bank accounts to your users or for administrative purposes.

The following curl request demonstrates how to list bank accounts for a customer:

curl --location 'https://api.spherepay.co/v1/bankAccount?customer=customer_8f86b648a14540a39498fe42112cf10e' \
-H 'Authorization: Bearer {token}'

6. Create a Transfer

Finally, to move money between your customer's wallets and bank accounts, you can create an on-ramp or off-ramp transfer specifying the source and destination of the funds.

The following curl request demonstrates the process for creating on-ramp and off-ramp transfers respectively.

curl https://api.spherepay.co/v1/transfer \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "customer_8f86b648a14540a39498fe42112cf10e",
    "amount": "100",
    "source": {
        "id": "bankAccount_5a0b919989e440b6ad644fad8f7227b0",
        "network": "wire",
        "currency": "usd"
    },
    "destination": {
        "id": "wallet_96000cb13fd847658fdd295d7ec1b7e6",
        "network": "sol",
        "currency": "usdc"
    }
}'

curl https://api.spherepay.co/v1/transfer \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "customer_8f86b648a14540a39498fe42112cf10e",
    "amount": "100",
    "source": {
        "id": "wallet_96000cb13fd847658fdd295d7ec1b7e6",
        "network": "sol",
        "currency": "usdc"
    },
    "destination": {
        "id": "bankAccount_5a0b919989e440b6ad644fad8f7227b0",
        "network": "wire",
        "currency": "usd"
    }
}'

Transfers will be created with a status of pending. To complete the transfer, your customer must fund the source specified in the instructions field of the transfer.

In the case of an off-ramp transfer the instructions field will specifies a wallet address to fund. In the case of an on-ramp transfer the instructions field will specify the bank account to fund.

When the customer has funded their transfer it will transition to a status of processing and then succeeded on delivery.