Beneficiarios externos

Se usa para guardar una cuenta bancaria externa como beneficiario, de modo que puedas enviarle dinero desde un saldo en efectivo de Fluz.

Descripción general

Un beneficiario externo es una cuenta bancaria de EE. UU. que pertenece a otra persona, por ejemplo, un contratista, un proveedor o un amigo. La guardas una vez en la cuenta y luego le envías pagos ACH con createExternalPayout usando su externalPayeeId. Por qué los beneficiarios se guardan primero:

Ingresa los datos bancarios una sola vez. El número de ruta y el número de cuenta completos se envían solo cuando creas el beneficiario. Después usas el externalPayeeId.
No se devuelven datos sensibles. Fluz almacena el número de cuenta de forma segura y devuelve solo los últimos cuatro dígitos.
Sin duplicados. Agregar de nuevo el mismo número de ruta y de cuenta devuelve el beneficiario existente.
Lista a nivel de cuenta. Los beneficiarios pertenecen a la cuenta de Fluz, por lo que todos los usuarios autorizados de esa cuenta ven la misma lista.

Dos operaciones administran los beneficiarios:

createExternalPayee - Agregar una cuenta bancaria como beneficiario
externalPayees - Listar los beneficiarios de la cuenta

Los beneficiarios externos sirven para enviar dinero a cuentas bancarias de otras personas. Para mover dinero a la cuenta bancaria del propio usuario, usa retiros. Para enviar dinero a otra cuenta de Fluz, usa Transferencias de cuenta a cuenta.

createExternalPayee

Agrega una cuenta bancaria externa como beneficiario en la cuenta del usuario autenticado.

Mutación (CreateExternalPayeeInput)

createExternalPayee(input: CreateExternalPayeeInput!): ExternalPayee

Requiere: alcance MAKE_PAYOUT_TRANSFER_SEND.

Entrada

Campo	Tipo	Requerido	Descripción
routingNumber	String!	Sí	El número de ruta ABA de 9 dígitos del banco de destino. Debe ser un número ABA válido.
accountNumber	String!	Sí	El número de cuenta de destino. Solo dígitos, de 4 a 17. Elimina los espacios y los guiones antes de enviarlo.
holderName	String!	Sí	El nombre que figura en la cuenta de destino. Máximo 255 caracteres. Debe contener al menos una letra o un dígito.
holderType	ExternalPayeeHolderType!	Sí	`INDIVIDUAL` o `BUSINESS`.
emailAddress	String!	Sí	La dirección de correo electrónico del titular de la cuenta. Fluz la usa para verificar si el destino pertenece a una cuenta de Fluz.
accountType	DepositAccountType	No	`CHECKING` o `SAVING`. El valor predeterminado es `CHECKING`.
nickname	String	No	Una etiqueta que se muestra en lugar del nombre del titular. Máximo 255 caracteres.

Respuesta (ExternalPayee)

Campo	Tipo	Descripción
externalPayeeId	ID!	El ID del beneficiario. Úsalo como `externalPayeeId` en `createExternalPayout`.
holderName	String!	El nombre que figura en la cuenta de destino
holderType	ExternalPayeeHolderType!	`INDIVIDUAL` o `BUSINESS`
nickname	String	La etiqueta, si se definió una
depositAccountType	DepositAccountType!	`CHECKING` o `SAVING`
achRoutingNumber	String!	El número de ruta ABA
destinationAccountNumberLastFour	String!	Los últimos cuatro dígitos del número de cuenta
emailAddress	String	La dirección de correo electrónico del titular de la cuenta
createdAt	DateTime!	Cuándo se agregó el beneficiario

Ejemplo

mutation {
  createExternalPayee(
    input: {
      routingNumber: "021000021"
      accountNumber: "123456789"
      holderName: "Jane Doe"
      holderType: INDIVIDUAL
      emailAddress: "jane@example.com"
      accountType: CHECKING
      nickname: "Jane - rent"
    }
  ) {
    externalPayeeId
    holderName
    nickname
    depositAccountType
    achRoutingNumber
    destinationAccountNumberLastFour
    createdAt
  }
}

Éxito:

{
  "data": {
    "createExternalPayee": {
      "externalPayeeId": "3f1c2b7e-8d4a-4c1e-9f2a-6b5d4e3c2a10",
      "holderName": "Jane Doe",
      "nickname": "Jane - rent",
      "depositAccountType": "CHECKING",
      "achRoutingNumber": "021000021",
      "destinationAccountNumberLastFour": "6789",
      "createdAt": "2026-10-20T15:30:00.000Z"
    }
  }
}

