API Guide

Requirements

To successfully set up and use an Onramper Account, each customer must:

• Be registered via the Create Customer API
• Have accepted the Terms of Service (TOS)
• Have signed the Customer's Agreement (for business customers only)
• Have completed KYC/KYB verification
• Have an active customer status of approved

Virtual Account APIs

Create Virtual Account

For full request/response details, see the Create Virtual Account API Reference.

Request Example

{
  "customerId": "customer_1ab2c3d4",
  "sourceCurrency": "USD",
  "destinationCurrency": "USDC",
  "network": "ethereum",
  "walletAddress": "0x1234...abcd"
}

Response Example

{
  "id": "virtualAccount_987xyz654",
  "active": true,
  "fees": {
    "totalBpsRate": "20",
    "integratorFee": {
      "bpsRate": "10"
    },
    "platformFee": {
      "bpsRate": "10"
    }
  },
  "depositInstructions": {
    "currency": "USD",
    "bankName": "Bank of Example",
    "bankAccountNumber": "000123456789",
    "bankRoutingNumber": "1234567890",
    "bankBeneficiaryName": "John Doe",
    "bankBeneficiaryAddress": "123 Main St, Anytown, USA"
  },
  "destination": {
    "currency": "USDC",
    "walletAddress": "0x1234...abcd",
    "network": "ethereum"
  },
  "created": "2025-04-20T21:49:46.697Z",
  "updated": "2025-04-20T21:50:18.854Z"
}

Retrieve Virtual Account

For full request/response details, see the Get a Virtual Account API Reference.

Update Virtual Account

For full request/response details, see the Update Virtual Account API Reference.

List Virtual Accounts

For full request/response details, see the List Virtual Accounts API Reference.

Deactivate Virtual Account

For full request/response details, see the Deactivate Virtual Account API Reference.

Reactivate Virtual Account

For full request/response details, see the Reactivate Virtual Account API Reference.

Transaction Timing

Transfers to your virtual bank account are converted instantly once funds arrive, excluding the transfer time from the customer's bank to the virtual account itself.

Account Verification

When customers link their Virtual Account to another financial platform (e.g. a fintech app or payroll provider), they may need to verify ownership via:

• Micro-deposit verification — A small amount (< $1) is deposited and withdrawn to confirm ownership.
• Challenge deposit verification — One or more small deposits are made, and the customer must enter the exact amounts.

Notes:

• Deposits under $1 are always treated as verification, not payments or transfers.
• Virtual Accounts only — shared memo/static deposit flows do not support micro-deposit verification.
• Each attempt creates a micro-deposit event with amount, source bank details, and timestamp.

Security and Compliance

SpherePay's Virtual Accounts adhere to KYB and KYC verification protocols.

Additional Notes

• To check transfer status, poll transfers for a specific virtual account using the List Virtual Account Transfers endpoint.