> ## 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.

# Realiza tu Primera Llamada a la API de SpherePay

> Recorre la creación de un cliente, el registro de una cuenta bancaria y billetera, y luego ejecuta tu primera transferencia on-ramp con la API de SpherePay.

Esta guía te lleva por la secuencia completa de tu primera integración con SpherePay: crea un cliente (`customer`), registra una cuenta bancaria (`bank_account`) y una billetera (`wallet`), luego ejecuta una transferencia on-ramp. Al final, habrás realizado llamadas API reales contra cada recurso central del modelo de SpherePay.

Todas las solicitudes van a la URL base: `https://api.spherepay.co/`

## Requisitos previos

* Tienes una clave API. Si no, consulta [Autenticación](https://docs.spherepay.co/es/get-started/authentication.md).
* Entiendes el modelo de integración. Si no, lee [Cómo funciona](https://docs.spherepay.co/es/get-started/how-it-works.md) primero.

**1. Crear un cliente**

Crea un cliente individual enviando una solicitud `POST` a `/v2/customer`. Incluye los datos de contacto e información de identificación fiscal del cliente.

```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"
    }
  }'
```

Una respuesta exitosa devuelve el objeto de cliente recién creado con un `id` generado por el sistema y un arreglo `verificationProfiles` que muestra el estado KYC como `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]
>
> El cliente debe completar la verificación KYC y alcanzar un estado `approved` antes de que puedas crear una transferencia en su nombre. La incorporación es un requisito previo obligatorio para todas las transferencias. Consulta el [Flujo KYC Individual](https://docs.spherepay.co/es/concepts/onboarding/individual-kyc.md) o el [Flujo KYB Empresarial](https://docs.spherepay.co/es/concepts/onboarding/business-kyb.md) para los próximos pasos.

**2. Registrar una cuenta bancaria**

Una vez que tu cliente tenga aprobación KYC, registra la cuenta bancaria que servirá como origen fiat para una transferencia on-ramp. Envía una solicitud `POST` a `/v2/bank-account` con el ID de cliente y los detalles de la cuenta.

```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"]
  }'
```

Una respuesta exitosa devuelve el objeto de cuenta bancaria con un `id` generado por el sistema:

```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"
}
```

**3. Registrar una billetera**

Registra la billetera cripto que servirá como destino para la transferencia on-ramp. Envía una solicitud `POST` a `/v2/wallet` con el ID de cliente y los detalles de la billetera.

```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"
  }'
```

Una respuesta exitosa devuelve el objeto de billetera con un `id` generado por el sistema:

```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"
}
```

**4. Crear una transferencia on-ramp**

Con un cliente verificado, una cuenta bancaria y una billetera registradas, ahora puedes crear una transferencia on-ramp. Especifica la cuenta bancaria como `source` (origen) y la billetera como `destination` (destino).

```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"
    }
  }'
```

Una respuesta exitosa devuelve el objeto de transferencia. El `status` inicial será `pendingFunding` mientras SpherePay espera los fondos:

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

**5. Rastrear el estado de la transferencia**

Consulta el estado de la transferencia enviando una solicitud `GET` a `/v2/transfer/{id}` usando el `id` devuelto en el paso anterior.

```bash theme={"dark"}
curl https://api.spherepay.co/v2/transfer/payout_9z8y7x6w5v4u3t2s1r0q \
  -H "Authorization: Bearer YOUR_API_KEY"
```

La respuesta devuelve el objeto de transferencia con un campo `status` actualizado. Una transferencia avanza por `pendingFunding` → `fundsReceived` → `processing` → `succeeded` (o `failed` si ocurre un error). Consulta [Ciclo de Vida de la Transferencia](https://docs.spherepay.co/es/concepts/transfers/lifecycle.md) para todos los posibles estados y sus significados.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.