Virtual Accounts

Virtual accounts provide unique routing and account numbers under a customer's name, enabling seamless acceptance of wire transfers and ACH deposits. These deposits are directly on-ramped to a designated wallet address chosen by the customer.

Example use cases:

  1. Seamless Crypto Purchases: Simplify the process of buying cryptocurrency by enabling direct fiat deposits that are instantly converted and credited to a wallet.
  2. Streamlined Business Operations: Businesses can use virtual accounts to collect payments from clients in fiat and convert them into crypto for treasury management or operational needs.
  3. Proof of Ownership for Compliance: For individuals or businesses requiring documented proof of ownership, such as for regulatory compliance, having the virtual account under the customer's name ensures credibility and trust.

This feature ensures a seamless and personalized experience for customers.

How to Access Virtual Accounts

Note that Virtual Accounts are a standalone product with separate pricing. Contact the Sphere team to get started.

The Virtual Account object

The following is the json object representation of a Sphere virtualAccount.

Properties

    Name
    id
    Type
    string
    Description

    A unique identifier for the object.

    Name
    active
    Type
    boolean
    Description

    Whether the virtual account is active.

    Name
    depositInstructions
    Type
    object
    Description

    The deposit instructions for the virtual account.

    • Name
      currency
      Type
      string
      Description

      The currency of the virtual account.

    • Name
      bankName
      Type
      string
      Description

      The name of the bank associated with the virtual account.

    • Name
      bankAddress
      Type
      string
      Description

      The address of the bank associated with the virtual account.

    • Name
      bankAccountNumber
      Type
      string
      Description

      The account number of the bank associated with the virtual account.

    • Name
      bankRoutingNumber
      Type
      string
      Description

      The routing number of the bank associated with the virtual account.

    • Name
      bankBeneficiaryName
      Type
      string
      Description

      The name of the beneficiary of the bank associated with the virtual account.

    • Name
      bankBeneficiaryAddress
      Type
      string
      Description

      The address of the beneficiary of the bank associated with the virtual account.

    Name
    destination
    Type
    object
    Description

    The destination of the virtual account.

    • Name
      currency
      Type
      string
      Description

      Currency of the crypto received from sending funds to the virtual account.

    • Name
      walletAddress
      Type
      string
      Description

      The wallet address to which funds are sent.

    • Name
      network
      Type
      string
      Description

      The crypto network to which funds are sent.

    Name
    updated
    Type
    string
    Description

    Datetime at which the account was last updated.

    Name
    created
    Type
    string
    Description

    Datetime at which the account was created.

Virtual Account Object

{
  "id": "virtualAccount_d5e591a16b1849a1b7596fd5b663cd83",
  "active": true,
  "depositInstructions": {
    "currency": "usd",
    "bankName": "Lead Bank",
    "bankAddress": "1801 Main St., Kansas City, MO 64108",
    "bankAccountNumber": "111111111111",
    "bankRoutingNumber": "222222222",
    "bankBeneficiaryName": "JOHN DOE",
    "bankBeneficiaryAddress": "Lala Land Road 123, Chicago, IL 60606"
  },
  "destination": {
      "currency": "usdt",
      "walletAddress": "0xc257274276a4e539741ca11b590b9447b26a8051",
      "network": "ethereum"
  },
  "created": "2025-01-03T08:19:25.234Z",
  "updated": "2025-01-03T08:47:43.366Z"
}
POST/v1/customer/:customerId/virtualAccount

Create a virtual account

Parameters

    Name
    destinationCurrency
    Type
    string
    Description

    The currency of the crypto received from sending funds to the virtual account. Can be either usdt or usdc.

    Name
    network
    Type
    string
    Description

    The crypto network to which funds are sent. Can be either ethereum, sol, polygon, base, arbitrum, or avalanche.

    Name
    walletAddress
    Type
    string
    Description

    The wallet address to which funds are sent.

Request

POST
/v1/customer/:customerId/virtualAccount
curl https://api.spherepay.co/v1/customer/:customerId/virtualAccount \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "destinationCurrency": "usdt",
    "network": "ethereum",
    "walletAddress": "0xc257274276a4e539741ca11b590b9447b26a8051"
  }'

Response

