sendMoney 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.
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.
No es lo mismo que
createTransfer.createTransfer 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
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.Mutation
A una dirección de correo electrónico o un número de teléfono
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.Variables
Como enlace de reclamo
ActivalinkOnly y entrega claimLink tú mismo, por ejemplo en tu propia app o mensaje.
Variables
Campos de entrada
SendMoneyInput
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
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.
Seguimiento de un envío retenido
Para ver en qué estado se encuentra un envío retenido, vuelve a llamar asendMoney 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.
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 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.
Mutation
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
linkOnlyen una clave usada para un destinatario, se rechaza conARG-0001. Nunca reutilices una clave de otra operación: una usada concreateTransfercrea un envío nuevo, y una usada para un pago externo solo se rechaza si la clave de ese pago estaba en minúsculas. memoydaysUntilExpirationno se comparan. Una repetición que cambia solo esos campos devuelve el envío original sin cambios.- Las claves de
sendMoneypertenecen 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 arregloerrors 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.
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: