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

# Flujos de Primera Parte

> Caminos de implementación cuando la misma entidad legal posee ambos lados del movimiento: transferencias únicas, Onramper Accounts y Offloader Wallets.

**Cuándo Sphere te enruta aquí:** El descubrimiento confirmó que la misma entidad legal posee tanto el origen como el destino — por ejemplo, on-ramp de tesorería, off-ramp de tesorería, o fondeo reutilizable/retiro para la cuenta bancaria y billetera propia de esa entidad.

Esta página define el **patrón de implementación de primera parte** a construir. Para definiciones de objetos y payloads de API, sigue los enlaces hacia [Conceptos](https://docs.spherepay.co/es/concepts/overview.md) y [Referencia API](https://docs.spherepay.co/es/api-reference/customer/post.md).

> [!NOTE]
>
> ¿Pagando empleados, proveedores, vendedores de marketplace u otros terceros? Usa [Flujos de Tercera Parte](https://docs.spherepay.co/es/implementation-guides/third-party-flows.md) en su lugar.

## Salida de definición

Al final del descubrimiento, tú y SpherePay deben acordar sobre:

* Tipo de cliente — individual o empresarial
* Entidad legal que posee **tanto** el origen como el destino
* Primer movimiento — on-ramp, off-ramp, o ambos
* Patrón — transferencia única, Onramper Account u Offloader Wallet
* Divisa fiat y riel
* Stablecoin y red
* Transferencias únicas vs instrucciones reutilizables
* Solo movimiento/conversión vs tenencia de saldo fiat
* Volumen mensual esperado, tamaño de transacción promedio y máximo
* Requisitos de perfil de verificación y habilitación de corredor
* Campos de conciliación que necesita tu equipo de finanzas

## Elige tu patrón

> [card] [Transferencia única](#pattern-one-off-transfer)
>
> Control explícito de API por on-ramp u off-ramp. Mejor cuando cada movimiento se inicia individualmente.

> [card] [Onramper Account](#pattern-onramper-account)
>
> Instrucciones de depósito fiat reutilizables que convierten automáticamente a stablecoin en la billetera del cliente.

> [card] [Offloader Wallet](#pattern-offloader-wallet)
>
> Dirección de depósito de stablecoin reutilizable que convierte automáticamente a fiat en la cuenta bancaria del cliente.

| Patrón | Señales del descubrimiento | Objetos principales |
| - | - | - |
| [Transferencia única](#pattern-one-off-transfer) | Control de API por movimiento; conversiones ad-hoc; seguimiento de estado por transferencia | Cliente, [billetera](https://docs.spherepay.co/es/concepts/transfers/wallets.md), [cuenta bancaria](https://docs.spherepay.co/es/concepts/transfers/bank-accounts.md), [transferencia](https://docs.spherepay.co/es/concepts/transfers/overview.md) |
| [Onramper Account](#pattern-onramper-account) | Depósitos fiat reutilizables; conversión automática a stablecoin; sin llamada de transferencia por depósito | Cliente, billetera, [Onramper Account](https://docs.spherepay.co/es/concepts/automation/onramper-accounts.md) |
| [Offloader Wallet](#pattern-offloader-wallet) | Depósitos de stablecoin reutilizables; conversión automática a fiat; sin llamada de transferencia por depósito | Cliente, cuenta bancaria, [Offloader Wallet](https://docs.spherepay.co/es/concepts/automation/offloader-wallets.md) |

## Cómo funciona el flujo

> [tab] On-ramp
>
> Cuenta bancaria del cliente o cuenta de fondeo reutilizable → SpherePay → Billetera del cliente
>
> ```mermaid theme={"dark"}
> flowchart LR
>     BA["Customer<br/>bank account"] -->|Fiat deposit| SP["SpherePay"]
>     SP -->|Stablecoin| W["Customer<br/>wallet"]
> ```

> [tab] Off-ramp
>
> Billetera del cliente → SpherePay → Cuenta bancaria del cliente
>
> ```mermaid theme={"dark"}
> flowchart LR
>     W["Customer<br/>wallet"] -->|Stablecoin| SP["SpherePay"]
>     SP -->|Fiat payout| BA["Customer<br/>bank account"]
> ```

Para un ejemplo de viaje de ida y vuelta de tesorería, consulta [Gestión de tesorería](https://docs.spherepay.co/es/solutions/treasury-management.md).

## Patrón: Transferencia única

**Usar cuando:** El cliente inicia cada on-ramp u off-ramp individualmente y necesita control explícito por transferencia.

**Señales del descubrimiento:**

* Cada movimiento se inicia en un momento específico — no activado por una dirección de depósito permanente
* El integrador posee el reintento, la idempotencia y la UX de estado por transferencia
* El cliente puede necesitar cotizar o ejecutar transferencias una a la vez

**1. Crear o recuperar el cliente**

Registra la entidad legal vía [POST /v2/customer](https://docs.spherepay.co/es/api-reference/customer/post.md).

**2. Completar KYC o KYB**

Termina el [KYC individual](https://docs.spherepay.co/es/concepts/onboarding/individual-kyc.md) o el [KYB empresarial](https://docs.spherepay.co/es/concepts/onboarding/business-kyb.md) hasta que el [perfil de verificación](https://docs.spherepay.co/es/concepts/onboarding/verification-profile.md) alcance `approved`.

**3. Registrar instrumentos**

Vincula la [billetera](https://docs.spherepay.co/es/api-reference/wallet/post.md) y la [cuenta bancaria](https://docs.spherepay.co/es/api-reference/bank-account/post.md) del cliente en el mismo registro de cliente.

**4. Bloquear una tasa (opcional)**

Si el cliente necesita una tasa garantizada, crea una cotización con tasa bloqueada vía [POST /v2/quote](https://docs.spherepay.co/es/api-reference/quote/post.md) (válida por 30, 60 o 300 segundos, canjeable una vez) y referencia su `quoteId` al crear la transferencia.

**5. Crear cada transferencia**

Llama a [POST /v2/transfer](https://docs.spherepay.co/es/api-reference/transfer/post.md) con cliente, origen y destino.

**6. Rastrear y conciliar**

Consulta [GET /v2/transfer/{transferId}](https://docs.spherepay.co/es/api-reference/transfer/get-id.md) hasta un estado terminal — consulta el [ciclo de vida de la transferencia](https://docs.spherepay.co/es/concepts/transfers/lifecycle.md).

> [!NOTE]
>
> Confirma que los instrumentos de origen y destino pertenecen al **mismo** cliente incorporado. Algunos corredores requieren habilitación específica del proveedor más allá del KYC/KYB estándar — confirma el acceso con SpherePay antes de construir.

**Solución relacionada:** [Gestión de tesorería](https://docs.spherepay.co/es/solutions/treasury-management.md)

## Patrón: Onramper Account

**Usar cuando:** El cliente necesita instrucciones de depósito fiat reutilizables que convierten automáticamente a stablecoin en una billetera que posee.

**Señales del descubrimiento:**

* El cliente enviará fiat a las mismas instrucciones de depósito repetidamente
* No debe dispararse una llamada `POST /v2/transfer` en cada depósito
* El destino es una billetera de stablecoin propiedad de la misma entidad legal

**1. Crear o recuperar el cliente**

Registra la entidad legal vía [POST /v2/customer](https://docs.spherepay.co/es/api-reference/customer/post.md).

**2. Completar KYC o KYB**

Alcanza `approved` en el perfil de verificación requerido.

**3. Registrar la billetera de destino**

El cliente ya debe poseer la dirección on-chain. Registra vía [POST /v2/wallet](https://docs.spherepay.co/es/api-reference/wallet/post.md).

**4. Crear un Onramper Account**

Llama a [POST /v2/virtual-account](https://docs.spherepay.co/es/api-reference/virtual-account/post.md). Consulta [Onramper Accounts](https://docs.spherepay.co/es/concepts/automation/onramper-accounts.md).

**5. Compartir instrucciones de depósito**

Proporciona `depositInstructions` de la respuesta. SpherePay convierte el fiat entrante y entrega stablecoin automáticamente.

**6. Rastrear depósitos y conversiones**

Consulta [GET /v2/transfer](https://docs.spherepay.co/es/api-reference/transfer/get.md) filtrado por cliente (usa `type=microdeposit` para depósitos de verificación) para listar las transferencias procesadas a través de la cuenta. Cada depósito fiat aparece como una transferencia una vez detectado — concilia contra tus depósitos esperados. No hay una llamada de API por depósito en la que anclar el estado, así que diseña tu cadencia de polling y claves de conciliación antes del lanzamiento.

> [!WARNING]
>
> Los Onramper Accounts son un producto adicional. Crea **una cuenta por cliente** — las cuentas compartidas rompen la atribución de depósitos. Confirma que el producto está habilitado para tu riel y región.

**Soluciones relacionadas:** [Aceptación de pagos](https://docs.spherepay.co/es/solutions/payment-acceptance.md), [Gestión de tesorería](https://docs.spherepay.co/es/solutions/treasury-management.md)

## Patrón: Offloader Wallet

**Usar cuando:** El cliente necesita una dirección on-chain reutilizable que convierte automáticamente stablecoin entrante a fiat en una cuenta bancaria que posee.

**Señales del descubrimiento:**

* El cliente enviará stablecoin a la misma dirección repetidamente
* No debe dispararse una llamada `POST /v2/transfer` en cada depósito
* El destino fiat es una cuenta bancaria propiedad de la misma entidad legal

**1. Crear o recuperar el cliente**

Registra la entidad legal vía [POST /v2/customer](https://docs.spherepay.co/es/api-reference/customer/post.md).

**2. Completar KYC o KYB**

Alcanza `approved` en el perfil de verificación requerido.

**3. Registrar la cuenta bancaria de destino**

Vincula la cuenta existente del cliente vía [POST /v2/bank-account](https://docs.spherepay.co/es/api-reference/bank-account/post.md).

**4. Crear un Offloader Wallet**

Llama a [POST /v2/offloader-wallet](https://docs.spherepay.co/es/api-reference/offloader-wallet/post.md). Consulta [Offloader Wallets](https://docs.spherepay.co/es/concepts/automation/offloader-wallets.md).

**5. Compartir la dirección offloader**

Proporciona la dirección on-chain de la respuesta. SpherePay convierte la stablecoin y paga el fiat automáticamente.

**6. Rastrear depósitos y pagos**

Consulta [GET /v2/transfer](https://docs.spherepay.co/es/api-reference/transfer/get.md) filtrado por cliente para rastrear depósitos de stablecoin y los pagos fiat resultantes hasta un estado terminal — consulta el [ciclo de vida de la transferencia](https://docs.spherepay.co/es/concepts/transfers/lifecycle.md).

> [!WARNING]
>
> Los Offloader Wallets son un producto adicional. Crea **una billetera por cliente**. Para cambiar el tipo de divisa/destino de origen o el tipo de riel, crea una nueva billetera — otros campos pueden ser PATCHeable vía [Actualizar Offloader Wallet](https://docs.spherepay.co/es/api-reference/offloader-wallet/patch-id.md). Verifica el nombre legal y la dirección física del titular de la cuenta bancaria (sin apartados postales) antes de crear la billetera — los socios rechazan direcciones con apartado postal, y las vías de corrección para una cuenta bancaria adjunta son limitadas.

**Solución relacionada:** [Gestión de tesorería](https://docs.spherepay.co/es/solutions/treasury-management.md)

## Qué enviar a Sphere antes del inicio

* Tipo de cliente: individual o empresarial
* Entidad legal que posee origen y destino
* Primer flujo: on-ramp, off-ramp, o ambos
* Patrón seleccionado: transferencia única, Onramper Account u Offloader Wallet
* Divisa fiat y riel
* Stablecoin y red
* Volumen mensual esperado
* Tamaño de transacción promedio y máximo
* Transferencias únicas vs instrucciones reutilizables
* Solo movimiento/conversión vs tenencia de saldo fiat
* Requisitos de conciliación

## Validar antes de que comience la ingeniería

| Bloqueo | Qué suele significar |
| - | - |
| Perfil de verificación no aprobado | El perfil KYC/KYB requerido está incompleto, pendiente, faltante o rechazado |
| Proveedor/corredor no habilitado | El cliente puede estar aprobado en general pero no habilitado para el corredor o riel específico |
| Riel, divisa o red no soportados | Combinación no disponible para tu producto — [Rieles soportados](https://docs.spherepay.co/es/concepts/transfers/supported-rails.md) |
| Discrepancia de propiedad | El instrumento de origen o destino no pertenece al cliente incorporado |
| Confusión con billeteras | [POST /v2/wallet](https://docs.spherepay.co/es/api-reference/wallet/post.md) registra una dirección existente — SpherePay no genera ni custodia claves privadas |
| Confusión con Onramper Account | Automatiza la conversión de fiat a stablecoin vía instrucciones de depósito — confirma requisitos de solo movimiento vs tenencia de saldo |
| Actualizaciones de Offloader Wallet | Cambiar el tipo de divisa/destino de origen o el tipo de riel requiere una nueva billetera; otros campos pueden ser PATCHeables |

## Lista de verificación pre-inicio

* [ ] La misma entidad legal posee origen y destino
* [ ] Patrón seleccionado y confirmado con SpherePay
* [ ] Cliente creado o recuperado; perfil de verificación `approved` para el corredor objetivo
* [ ] Proveedor/corredor habilitado si es requerido
* [ ] Billetera y/o cuenta bancaria registrada en el cliente correcto
* [ ] Riel, divisa y red confirmados
* [ ] Mapeo de conciliación y estado definido
* [ ] Entradas de inicio enviadas a SpherePay

## Antes del lanzamiento

SpherePay no tiene un sandbox separado — las pruebas de integración se ejecutan contra producción con datos de identidad reales. Ejecuta una transferencia en vivo de bajo monto en cada corredor antes del lanzamiento.

La primera transferencia a un nuevo beneficiario puede activar un RFI de cumplimiento del socio bancario. Establece esta expectativa con tu cliente desde el inicio, y asegúrate de que tu propietario de RFI designado esté listo para responder.

Para preguntas de liquidación de usuarios finales, comparte los artículos de la Base de Conocimiento de SpherePay [When will the funds land in my account?](https://spherepay-knowledge-base.help.usepylon.com/articles/9934878291-when-will-the-funds-land-in-my-account) y [My funds are missing or have not landed in my account](https://spherepay-knowledge-base.help.usepylon.com/articles/9884755317-my-funds-are-missing-or-have-not-landed-in-my-account-what-should-i-do) para que los usuarios se autoatiendan en lugar de abrir tickets de soporte contigo.

## Profundizar

> [card] [Gestión de tesorería](https://docs.spherepay.co/es/solutions/treasury-management.md)
>
> Resultado de tesorería de primera parte — ejemplos de on-ramp/off-ramp de ida y vuelta.

> [card] [Transferencias](https://docs.spherepay.co/es/concepts/transfers/overview.md)
>
> Ciclo de vida de transferencia única, restricciones BRL/PIX y referencia de estados.

> [card] [Flujos de Tercera Parte](https://docs.spherepay.co/es/implementation-guides/third-party-flows.md)
>
> Cuando origen y destino no son la misma entidad legal.

> [card] [Incorporación](https://docs.spherepay.co/es/concepts/onboarding/overview.md)
>
> Requisitos de KYC, KYB y perfil de verificación.

> [card] [Base de Conocimiento y FAQ](https://spherepay-knowledge-base.help.usepylon.com/)
>
> Artículos de soporte para usuarios finales — tiempos de liquidación, fondos faltantes, mínimos y guías del panel — para compartir con tus usuarios.


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