{
  "id": "virtualAccount_d5e591a16b1849a1b7596fd5b663cd83",
  "active": true,
  "depositInstructions": {
    "currency": "usd",
    "bankName": "Lead Bank",
    "bankAddress": "1801 Main St., Kansas City, MO 64108",
    "bankAccountNumber": "111111111111",
    "bankRoutingNumber": "222222222",
    "bankBeneficiaryName": "JOHN DOE",
    "bankBeneficiaryAddress": "Lala Land Road 123, Chicago, IL 60606"
  },
  "destination": {
    "currency": "usdt",
    "walletAddress": "0xc257274276a4e539741ca11b590b9447b26a8051",
    "network": "ethereum"
  },
  "created": "2025-01-03T08:19:25.234Z",
  "updated": "2025-01-03T08:47:43.366Z"
}
GET/v1/customer/:customerId/virtualAccount/:id

Retrieve a virtual account

Request

GET
/v1/customer/:customerId/virtualAccount/:id
curl https://api.spherepay.co/v1/customer/:customerId/virtualAccount/virtualAccount_d5e591a16b1849a1b7596fd5b663cd83 \
  -H "Authorization: Bearer {token}"

Response

{
  "id": "virtualAccount_d5e591a16b1849a1b7596fd5b663cd83",
  "active": true,
  "depositInstructions": {
    "currency": "usd",
    "bankName": "Lead Bank",
    "bankAddress": "1801 Main St., Kansas City, MO 64108",
    "bankAccountNumber": "111111111111",
    "bankRoutingNumber": "222222222",
    "bankBeneficiaryName": "JOHN DOE",
    "bankBeneficiaryAddress": "Lala Land Road 123, Chicago, IL 60606"
  },
  "destination": {
    "currency": "usdt",
    "walletAddress": "0xc257274276a4e539741ca11b590b9447b26a8051",
    "network": "ethereum"
  },
  "created": "2025-01-03T08:19:25.234Z",
  "updated": "2025-01-03T08:47:43.366Z"
}
GET/v1/customer/:customerId/virtualAccount

List virtual accounts

This endpoint allows you to retrieve a paginated list of all your virtual accounts. By default, a maximum of ten virtual accounts are shown per page.

Parameters

    Name
    limit
    Type
    number
    Description

    Limit the number of bank accounts returned. The maximum value per query is 200. Defaults to 25.

    Name
    startDate
    Type
    string
    Description

    The start datetime of the bank accounts to retrieve.

    Name
    endDate
    Type
    string
    Description

    The end datetime of the bank accounts to retrieve.

Request

GET
/v1/customer/:customerId/virtualAccount
curl -G https://api.spherepay.co/v1/customer/:customerId/virtualAccount \
  -H "Authorization: Bearer {token}" \
  -d limit=2

Response

[
    {
        "id": "virtualAccount_341d1ac9820d4f478abc4c91c85c3d0a",
        "active": true,
        "depositInstructions": {
            "currency": "usd",
            "bankName": "Lead Bank",
            "bankAddress": "1801 Main St., Kansas City, MO 64108",
            "bankAccountNumber": "111111111111",
            "bankRoutingNumber": "222222222",
            "bankBeneficiaryName": "JOHN DOE",
            "bankBeneficiaryAddress": "Lala Land Road 123, Chicago, IL 60606"
        },
        "destination": {
            "currency": "usdt",
            "walletAddress": "0xc257274276a4e539741ca11b590b9447b26a8051",
            "network": "ethereum"
        },
        "created": "2025-01-03T08:28:00.738Z",
        "updated": "2025-01-03T08:33:59.750Z"
    },
    {
        "id": "virtualAccount_7ad88e9377424d05bb144034d82f29ef",
        "active": false,
        "depositInstructions": {
            "currency": "usd",
            "bankName": "Lead Bank",
            "bankAddress": "1801 Main St., Kansas City, MO 64108",
            "bankAccountNumber": "444444444444",
            "bankRoutingNumber": "333333333",
            "bankBeneficiaryName": "JOHN DOE",
            "bankBeneficiaryAddress": "Lala Land Road 123, Chicago, IL 60606"
        },
        "destination": {
            "currency": "usdc",
            "walletAddress": "0xc257274276a4e539741ca11b590b9447b26a8051",
            "network": "ethereum"
        },
        "created": "2025-01-03T09:05:11.483Z",
        "updated": "2025-01-03T09:05:45.249Z"
    }
]
PATCH/v1/customer/:customerId/virtualAccount/:id

