> ## 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. # Enviar dinero > Envía dinero desde el saldo en efectivo de un usuario a una dirección de correo electrónico, un número de teléfono, una cuenta de Fluz o un enlace de reclamo con sendMoney, y cancela un envío que nadie ha reclamado. Usa [`sendMoney`](https://docs.fluz.app/api-reference/mutations/send-money) para enviar dinero desde el saldo en efectivo de Fluz de un usuario. Puedes dirigirlo a una dirección de correo electrónico o a un número de teléfono, a un id de cuenta de Fluz, o a nadie, en cuyo caso obtienes un enlace de reclamo para que lo entregues tú mismo. El destinatario no necesita ser usuario de tu aplicación ni tener ya una cuenta de Fluz. Un envío termina de una de dos maneras. `SENT` significa que el dinero llegó al saldo del destinatario, y es definitivo. `PENDING_CLAIM` significa que Fluz retiene el dinero hasta que el destinatario lo reclame en una página de Fluz. Si nadie lo reclama antes de que venza, o si lo cancelas, el dinero regresa al remitente. La forma en que diriges el envío decide cuál de los dos ocurre. > [!NOTE] > > **Antes de empezar** > > * Llama con un token de acceso de usuario Bearer que tenga el scope `MAKE_PAYOUT_TRANSFER_SEND`. No se acepta Basic Auth con tu clave de API. > * El usuario del token debe ser propietario o administrador de la cuenta. > * Fluz habilita el envío de dinero por cuenta. Pide a tu equipo de cuenta que lo habilite para cada cuenta que envíe. > * La cuenta debe haber pasado la verificación de identidad: KYC para una cuenta personal, KYB para una empresa. > * Si el usuario limitó tu aplicación a ciertas cuentas de gasto, envía desde una de ellas. > [!NOTE] > > **No es lo mismo que `createTransfer`.** > > [`createTransfer`](https://docs.fluz.app/features/transfer-to-another-fluz-wallet) mueve dinero entre la cuenta de tu aplicación y las cuentas que han autorizado tu aplicación, o entre dos de esas cuentas. `sendMoney` puede pagar a cualquier cuenta de Fluz que pueda recibir pagos, o llegar a alguien por correo electrónico o teléfono. Para un destinatario nuevo retiene el dinero hasta que lo reclame, y Fluz le envía el enlace de reclamo. ## Cómo se entrega un envío | Envías a | Qué ocurre | | :- | :- | | `recipientId` | El dinero llega de inmediato a esa cuenta (`SENT`). Si la cuenta no puede recibir pagos, el envío se rechaza. Nunca se retiene. | | `recipientEmail` o `recipientPhone`, y un usuario de Fluz ha verificado ese dato de contacto | El dinero llega de inmediato a la cuenta personal de ese usuario (`SENT`). | | `recipientEmail` o `recipientPhone` que no coincide con ningún usuario de Fluz, o que coincide con un usuario que no lo ha verificado | Fluz retiene el dinero (`PENDING_CLAIM`) y envía al destinatario un enlace de reclamo al dato de contacto que indicaste. | | `linkOnly: true` | Fluz retiene el dinero (`PENDING_CLAIM`) y devuelve un `claimLink`. Fluz no contacta a nadie, así que tú entregas el enlace. | Fluz compara la dirección de correo electrónico y el número de teléfono con los del perfil de Fluz de un usuario. Si alguno coincide con más de un usuario, el envío se rechaza y necesitas otro identificador. Puedes enviar `recipientEmail` y `recipientPhone` juntos para la misma persona. Si ambos coinciden con un mismo usuario, decide el teléfono: el dinero llega de inmediato solo si ese usuario ha verificado el teléfono. Si coinciden con dos usuarios distintos, Fluz retiene el dinero en lugar de elegir. Si solo uno de ellos coincide con un usuario, ese dato de contacto decide por sí solo: si el usuario lo verificó, el dinero llega de inmediato a su cuenta, aunque el otro dato de contacto no coincida con nadie. `recipientId` no se puede combinar con un correo electrónico ni con un teléfono, y `linkOnly` no se puede combinar con ningún destinatario. No puedes enviar a la cuenta del propio remitente. Un envío que llegaría de inmediato pero no puede hacerlo, por ejemplo porque la cuenta del destinatario no puede recibir pagos o porque el monto supera un límite, falla con un error. Fluz no lo retiene en su lugar. ## Enviar dinero La misma mutación cubre todos los tipos de envío. Solo cambia la entrada. ```graphql Mutation theme={null} mutation SendMoney($input: SendMoneyInput!) { sendMoney(input: $input) { result transferId destinationAccountId shareRequestId claimLink claimStatus } } ``` ### A una dirección de correo electrónico o un número de teléfono ```json Variables theme={null} { "input": { "idempotencyKey": "6f2b8c1e-4d3a-4f7b-9a21-3c5e8d9f0a12", "amount": 25, "sourceCashBalanceId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed", "recipientEmail": "alex@example.com", "memo": "Dinner on Friday" } } ``` ```json Response (held) theme={null} { "data": { "sendMoney": { "result": "PENDING_CLAIM", "transferId": "c56a4180-65aa-42ec-a945-5fd21dec0538", "destinationAccountId": null, "shareRequestId": "0b8f2a5e-7c41-4d9e-8f3a-2e6b9c1d4a70", "claimLink": "https://fluz-links.short.gy/Xy7Kq2", "claimStatus": "PENDING" } } } ``` ```json Response (sent) theme={null} { "data": { "sendMoney": { "result": "SENT", "transferId": "c56a4180-65aa-42ec-a945-5fd21dec0538", "destinationAccountId": "a2c02ec6-357b-41cf-9229-4da34e727019", "shareRequestId": null, "claimLink": null, "claimStatus": null } } } ``` `claimLink` es un enlace corto a la página de reclamo. Úsalo tal como se devuelve, sin construirlo ni analizarlo. Para enviar a un número de teléfono, pasa `recipientPhone` en formato E.164, como `+14155551234`, en lugar de `recipientEmail`. ### A una cuenta de Fluz Pasa el id de la cuenta del destinatario. El envío llega de inmediato o se rechaza. ```json Variables theme={null} { "input": { "idempotencyKey": "3d1f9a7c-2b5e-4c8d-a6f0-7e9b1c2d3a45", "amount": 40.5, "sourceCashBalanceId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed", "recipientId": "a2c02ec6-357b-41cf-9229-4da34e727019" } } ``` ### Como enlace de reclamo Activa `linkOnly` y entrega `claimLink` tú mismo, por ejemplo en tu propia app o mensaje. ```json Variables theme={null} { "input": { "idempotencyKey": "9a4e2c7b-1f3d-4b6a-8c5e-0d2f4a6b8c1e", "amount": 15, "sourceCashBalanceId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed", "linkOnly": true } } ``` > [!WARNING] > > **Trata el enlace de reclamo como una contraseña.** > > Cualquier persona que tenga el `claimLink` de un envío solo con enlace puede reclamar el dinero una vez que pase la verificación de identidad. Su `shareRequestId` es igual de sensible, porque con él se puede acceder a la página de reclamo. Mantén ambos fuera de los registros y de las analíticas. ## Campos de entrada [`SendMoneyInput`](https://docs.fluz.app/api-reference/types/send-money-input) | Campo | Tipo | Obligatorio | Descripción | | :- | :- | :- | :- | | `idempotencyKey` | `UUID!` | Sí | Un UUID que generas para cada envío nuevo. Consulta [Idempotencia](#idempotencia). | | `amount` | `Float!` | Sí | Mayor que 0, como máximo 1,000,000, con un máximo de dos decimales. | | `sourceCashBalanceId` | `UUID!` | Sí | El `userCashBalanceId` de la cuenta de gasto que paga, obtenido de [`getUserCashBalances`](https://docs.fluz.app/features/get-spend-accounts), que requiere el scope `LIST_PAYMENT`. Debe ser una cuenta de gasto activa de la cuenta del token. | | `recipientEmail` | `String` | Elige uno | La dirección de correo electrónico del destinatario. | | `recipientPhone` | `String` | Elige uno | El número de teléfono del destinatario en formato E.164. | | `recipientId` | `UUID` | Elige uno | El id de la cuenta de Fluz del destinatario. | | `linkOnly` | `Boolean` | Elige uno | `true` para obtener un enlace de reclamo sin destinatario designado. | | `memo` | `String` | No | Una nota para el destinatario, de máximo 255 caracteres. No puede empezar con `=`, `+`, `-`, `@`, una tabulación ni un retorno de carro, ni siquiera después de espacios en blanco iniciales. | | `daysUntilExpiration` | `Int` | No | Días durante los que se puede reclamar un envío retenido, de 1 a 365. El valor predeterminado es 30. | Dirige el envío con `recipientEmail`, `recipientPhone` o ambos, con `recipientId` o con `linkOnly`. En un envío retenido, el memo aparece en la página de reclamo, donde cualquiera que abra el enlace puede leerlo, incluso después de que el envío se reclame o se devuelva. No incluyas datos personales en él. ## Campos de respuesta [`SendMoneyResponse`](https://docs.fluz.app/api-reference/types/send-money-response) | Campo | Tipo | Descripción | | :- | :- | :- | | `result` | `MoneySendResult!` | `SENT` o `PENDING_CLAIM`. | | `transferId` | `UUID` | La transferencia que movió el dinero, o que lo retiene mientras el envío está en espera. | | `destinationAccountId` | `UUID` | La cuenta que recibió el dinero. Solo tiene valor cuando `result` es `SENT`. | | `shareRequestId` | `UUID` | Identifica un envío retenido. Pásalo a `cancelMoneySend`. Solo tiene valor cuando `result` es `PENDING_CLAIM`. Abre la página de reclamo igual que `claimLink`, así que mantenlo fuera de los registros y de las analíticas. | | `claimLink` | `String` | El enlace que el destinatario abre para reclamar. Se devuelve solo mientras `claimStatus` es `PENDING`. | | `claimStatus` | `MoneySendClaimStatus` | En qué estado se encuentra ahora un envío retenido. Consulta [Seguimiento de un envío retenido](#seguimiento-de-un-envío-retenido). | ## Qué hace el destinatario El reclamo ocurre en una página de Fluz, no a través de la API. **1. Abrir el enlace** Fluz envía el enlace de reclamo a la dirección de correo electrónico o al número de teléfono a los que dirigiste el envío. En un envío solo con enlace, tú lo entregas. **2. Iniciar sesión o crear una cuenta de Fluz** El dinero va a la cuenta con la que haya iniciado sesión al reclamar, ya sea personal o empresarial. **3. Verificar su identidad** La cuenta debe aprobar KYC si es personal o KYB si es empresarial, y poder recibir pagos. **4. Confirmar el dato de contacto** En un envío a un número de teléfono, el teléfono de su cuenta de Fluz debe coincidir con él y estar verificado. En un envío a una dirección de correo electrónico, Fluz envía un código de 6 dígitos a esa dirección. Si enviaste a ambos, basta con un teléfono verificado que coincida. Si el teléfono de su cuenta coincide pero no está verificado, primero lo verifican. De lo contrario, ingresan el código del correo. Un envío solo con enlace solo necesita el enlace. La página de reclamo muestra el monto, el nombre del remitente y el memo a cualquiera que abra el enlace, antes de que inicie sesión. Cuando alguien reclama, Fluz vuelve a revisar la cuenta del remitente. Si ya no pasa KYC o KYB, o si Fluz la ha restringido, el reclamo se rechaza y el dinero permanece retenido hasta que canceles el envío o este venza. Desactivar el envío de dinero de una cuenta no impide que se reclamen sus envíos retenidos, así que cancela los que quieras detener. ## Seguimiento de un envío retenido Para ver en qué estado se encuentra un envío retenido, vuelve a llamar a `sendMoney` con el mismo `idempotencyKey` y la misma entrada. La respuesta repite el resultado y los ids originales con el `claimStatus` actual, incluye `claimLink` solo mientras `claimStatus` es `PENDING` y no mueve dinero. | `claimStatus` | Significado | | :- | :- | | `PENDING` | Esperando al destinatario. Puedes cancelarlo. | | `CLAIMING` | Reservado. Un reclamo pasa un envío directamente de `PENDING` a `CLAIMED`. | | `CLAIMED` | El destinatario lo reclamó y el dinero está en su saldo. | | `RETURNED` | Venció o se canceló, y el dinero regresó al remitente. | La llamada repetida ejecuta las mismas verificaciones de scope, rol y cuenta de gasto que un envío nuevo, por lo que se rechaza si el usuario ya no es propietario ni administrador, o si tu aplicación ya no puede usar la cuenta de gasto. ## Cancelar un envío retenido [`cancelMoneySend`](https://docs.fluz.app/api-reference/mutations/cancel-money-send) cancela un envío mientras su `claimStatus` es `PENDING` y devuelve el dinero al saldo en efectivo del que salió. Un envío `SENT` no se puede cancelar. ```graphql Mutation theme={null} mutation CancelMoneySend($shareRequestId: UUID!, $idempotencyKey: UUID!) { cancelMoneySend(shareRequestId: $shareRequestId, idempotencyKey: $idempotencyKey) { cancelled transferId } } ``` ```json Variables theme={null} { "shareRequestId": "0b8f2a5e-7c41-4d9e-8f3a-2e6b9c1d4a70", "idempotencyKey": "4c7e1a9b-6d2f-4e8a-b3c5-1f9d7a2e6b40" } ``` ```json Response theme={null} { "data": { "cancelMoneySend": { "cancelled": true, "transferId": "c56a4180-65aa-42ec-a945-5fd21dec0538" } } } ``` Cancelar requiere el mismo scope, y el usuario del token debe ser propietario o administrador de la cuenta que envía. Puedes cancelar cualquier envío retenido de la cuenta, incluido uno que haya enviado otro usuario u otra aplicación. Una cancelación rechazada se devuelve como un error, así que `cancelled` siempre es `true`. Si el mismo usuario repite una cancelación exitosa del mismo envío con el mismo `idempotencyKey` dentro de 24 horas, recibe la misma respuesta. Una cancelación rechazada no se guarda, así que una repetición la vuelve a ejecutar. ## Vencimiento Un envío retenido se puede reclamar hasta el final del día, hora del Este, `daysUntilExpiration` días después de haberse enviado. La respuesta no incluye esa fecha, así que regístrala cuando envíes. Después de eso, los reclamos se rechazan, y Fluz devuelve el dinero al saldo en efectivo del remitente a la mañana siguiente, en un proceso diario a las 9:00, hora del Este. Hasta que se devuelve el dinero, `claimStatus` sigue mostrando `PENDING` y todavía puedes cancelar el envío. ## Idempotencia `sendMoney` y `cancelMoneySend` reciben un `idempotencyKey`, un UUID que generas tú. No importa si usas mayúsculas o minúsculas. * Una repetición con la misma clave y la misma entrada devuelve el envío original, no mueve dinero y muestra en qué estado está el envío ahora. * Una clave queda ligada a su envío. Fluz responde las repeticiones desde una caché durante 24 horas y, después de ese plazo, desde el propio envío, así que una misma clave nunca genera dos envíos. Usa una clave nueva para cada envío nuevo. * Una repetición que cambia el monto, el saldo en efectivo o el destinatario, o que establece `linkOnly` en una clave usada para un destinatario, se rechaza con `ARG-0001`. Nunca reutilices una clave de otra operación: una usada con `createTransfer` crea un envío nuevo, y una usada para un pago externo solo se rechaza si la clave de ese pago estaba en minúsculas. * `memo` y `daysUntilExpiration` no se comparan. Una repetición que cambia solo esos campos devuelve el envío original sin cambios. * Las claves de `sendMoney` pertenecen a la cuenta, no a tu aplicación. La misma clave y entrada de otra aplicación o de otro usuario de la cuenta devuelve el envío original. * Si un envío falla antes de que se mueva dinero, por ejemplo porque el saldo es insuficiente, la clave queda libre. Corrige la causa y reintenta con la misma clave. `G-0409` significa que Fluz todavía está procesando esa clave, o que se perdió su respuesta. Es posible que el envío se haya completado, así que reintenta con la misma clave y la misma entrada hasta obtener un resultado. Una solicitud en curso retiene su clave hasta por 10 minutos. ## Límites Los envíos cuentan para los límites de transferencia de la cuenta: totales diarios, semanales, mensuales y anuales, además de un mínimo y un máximo por envío. Un envío retenido cuenta desde que se envía hasta que se devuelve el dinero. Los límites de recepción del destinatario se aplican cuando el dinero llega: al enviar, en un envío inmediato, y al reclamar, en uno retenido. Pide a tu equipo de cuenta los límites de tu cuenta. ## Errores Los errores regresan en el arreglo `errors` de GraphQL con `sendMoney` o `cancelMoneySend` establecido en `null`. Basa tu lógica en `extensions.code`. Los mensajes `ARG-` y `G-0003` indican el motivo específico. Los demás mensajes pueden cambiar. | Código | Cuándo ocurre | | :- | :- | | `AUTH-0002` | La solicitud usó Basic Auth. Usa un token de acceso de usuario Bearer. | | `AUTH-0031` | El token no tiene `MAKE_PAYOUT_TRANSFER_SEND`, o tu aplicación no puede usar ese saldo en efectivo. | | `AUTH-0008` | El usuario del token no es propietario ni administrador de la cuenta. | | `G-0003` | `Account is not enabled for money sends`: Fluz no ha habilitado el envío de dinero para la cuenta. | | `G-0003` | `Sender is not authorized to send a payment.`: la cuenta no ha pasado KYC o KYB. | | `G-0003` | `Recipient is not able to receive payments`: la cuenta a la que enviaste con `recipientId` no puede recibir pagos, o el envío superaría sus límites de recepción. No se da ningún motivo. | | `ARG-0001`, `ARG-0002` | La entrada no es válida, y el mensaje indica el problema. Esto incluye un envío a la cuenta del propio remitente, un dato de contacto que coincide con más de un usuario y una clave reutilizada con una entrada distinta. | | `PT-0007` | El saldo en efectivo no tiene fondos suficientes para cubrir el monto. | | `PT-0008` | Parte del saldo de una cuenta personal aún está en proceso de compensación y no se puede enviar todavía. | | `US-0042` | `sourceCashBalanceId` no es una de las cuentas de gasto de la cuenta. Un id que no existe puede devolver `ARG-0001` en su lugar. | | `CASH-0002` | El destinatario no tiene un saldo en efectivo que pueda recibir este envío. | | `FLUZ-0113` | La cuenta del remitente no puede enviar dinero en este momento. | | `FLUZ-0131`, `FLUZ-0140`, `FLUZ-0132`, `FLUZ-0141` | El envío superaría el límite diario, semanal, mensual o anual. | | `FLUZ-0142`, `FLUZ-0143` | El monto está por debajo del mínimo o por encima del máximo por envío. | | `G-0409` | La clave sigue en curso o se perdió su respuesta. Reintenta con la misma clave y entrada. | | `G-0010` | Falló un servicio de Fluz al preparar al destinatario de un envío a un correo electrónico o número de teléfono. No se movió dinero. Reintenta con la misma clave y entrada, y contacta a tu equipo de cuenta si sigue fallando. | | `G-0004` | Falló algo inesperado, o la cuenta de gasto no está activa. Reintenta con la misma clave y entrada, y revisa la cuenta de gasto si sigue fallando. | Un envío que llega de inmediato también pasa por el filtro antifraude de Fluz, que puede rechazarlo con otros códigos. En un envío a `recipientEmail` o `recipientPhone`, un código de límite `FLUZ-` también puede referirse al límite de recepción del destinatario. Un token ausente, no válido o revocado se rechaza antes de que se ejecute la operación, con HTTP 401, o con HTTP 498 si ya venció, y sin un arreglo `errors` de GraphQL. Para `cancelMoneySend`: | Código | Mensaje | Cuándo ocurre | | :- | :- | :- | | `ARG-0001` | `Money send not found` | El id no corresponde a un envío de dinero. | | `G-0003` | `You are not the sender of this money send` | El envío provino de otra cuenta. | | `G-0003` | `Money send is not cancellable (status USED)` | El destinatario ya lo reclamó. | | `G-0003` | `Money send is not cancellable (status EXPIRED)` | Ya se había cancelado o devuelto. | | `G-0003` | `Money send escrow was settled concurrently` | El dinero retenido ya se liquidó, pero el envío sigue en `PENDING`. Contacta a tu equipo de cuenta con el `shareRequestId`. | ## Referencia * [`sendMoney`](https://docs.fluz.app/api-reference/mutations/send-money) y [`SendMoneyInput`](https://docs.fluz.app/api-reference/types/send-money-input) * [`SendMoneyResponse`](https://docs.fluz.app/api-reference/types/send-money-response), [`MoneySendResult`](https://docs.fluz.app/api-reference/types/money-send-result) y [`MoneySendClaimStatus`](https://docs.fluz.app/api-reference/types/money-send-claim-status) * [`cancelMoneySend`](https://docs.fluz.app/api-reference/mutations/cancel-money-send) y [`CancelMoneySendResponse`](https://docs.fluz.app/api-reference/types/cancel-money-send-response) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.