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 individual customers.
• Creating and validating wallets and bank accounts for your customers.
• Orchestrating and executing transfers on behalf or on the behest of your customers.

1. Create a Customer

To create a transfer, customers must have their kycStatus and tosStatus approved.

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

The following curl requests demonstrate the process of creating individual customers. To create a business customer please use Create Customer API v1.

curl https://api.spherepay.co/v2/customer \
-H "Authorization: Bearer {token}" \
-H "Content-Type: multipart/formdata" \
-F "type=individual" \
-F "firstName=John" \
-F "lastName=Doe" \
-F "email=johndoe123@gmail.com" \
-F "phoneNumber=+12345678900" \
-F "address.line1=123 Main St" \
-F "address.city=San Francisco" \
-F "address.postalCode=94107" \
-F "address.state=CA" \
-F "address.country=USA" \
-F "dob.month=3" \
-F "dob.day=23" \
-F "dob.year=1990" \
-F "proofOfAddressDocument=@/path/to/proofOfAddressDocument.png" \
-F "identityDocumentFront=@/path/to/identityDocumentFront.png" \
-F "identityDocumentBack=@/path/to/identityDocumentBack.png"

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/v2/customer/{customer_id}/tos-link
\ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" \

The customer will be redirected to the TOS link to accept the terms of service and is required to do so before they can create a transfer.

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.

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

curl -X POST https://api.spherepay.co/v2/customer/{customer_id}/kyc-link \ -H
"Authorization: Bearer {token}" \ -H "Content-Type: application/json" \ 

After the customer has completed the KYC/B process, their kycStatus will be updated 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_id}",
    "network": "sol",
    "address": "{wallet_address}"
  }'

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_id}' \
--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/v2/customer/{customer_id}/bank-account \
    -H "Authorization: Bearer {token}" \
    -H "Content-Type: application/json" \
    -d '{
      "customer": "{customer_id}",
      "accountName": "Example bank account",
      "bankName": "Bank of America",
      "accountType": "checking",
      "accountNumber": "123456789",
      "routingNumber": "987654321"
  }'

In cases where transfers is refunded, the bank accounts associated 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/v2/customer/{customer_id}
/bank-account' \ -H 'Authorization: Bearer {token}' 

Alternatively, you can retrieve a specific bank account by specifying the id of the bank account. This is useful for displaying available bank accounts to your users or for administrative purposes.

The following curl request demonstrates how to retrieve a specific bank account:

curl --location 'https://api.spherepay.co/v2/customer/{customer_id}
/bank-account/{bank_account_id}' \ -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_id}",
    "amount": "100",
    "source": {
        "id": "{bank_account_id}",
        "network": "wire",
        "currency": "usd"
    },
    "destination": {
        "id": "{wallet_id}",
        "network": "sol",
        "currency": "usdc"
    }
}'

curl https://api.spherepay.co/v1/transfer \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "{customer_id}",
    "amount": "100",
    "source": {
        "id": "{wallet_id}",
        "network": "sol",
        "currency": "usdc"
    },
    "destination": {
        "id": "{bank_account_id}",
        "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.