Make Your First SpherePay API Call

This guide walks you through the complete sequence for your first SpherePay integration: create a customer, register a bank account and wallet, then execute an on-ramp transfer. By the end, you’ll have issued real API calls against every core resource in the SpherePay model. All requests go to the base URL: https://api.spherepay.co/

Prerequisites

You have an API key. If not, see Authentication.
You understand the integration model. If not, read How it works first.

Create a customer

Create an individual customer by sending a POST request to /v2/customer. Include the customer’s contact details and tax identification information.

curl -X POST https://api.spherepay.co/v2/customer \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "individual",
    "email": "jane.smith@example.com",
    "phone": "+14155550123",
    "address": {
      "line1": "233 South Wacker Drive",
      "line2": "Suite 4700",
      "city": "Chicago",
      "postalCode": "60606",
      "state": "IL",
      "country": "USA"
    },
    "personalInformation": {
      "taxIdentificationNumber": "123456789",
      "taxIdentificationNumberType": "ssn",
      "taxIdentificationNumberCountry": "USA"
    }
  }'

A successful response returns the newly created customer object with a system-generated id and a verificationProfiles array showing the KYC status as incomplete:

{
    "id": "customer_4fbb292cc6e447da8858e054d1937e7e",
    "email": "jane.smith@example.com",
    "phone": "+14155550123",
    "verificationProfiles": [
        {
            "name": "kyc_profile_a",
            "status": "incomplete",
            "criteria": {
                "complete": [],
                "pending": [],
                "required": [],
                "errors": []
            }
        }
    ],
    "createdAt": "2026-03-03T21:25:03.102Z",
    "updatedAt": "2026-03-03T21:25:03.102Z",
    "type": "individual"
}

The customer must complete KYC verification and reach an approved status before you can create a transfer on their behalf. Onboarding is a hard prerequisite for all transfers. See the Individual KYC Flow or Business KYB Flow for next steps.

Once your customer is KYC-approved, register the bank account that will serve as the fiat source for an on-ramp transfer. Send a POST request to /v2/bank-account with the customer ID and account details.

curl -X POST https://api.spherepay.co/v2/bank-account \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "customer_4fbb292cc6e447da8858e054d1937e7e",
    "bankName": "Chase",
    "accountName": "Jane Doe Checking",
    "accountOwner": {
      "accountHolderName": "Jane Doe",
      "address": {
        "line1": "233 South Wacker Drive",
        "city": "Chicago",
        "state": "IL",
        "postalCode": "60606",
        "country": "USA"
      }
    },
    "currency": "usd",
    "accountDetails": {
      "accountNumber": "123456789",
      "routingNumber": "021000021",
      "accountType": "checking"
    },
    "networks": ["ach"]
  }'

A successful response returns the bank account object with a system-generated id:

{
    "id": "bankAccount_7c3d2a1b4e8f4290a1c2d3e4f5a6b7c8",
    "customerId": "customer_4fbb292cc6e447da8858e054d1937e7e",
    "bankName": "Chase",
    "accountName": "Jane Doe Checking",
    "currency": "usd",
    "networks": ["ach"],
    "createdAt": "2026-03-03T21:30:00.000Z",
    "updatedAt": "2026-03-03T21:30:00.000Z"
}

Register the crypto wallet that will serve as the destination for the on-ramp transfer. Send a POST request to /v2/wallet with the customer ID and wallet details.

curl -X POST https://api.spherepay.co/v2/wallet \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "customer_4fbb292cc6e447da8858e054d1937e7e",
    "address": "0xAbC1234567890dEfAB1234567890DEFaB123456",
    "network": "ethereum",
    "currency": "usdc"
  }'

A successful response returns the wallet object with a system-generated id:

{
    "id": "wallet_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
    "customerId": "customer_4fbb292cc6e447da8858e054d1937e7e",
    "address": "0xAbC1234567890dEfAB1234567890DEFaB123456",
    "network": "ethereum",
    "currency": "usdc",
    "status": "active",
    "createdAt": "2026-03-03T21:35:00.000Z",
    "updatedAt": "2026-03-03T21:35:00.000Z"
}

Create an on-ramp transfer

With a verified customer, a bank account, and a wallet all registered, you can now create an on-ramp transfer. Specify the bank account as the source and the wallet as the destination.

curl -X POST https://api.spherepay.co/v2/transfer \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "100.00",
    "customer": "customer_4fbb292cc6e447da8858e054d1937e7e",
    "source": {
      "type": "bank_account",
      "id": "bankAccount_7c3d2a1b4e8f4290a1c2d3e4f5a6b7c8",
      "currency": "usd",
      "network": "ach"
    },
    "destination": {
      "type": "wallet",
      "id": "wallet_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
      "currency": "usdc",
      "network": "ethereum"
    }
  }'

A successful response returns the transfer object. The initial status will be pendingFunding while SpherePay waits for funds:

{
    "id": "payout_9z8y7x6w5v4u3t2s1r0q",
    "type": "on_ramp",
    "status": "pendingFunding",
    "customer": "customer_4fbb292cc6e447da8858e054d1937e7e"
}

Track transfer status

Poll the transfer status by sending a GET request to /v2/transfer/{id} using the id returned in the previous step.

curl https://api.spherepay.co/v2/transfer/payout_9z8y7x6w5v4u3t2s1r0q \
  -H "Authorization: Bearer YOUR_API_KEY"

The response returns the transfer object with an updated status field. A transfer moves through pendingFunding → fundsReceived → processing → succeeded (or failed if an error occurs). See Transfer Lifecycle for all possible statuses and their meanings.

Introduction

Get Started

Make Your First SpherePay API Call

Prerequisites

​Prerequisites

Prerequisites