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

# 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

> [!NOTE]
>
> 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](https://docs.fluz.app/features/move-funds-with-external-accounts.md). Para enviar dinero a otra cuenta de Fluz, usa [Transferencias de cuenta a cuenta](https://docs.fluz.app/features/account-to-account-transfers.md).

***

### createExternalPayee

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

#### Mutación (CreateExternalPayeeInput)

```graphql theme={null}
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

```graphql theme={null}
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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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

```graphql theme={null}
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

```graphql theme={null}
query {
  externalPayees(paginate: { limit: 10, offset: 0 }) {
    externalPayees {
      externalPayeeId
      holderName
      nickname
      destinationAccountNumberLastFour
    }
    totalCount
    hasNextPage
  }
}
```

**Éxito:**

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

**Sin beneficiarios:**

```json theme={null}
{
  "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`](https://docs.fluz.app/features/external-payouts), usando el `externalPayeeId` y un saldo en efectivo de origen.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.