API de Transferencias: Guía de On-Ramp y Off-Ramp

La API de Transferencias te permite crear transferencias (transfer) on-ramp y off-ramp para tus clientes y rastrear su ciclo de vida desde la creación hasta la finalización o fallo. Un on-ramp convierte moneda fiat (USD, EUR, BRL) en una stablecoin (USDC, USDT, EURC) depositada en una billetera blockchain. Un off-ramp hace lo inverso — convierte stablecoin en fiat y lo entrega a una cuenta bancaria. Ambas direcciones usan el mismo endpoint POST /v2/transfer; la dirección se determina por lo que configures como source (origen) y destination (destino).

Las transferencias pueden soportar múltiples modelos de negocio. Antes de la implementación, confirma si el movimiento es de primera parte o tercera parte para que puedas identificar el cliente de registro correcto, origen, destino y datos de pago requeridos.

Cuándo usar la API de Transferencias

Usa la API de Transferencias cuando quieras integrar transferencias directamente en tu producto y controlar tu propia UX. Tú inicias cada transferencia explícitamente, y SpherePay devuelve instrucciones de depósito únicas por solicitud — el cliente envía fondos a esas instrucciones, y SpherePay hace coincidir el memo para procesarlo. Si quieres una experiencia alojada preconstruida sin trabajo de frontend, usa el Ramp Widget en su lugar.

	API de Transferencias	Ramp Widget
Control	Total — tú inicias y rastreas cada transferencia	Mínimo — SpherePay aloja la UX
Propiedad de UX	Tu producto	Widget alojado por SpherePay
Mejor para	Integraciones personalizadas, flujos programáticos	Embeds rápidos, prototipos

Resumen de integración

Incorporar al cliente

Completa KYC (individuos) o KYB (empresas) antes de que se pueda crear cualquier transferencia. El perfil de verificación del cliente debe ser approved. Consulta Clientes e Incorporación.

Crear instrumentos de fondeo

Registra la cuenta bancaria y la billetera que se usarán como origen y destino para la transferencia.

Cuentas bancarias: POST /v2/bank-account
Billeteras: POST /v2/wallet

Crear una transferencia

Llama a POST /v2/transfer con el cliente, monto, origen y destino. Consulta ejemplos completos a continuación.

Rastrear el estado y manejar resultados

Consulta GET /v2/transfer/{id} hasta que la transferencia alcance un estado terminal (succeeded, failed, refunded, etc.). Consulta Ciclo de Vida de la Transferencia.

Creación de transferencias

POST https://api.spherepay.co/v2/transfer Usa las pestañas a continuación para ver los cuerpos de solicitud para cada dirección de transferencia soportada.

On-ramp (USD)
Off-ramp (USD)
On-ramp (BRL/PIX)
Off-ramp (BRL/PIX)

Envía USD desde una cuenta bancaria vía ACH y entrega USDC a una billetera Ethereum.

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

Envía USDC desde una billetera Ethereum y entrega USD a una cuenta bancaria vía ACH.

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

Envía BRL desde una cuenta bancaria PIX y entrega USDC a una billetera Polygon.

curl -X POST https://api.spherepay.co/v2/transfer \
  -H "Authorization: Bearer {{api_key}}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "500.00",
    "customer": "{{customer_id}}",
    "source": {
      "type": "bank_account",
      "id": "{{bank_account_id}}",
      "currency": "brl",
      "network": "pix"
    },
    "destination": {
      "type": "wallet",
      "id": "{{wallet_id}}",
      "currency": "usdc",
      "network": "polygon"
    },
    "integratorBpsFeeRate": "50"
  }'

Envía USDC desde una billetera Polygon y entrega BRL a una cuenta bancaria PIX.

curl -X POST https://api.spherepay.co/v2/transfer \
  -H "Authorization: Bearer {{api_key}}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "500.00",
    "customer": "{{customer_id}}",
    "source": {
      "type": "wallet",
      "id": "{{wallet_id}}",
      "currency": "usdc",
      "network": "polygon"
    },
    "destination": {
      "type": "bank_account",
      "id": "{{bank_account_id}}",
      "currency": "brl",
      "network": "pix"
    },
    "integratorBpsFeeRate": "50"
  }'

Respuesta

Una solicitud exitosa devuelve un objeto de transferencia con un id, type y status inicial:

{
  "id": "payout_1234567890abcdef12345678",
  "type": "on_ramp",
  "status": "pendingFunding",
  "customer": "customer_123abc..."
}

Guarda el id — lo usarás para consultar actualizaciones de estado.

Restricciones de transferencias BRL/PIX

Las transferencias BRL usan la red de pago instantáneo PIX de Brasil y están sujetas a reglas adicionales más allá de las transferencias estándar USD/EUR. Límites de transferencia

On-ramp (PIX BRL → USDC/USDT): R $1.00 – R$ 7,500.00 por transferencia
Off-ramp (USDC/USDT → PIX BRL): $1.00 –$ 7,500.00 (unidades de stablecoin, aproximadamente 1:1 con USD)

Los límites pueden incrementarse basándose en diligencia debida. Contacta a tu representante de SpherePay para más detalles. Redes de billetera soportadas Las transferencias BRL soportan polygon, ethereum, base y tron. Solana no está soportada para transferencias BRL — las solicitudes que pasen "network": "sol" serán rechazadas. Stablecoins soportadas

Stablecoin	Polygon	Ethereum	Base	Tron
USDC	✅	✅	✅	—
USDT	✅	✅	—	✅

USDT en Base y USDC en Tron no están soportados para transferencias BRL.

Parámetro de comisión Solo se acepta integratorBpsFeeRate (puntos base) para transferencias BRL. integratorFixedFee no está permitido porque las comisiones se cobran en el lado de la stablecoin, y una comisión fija denominada en fiat requeriría conversión entre divisas. Perfil de verificación Las transferencias BRL requieren un perfil de verificación separado (kyc_profile_b para individuos, kyb_profile_b para empresas) además del perfil estándar. Contacta a tu representante de SpherePay para habilitar el acceso.

Rastrear transferencias

Listar todas las transferencias

GET https://api.spherepay.co/v2/transfer Devuelve una lista paginada de transferencias para tu cuenta. Consulta la referencia API de Lista de Transferencias para parámetros de consulta y formato de respuesta.

Recuperar una transferencia por ID

GET https://api.spherepay.co/v2/transfer/{id} Devuelve el estado actual de una única transferencia. Consulta este endpoint para rastrear el progreso. Consulta la referencia API de Obtener una Transferencia para el esquema de respuesta completo.

Consulta GET /v2/transfer/{id} después de la creación y después de cada actualización de estado hasta que la transferencia alcance un estado terminal: succeeded, refunded, failed o canceled. Consulta Ciclo de Vida de la Transferencia para la referencia completa de estados.

​Cuándo usar la API de Transferencias

​Resumen de integración

​Creación de transferencias

​Respuesta

​Restricciones de transferencias BRL/PIX

​Rastrear transferencias

​Listar todas las transferencias

​Recuperar una transferencia por ID

Cuándo usar la API de Transferencias

Resumen de integración

Creación de transferencias

Respuesta

Restricciones de transferencias BRL/PIX

Rastrear transferencias

Listar todas las transferencias

Recuperar una transferencia por ID