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

# Request Account Transfer Approval

`requestAccountTransfer`

Submit a manager approval request for an account-to-account transfer. When approved, Fluz executes the transfer using the same semantics as `createTransfer`.

Use this when a user or application needs manager sign-off before moving funds between Fluz accounts. For transfers between spend accounts on the same account, use `requestInternalTransfer` instead.

## Scopes

| Action             | Scope                      |
| ------------------ | -------------------------- |
| Create request     | `REQUEST_ACCOUNT_TRANSFER` |
| List requests      | `LIST_APPROVALS`           |
| Approve or decline | `MANAGE_APPROVALS`         |

## Webhook Identifiers

| Field          | Value    |
| -------------- | -------- |
| `approvalType` | `PAYOUT` |
| `approvalCode` | `500402` |

Webhook events: `APPROVAL_CREATE`, `APPROVAL_APPROVE`, `APPROVAL_DECLINE`, and `APPROVAL_HANDLER_ERROR` on execution failure.

> Internal transfers and account transfers share the same `approvalType` and `approvalCode`. Use the original request mutation or inspect the approval payload in your integration to distinguish them.

## Create a Request

Input mirrors [Create Wallet Transfer to Another Fluz Account](https://docs.fluz.app/docs/application-transfer.md). The sender is determined from authentication; destination and funding sources follow the same rules as `createTransfer`.

### RequestAccountTransferInput

| Field                 | Type                | Required | Description                                                                                    |
| --------------------- | ------------------- | -------- | ---------------------------------------------------------------------------------------------- |
| `idempotencyKey`      | UUID                | Yes      | Unique key to prevent duplicate transfers on approval                                          |
| `amount`              | Float               | Yes      | Amount to transfer. Must be greater than zero                                                  |
| `destination`         | TransferDestination | Depends  | Recipient account. Required for Basic Auth; optional for Bearer (defaults to your application) |
| `bankCardId`          | UUID                | No       | Fund from a linked bank card. Bearer token only                                                |
| `bankAccountId`       | UUID                | No       | Fund via ACH. Bearer token only                                                                |
| `paypalVaultId`       | UUID                | No       | Fund from PayPal. Bearer token only                                                            |
| `memo`                | String              | No       | Transaction memo                                                                               |
| `transactionCategory` | String              | No       | Category label; created automatically on first use                                             |
| `attachmentId`        | String              | No       | ID of a previously uploaded transaction attachment                                             |

### TransferDestination

| Field                 | Type   | Description                                            |
| --------------------- | ------ | ------------------------------------------------------ |
| `accountId`           | UUID   | Recipient Fluz account ID                              |
| `externalReferenceId` | String | Recipient external reference ID from your system       |
| `userCashBalanceId`   | UUID   | Optional target spend account on the recipient account |

Provide either `accountId` or `externalReferenceId`, not both.

### Authentication Notes

| Method       | Sender             | Notes                                                                        |
| ------------ | ------------------ | ---------------------------------------------------------------------------- |
| Bearer token | Authenticated user | Funding sources allowed; destination optional (defaults to your application) |
| Basic Auth   | Your application   | Destination required; funding sources not allowed                            |

### Sample Mutation — User to Application

```graphql
mutation {
  requestAccountTransfer(
    input: {
      idempotencyKey: "550e8400-e29b-41d4-a716-446655440000"
      amount: 100.00
    }
  ) {
    success
    messageId
    error {
      code
      message
    }
  }
}
```

### Sample Mutation — Application to User

```graphql
mutation {
  requestAccountTransfer(
    input: {
      idempotencyKey: "550e8400-e29b-41d4-a716-446655440001"
      amount: 50.00
      destination: {
        accountId: "c3d4e5f6-a7b8-9012-cdef-345678901234"
      }
    }
  ) {
    success
    messageId
    error {
      code
      message
    }
  }
}
```

### Sample Response

```json
{
  "data": {
    "requestAccountTransfer": {
      "success": true,
      "messageId": "1234567890"
    }
  }
}
```

The `idempotencyKey` is preserved and used when the transfer executes on approval.

## Approve a Request

Call `approveApprovalRequest` with the `approvalId`. Requires `MANAGE_APPROVALS`.

```graphql
mutation {
  approveApprovalRequest(approvalId: "07df5653-43a8-4532-9881-3ab5857bbe12") {
    success
    approvalId
    action
  }
}
```

On approval, Fluz executes the account transfer.

## Decline a Request

Call `declineApprovalRequest` with the `approvalId`. Requires `MANAGE_APPROVALS`.

```graphql
mutation {
  declineApprovalRequest(approvalId: "07df5653-43a8-4532-9881-3ab5857bbe12") {
    success
    approvalId
    action
  }
}
```

No transfer is executed when a request is declined.