Entrada no válida:

{
  "errors": [
    {
      "message": "account_number must contain only digits",
      "extensions": { "code": "ARG-0001" }
    }
  ]
}

Códigos de error

Código	Descripción
ARG-0002	Falta un campo obligatorio
ARG-0001	Entrada no válida, por ejemplo un número de ruta o de cuenta incorrecto. También se devuelve cuando la cuenta bancaria pertenece a la propia cuenta de Fluz del usuario.
G-0003	El envío de dinero a cuentas bancarias externas no está habilitado en esta cuenta
G-0001	No se pudo agregar la cuenta bancaria, o se produjo un error del servidor

externalPayees

Lista los beneficiarios externos de la cuenta del usuario autenticado, del más reciente al más antiguo.

Consulta

externalPayees(paginate: OffsetInput): ExternalPayeeConnection!

Requiere: alcance MAKE_PAYOUT_TRANSFER_SEND.

Entrada (OffsetInput)

Campo	Tipo	Requerido	Descripción
limit	Int	No	Cantidad de beneficiarios por página. El valor predeterminado y máximo es 20.
offset	Int	No	Cantidad de beneficiarios que se omiten. El valor predeterminado es 0.

Respuesta (ExternalPayeeConnection)

Campo	Tipo	Descripción
externalPayees	[ExternalPayee]	Los beneficiarios de esta página. Mismos campos que la respuesta de `createExternalPayee`.
totalCount	Int!	Cantidad total de beneficiarios en la cuenta
hasNextPage	Boolean!	`true` si hay más beneficiarios disponibles después de esta página

Ejemplo

query {
  externalPayees(paginate: { limit: 10, offset: 0 }) {
    externalPayees {
      externalPayeeId
      holderName
      nickname
      destinationAccountNumberLastFour
    }
    totalCount
    hasNextPage
  }
}

Éxito:

{
  "data": {
    "externalPayees": {
      "externalPayees": [
        {
          "externalPayeeId": "3f1c2b7e-8d4a-4c1e-9f2a-6b5d4e3c2a10",
          "holderName": "Jane Doe",
          "nickname": "Jane - rent",
          "destinationAccountNumberLastFour": "6789"
        }
      ],
      "totalCount": 1,
      "hasNextPage": false
    }
  }
}

Sin beneficiarios:

{
  "data": {
    "externalPayees": {
      "externalPayees": [],
      "totalCount": 0,
      "hasNextPage": false
    }
  }
}

Códigos de error

Código	Descripción
G-0001	Error del servidor

Notas importantes

createExternalPayee

Solo se admiten cuentas bancarias de EE. UU. a las que se pueda llegar por ACH. El tipo de cuenta debe ser CHECKING o SAVING.
Agregar de nuevo el mismo número de ruta y de cuenta devuelve el beneficiario existente. No se crea ningún duplicado.
Si un beneficiario con el mismo número de ruta y de cuenta se eliminó antes, al agregarlo de nuevo se restaura con sus datos originales. Los valores nuevos de nombre, correo electrónico o alias de la solicitud no se aplican.
No puedes agregar una cuenta bancaria que pertenezca a la propia cuenta de Fluz del usuario autenticado.
Algunas cuentas bancarias no se pueden agregar. En ese caso, la solicitud falla con un error general.
El número de cuenta completo nunca se devuelve. Guarda el externalPayeeId, no los datos bancarios.

externalPayees

Devuelve los beneficiarios de toda la cuenta de Fluz, no solo los que agregó el usuario actual.
Los beneficiarios eliminados no aparecen en la lista.
Los resultados se ordenan del más reciente al más antiguo.

Siguiente paso

Envía dinero a un beneficiario con createExternalPayout, usando el externalPayeeId y un saldo en efectivo de origen.

​Descripción general

​createExternalPayee

​Mutación (CreateExternalPayeeInput)

​Entrada

​Respuesta (ExternalPayee)

​Ejemplo

​Códigos de error

​externalPayees

​Consulta

​Entrada (OffsetInput)

​Respuesta (ExternalPayeeConnection)

​Ejemplo

​Códigos de error

​Notas importantes

​createExternalPayee

​externalPayees

​Siguiente paso

Descripción general

createExternalPayee

Mutación (CreateExternalPayeeInput)

Entrada

Respuesta (ExternalPayee)

Ejemplo

Códigos de error

externalPayees

Consulta

Entrada (OffsetInput)

Respuesta (ExternalPayeeConnection)

Ejemplo

Códigos de error

Notas importantes

createExternalPayee

externalPayees

Siguiente paso