> ## Documentation Index > Fetch the complete documentation index at: https://docs.fluz.app/llms.txt > Use this file to discover all available pages before exploring further. # Transferir a otra cuenta de Fluz Mueve fondos entre el saldo de tu aplicación y los saldos de tus usuarios, o entre dos usuarios. > "Requisito: Tu aplicación debe ser una app pública." ## Inicio rápido Envía \$10 de un usuario a tu aplicación: ```graphql theme={null} mutation { createTransfer(input: { idempotencyKey: "550e8400-e29b-41d4-a716-446655440000" amount: 10 }) { success message transferId } } ``` ```text theme={null} Authorization: Bearer ``` Envía \$10 de tu aplicación a un usuario: ```graphql theme={null} mutation { createTransfer(input: { idempotencyKey: "550e8400-e29b-41d4-a716-446655440001" amount: 10.00 destination: { accountId: "c3d4e5f6-a7b8-9012-cdef-345678901234" } }) { success message transferId } } ``` ```text theme={null} Authorization: Basic ``` *** ## Autenticación Las transferencias admiten dos métodos de autenticación. El método que elijas determina quién es el remitente. | Método | Remitente | Caso de uso | | :----------- | :------------ | :------------------------------------------------------------------- | | Bearer token | El usuario | Cobrar pagos a usuarios (usuario → tú) o mover fondos entre usuarios | | Basic Auth | Tu aplicación | Desembolsar fondos a usuarios (tú → usuario) | ### Bearer Token Usa un token OAuth de usuario obtenido mediante `generateUserAccessToken` o a través del [flujo de actualización de OAuth.](/refresh-o-auth-access-token) El token debe incluir el alcance `MAKE_PAYOUT_TRANSFER_SEND`. ### Basic Auth Usa la Api Key de tu aplicación. *** ## Entrada ### CreateTransferInput | Campo | Tipo | Requerido | Descripción | | :------------------ | :------------------ | :-------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | idempotencyKey | String! | Sí | Un UUID único que generas para evitar transferencias duplicadas. Reenviar la misma clave devuelve el resultado original. | | amount | Float! | Sí | Monto a transferir. Debe ser positivo.. | | destination | TransferDestination | Depende | Quién recibe los fondos. **Requerido para Basic Auth**. Para Bearer token, si se omite, el valor predeterminado es tu aplicación. | | bankCardId | UUID | No | Financiar la transferencia desde la tarjeta bancaria vinculada del usuario en lugar de su saldo en efectivo. Solo Bearer token.. | | bankAccountId | UUID | No | Financiar la transferencia vía ACH desde la cuenta bancaria del usuario. Solo Bearer token.. | | paypalVaultId | UUID | No | Financiar la transferencia desde el PayPal vinculado del usuario. Solo Bearer token.. | | memo | String | No | Nota de texto libre para adjuntar a esta transacción. Máximo 255 caracteres. | | transactionCategory | String | No | Etiqueta de categoría para adjuntar a esta transacción. De formato libre: las categorías se crean automáticamente en el primer uso. | | attachmentId | UUID | No | ID de un archivo previamente cargado (PDF o PNG) para adjuntar a esta transacción. Carga el archivo primero usando el endpoint de adjuntos de memo de transacción. | > "Solo se puede especificar una fuente de fondos por solicitud. Si no se proporciona ninguna, la transferencia se toma del saldo en efectivo del remitente. > > Las fuentes de fondos no están disponibles con Basic Auth." 📘 Consulta [Agregar detalles de gasto](/features/add-expense-details) para obtener información completa sobre cómo cargar adjuntos y trabajar con memos y categorías. ### TransferDirection Identifica al destinatario por ID de cuenta o por el ID de referencia externa que asignaste al crear el usuario. Proporciona uno u otro, no ambos. | Campo | Tipo | Requerido | Descripción | | :------------------ | :----- | :-------- | :----------------------------------------------------------------------------------------------------------------------------------------------- | | accountId | UUID | Sí | El ID de cuenta de Fluz del destinatario.. | | externalReferenceId | String | Sí | El ID de referencia externa que asignaste al usuario en tu sistema.. | | userCashBalanceId | UUID | Depende | Opcional. Orienta un saldo en efectivo específico en la cuenta del destinatario. Si se omite, el sistema selecciona el correcto automáticamente. | > "El destinatario debe ser un usuario registrado de tu aplicación." *** ## Respuesta | Campo | Tipo | Descripción | | :--------- | :------- | :-------------------------------------------------------------------- | | success | Boolean! | Indica si la transferencia se completó. | | message | String! | Descripción del resultado en lenguaje natural. | | transferId | UUID | El ID único de la transferencia. Presente cuando `success` es `true`. | *** ## Ejemplos ### Cobrar un pago de un usuario (Bearer) ```graphql theme={null} mutation { createTransfer(input: { idempotencyKey: "550e8400-e29b-41d4-a716-446655440000" amount: 100.00 }) { success message transferId } } ``` ```text theme={null} Authorization: Bearer ``` No se necesita destino: el valor predeterminado es tu aplicación. Opcionalmente incluye `bankCardId`, `bankAccountId` o `paypalVaultId` para financiar desde una fuente externa en lugar del saldo en efectivo del usuario. ### Desembolsar fondos a un usuario (Basic Auth) ```graphql theme={null} mutation { createTransfer(input: { idempotencyKey: "550e8400-e29b-41d4-a716-446655440001" amount: 50.00 destination: { accountId: "c3d4e5f6-a7b8-9012-cdef-345678901234" } }) { success message transferId } } ``` ```text theme={null} Authorization: Basic ``` Usa `externalReferenceId` en lugar de `accountId` para identificar al destinatario por el ID que asignaste. ### Transferir entre dos usuarios (Bearer) ```graphql theme={null} mutation { createTransfer(input: { idempotencyKey: "550e8400-e29b-41d4-a716-446655440002" amount: 25.00 destination: { accountId: "b2c3d4e5-f6a7-8901-bcde-f23456789012" } }) { success message transferId } } ``` ```text theme={null} Authorization: Bearer ``` ### Respuesta exitosa ```json theme={null} { "data": { "createTransfer": { "success": true, "message": "Transfer created successfully.", "transferId": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } } } ``` *** ## Idempotencia Cada solicitud debe incluir una `idempotencyKey` única (una cadena que generas). Si se envía la misma clave más de una vez, la API devuelve el resultado de la solicitud original sin crear una transferencia duplicada. Las claves son válidas por 10 minutos. *** ## Errores Los errores siguen el formato estándar de errores de GraphQL: ```json theme={null} { "errors": [ { "message": "Amount must be positive.", "extensions": { "code": "ARG-0001", "name": "InvalidArguments", "status_code": 422 } } ] } ``` ### Error común | Error | Causa | | :-------------------------------------------------------- | :-------------------------------------------------------------------------------------------- | | Missing idempotencyKey or amount | Campos requeridos no proporcionados. | | Amount must be positive | El monto es cero o negativo. | | Destination is required when using Basic auth | Las solicitudes con Basic Auth deben especificar un destino. | | Funding sources are not supported when using Basic auth | Elimina `bankCardId` / `bankAccountId` / `paypalVaultId` de las solicitudes con Basic Auth. | | Only one funding source is allowed at a time | Se proporcionaron múltiples fuentes de fondos. Pasa solo una. | | Provide either accountId or externalReferenceId, not both | El destino tiene ambos identificadores. Usa uno. | | Destination account has not authorized this application | El destinatario no es un usuario registrado de tu aplicación. | | No user found with this external reference ID | El `externalReferenceId` no coincide con ningún usuario en tu aplicación. | | User does not have a cash balance configured | El remitente o destinatario no tiene un saldo en efectivo en el banco patrocinador requerido. | | Basic auth is not supported for personal applications | Actualiza tu aplicación a estado `ACTIVE` para usar transferencias con Basic Auth. | | Insufficient balance | El saldo en efectivo del remitente es menor que el monto de la transferencia. |