> ## 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.
# API de Transferencias: Guía de On-Ramp y Off-Ramp
> Crea transferencias on-ramp y off-ramp con la API de SpherePay: flujo de integración, ejemplos para USD y BRL/PIX, y seguimiento de estado.
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](/es/implementation-guides/first-party-flows) o [tercera parte](/es/implementation-guides/third-party-flows) 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](/widget/overview) 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
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](/es/concepts/onboarding/overview).
Registra la cuenta bancaria y la billetera que se usarán como origen y destino para la transferencia.
* Cuentas bancarias: [POST /v2/bank-account](/es/concepts/transfers/bank-accounts)
* Billeteras: [POST /v2/wallet](/es/concepts/transfers/wallets)
Llama a `POST /v2/transfer` con el cliente, monto, origen y destino. Consulta ejemplos completos a continuación.
Consulta `GET /v2/transfer/{id}` hasta que la transferencia alcance un estado terminal (`succeeded`, `failed`, `refunded`, etc.). Consulta [Ciclo de Vida de la Transferencia](/es/concepts/transfers/lifecycle).
## 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.
Envía USD desde una cuenta bancaria vía ACH y entrega USDC a una billetera Ethereum.
```bash theme={"dark"}
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.
```bash theme={"dark"}
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.
```bash theme={"dark"}
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.
```bash theme={"dark"}
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:
```json theme={"dark"}
{
"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](/es/api-reference/transfer/get) 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](/es/api-reference/transfer/get-id) 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](/es/concepts/transfers/lifecycle) para la referencia completa de estados.