Update a virtual account

Parameters

    Name
    destinationCurrency
    Type
    string
    Description

    The currency of the crypto received from sending funds to the virtual account. Can be either usdt or usdc.

    Name
    network
    Type
    string
    Description

    The crypto network to which funds are sent. Can be either ethereum, sol, polygon, base, arbitrum, or avalanche.

    Name
    walletAddress
    Type
    string
    Description

    The wallet address to which funds are sent.

Request

PATCH
/v1/customer/:customerId/virtualAccount/:id
curl https://api.spherepay.co/v1/customer/:customerId/virtualAccount/:id \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "destinationCurrency": "usdt",
    "network": "ethereum",
    "walletAddress": "0xc257274276a4e539741ca11b590b9447b26a8051"
  }'

Response

{
  "id": "virtualAccount_d5e591a16b1849a1b7596fd5b663cd83",
  "active": true,
  "depositInstructions": {
    "currency": "usd",
    "bankName": "Lead Bank",
    "bankAddress": "1801 Main St., Kansas City, MO 64108",
    "bankAccountNumber": "111111111111",
    "bankRoutingNumber": "222222222",
    "bankBeneficiaryName": "JOHN DOE",
    "bankBeneficiaryAddress": "Lala Land Road 123, Chicago, IL 60606"
  },
  "destination": {
    "currency": "usdt",
    "walletAddress": "0xc257274276a4e539741ca11b590b9447b26a8051",
    "network": "ethereum"
  },
  "created": "2025-01-03T08:19:25.234Z",
  "updated": "2025-01-03T08:47:43.366Z"
}
PATCH/v1/customer/:customerId/virtualAccount/:id/deactivate

Deactivate a virtual account

This endpoint allows you to deactivate a virtual account.

Request

PATCH
/v1/customer/:customerId/virtualAccount/:id/deactivate
curl https://api.spherepay.co/v1/customer/:customerId/virtualAccount/:id/deactivate \
  -H "Authorization: Bearer {token}"

Response

{
  "id": "virtualAccount_d5e591a16b1849a1b7596fd5b663cd83",
  "active": false,
  "depositInstructions": {
    "currency": "usd",
    "bankName": "Lead Bank",
    "bankAddress": "1801 Main St., Kansas City, MO 64108",
    "bankAccountNumber": "111111111111",
    "bankRoutingNumber": "222222222",
    "bankBeneficiaryName": "JOHN DOE",
    "bankBeneficiaryAddress": "Lala Land Road 123, Chicago, IL 60606"
  },
  "destination": {
    "currency": "usdt",
    "walletAddress": "0xc257274276a4e539741ca11b590b9447b26a8051",
    "network": "ethereum"
  },
  "created": "2025-01-03T08:19:25.234Z",
  "updated": "2025-01-03T08:47:43.366Z"
}
PATCH/v1/customer/:customerId/virtualAccount/:id/reactivate

Reactivate a virtual account

This endpoint allows you to reactivate a virtual account.

Request

PATCH
/v1/customer/:customerId/virtualAccount/:id/reactivate
curl https://api.spherepay.co/v1/customer/:customerId/virtualAccount/:id/reactivate \
  -H "Authorization: Bearer {token}"

Response

{
  "id": "virtualAccount_d5e591a16b1849a1b7596fd5b663cd83",
  "active": false,
  "depositInstructions": {
    "currency": "usd",
    "bankName": "Lead Bank",
    "bankAddress": "1801 Main St., Kansas City, MO 64108",
    "bankAccountNumber": "111111111111",
    "bankRoutingNumber": "222222222",
    "bankBeneficiaryName": "JOHN DOE",
    "bankBeneficiaryAddress": "Lala Land Road 123, Chicago, IL 60606"
  },
  "destination": {
    "currency": "usdt",
    "walletAddress": "0xc257274276a4e539741ca11b590b9447b26a8051",
    "network": "ethereum"
  },
  "created": "2025-01-03T08:19:25.234Z",
  "updated": "2025-01-03T08:47:43.366Z"
}

Was this page helpful?