Realiza tu Primera Llamada a 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.
Entiendes el modelo de integración. Si no, lee Cómo funciona primero.

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.

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:

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

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 o el Flujo KYB Empresarial para los próximos pasos.

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.

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:

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

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.

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:

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

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

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:

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

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.

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 para todos los posibles estados y sus significados.

​Requisitos previos

Requisitos previos