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:

mutation {
  createTransfer(input: {
    idempotencyKey: "550e8400-e29b-41d4-a716-446655440000"
    amount: 10
  }) {
    success
    message
    transferId
  }
}

Authorization: Bearer <user-oauth-token>

Envía $10 de tu aplicación a un usuario:

mutation {
  createTransfer(input: {
    idempotencyKey: "550e8400-e29b-41d4-a716-446655440001"
    amount: 10.00
    destination: {
      accountId: "c3d4e5f6-a7b8-9012-cdef-345678901234"
    }
  }) {
    success
    message
    transferId
  }
}

Authorization: Basic <Api-Key>

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

mutation {
  createTransfer(input: {
    idempotencyKey: "550e8400-e29b-41d4-a716-446655440000"
    amount: 100.00
  }) {
    success
    message
    transferId
  }
}

Authorization: Bearer <user-oauth-token>

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)

mutation {
  createTransfer(input: {
    idempotencyKey: "550e8400-e29b-41d4-a716-446655440001"
    amount: 50.00
    destination: {
      accountId: "c3d4e5f6-a7b8-9012-cdef-345678901234"
    }
  }) {
    success
    message
    transferId
  }
}

Authorization: Basic <API-Key>

Usa externalReferenceId en lugar de accountId para identificar al destinatario por el ID que asignaste.

Transferir entre dos usuarios (Bearer)

mutation {
  createTransfer(input: {
    idempotencyKey: "550e8400-e29b-41d4-a716-446655440002"
    amount: 25.00
    destination: {
      accountId: "b2c3d4e5-f6a7-8901-bcde-f23456789012"
    }
  }) {
    success
    message
    transferId
  }
}

Authorization: Bearer <user-oauth-token>

Respuesta exitosa

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

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

​Inicio rápido

​Autenticación

​Bearer Token

​Basic Auth

​Entrada

​CreateTransferInput

​TransferDirection

​Respuesta

​Ejemplos

​Cobrar un pago de un usuario (Bearer)

​Desembolsar fondos a un usuario (Basic Auth)

​Transferir entre dos usuarios (Bearer)

​Respuesta exitosa

​Idempotencia

​Errores

​Error común