> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spherepay.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Make Your First SpherePay API Call

> Walk through creating a customer, registering a bank account and wallet, then executing your first on-ramp transfer with the SpherePay API.

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](/get-started/authentication).
* You understand the integration model. If not, read [How it works](/get-started/how-it-works) first.

<Steps>
  <Step title="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.

    ```bash theme={"dark"}
    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`:

    ```json theme={"dark"}
    {
        "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"
    }
    ```

    <Note>
      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](/concepts/onboarding/individual-kyc) or [Business KYB Flow](/concepts/onboarding/business-kyb) for next steps.
    </Note>
  </Step>

  <Step title="Register a bank account">
    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.

    ```bash theme={"dark"}
    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`:

    ```json theme={"dark"}
    {
        "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"
    }
    ```
  </Step>

  <Step title="Register a wallet">
    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.

    ```bash theme={"dark"}
    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`:

    ```json theme={"dark"}
    {
        "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"
    }
    ```
  </Step>

  <Step title="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`.

    ```bash theme={"dark"}
    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:

    ```json theme={"dark"}
    {
        "id": "payout_9z8y7x6w5v4u3t2s1r0q",
        "type": "on_ramp",
        "status": "pendingFunding",
        "customer": "customer_4fbb292cc6e447da8858e054d1937e7e"
    }
    ```
  </Step>

  <Step title="Track transfer status">
    Poll the transfer status by sending a `GET` request to `/v2/transfer/{id}` using the `id` returned in the previous step.

    ```bash theme={"dark"}
    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](/concepts/transfers/lifecycle) for all possible statuses and their meanings.
  </Step>
</Steps>