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?