> ## 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. # Create Wallet Transfer to Another Fluz Account Move funds between your application's balance and your users' balances, or between two users. > "Requirement: Your application must be a public app." ## Quick Start Send $10 from a user to your application: ```graphql mutation { createTransfer(input: { idempotencyKey: "550e8400-e29b-41d4-a716-446655440000" amount: 10 }) { success message transferId } } ``` ``` Authorization: Bearer ``` Send $10 from your application to a user: ```graphql mutation { createTransfer(input: { idempotencyKey: "550e8400-e29b-41d4-a716-446655440001" amount: 10.00 destination: { accountId: "c3d4e5f6-a7b8-9012-cdef-345678901234" } }) { success message transferId } } ``` ``` Authorization: Basic ``` *** ## Authentication Transfers support two authentication methods. The method you choose determines who the sender is. | Method | Sender | Use case | | :----------- | :--------------- | :----------------------------------------------------------------------- | | Bearer token | The user | Collecting payments from users (user → you) or moving funds between user | | Basic Auth | Your application | Disbursing funds to users (you → user) | ### Bearer Token Use a user OAuth token obtained via `generateUserAccessToken` or through the [OAuth refresh flow.](https://docs.fluz.app/update/docs/using-oauth) The token must include the `MAKE_PAYOUT_TRANSFER_SEND` scope. ### Basic Auth Use your application's Api Key. *** ## Input ### CreateTransferInput | Field | Type | Required | Description | | :------------------ | :------------------ | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------- | | idempotencyKey | String! | Yes | A unique UUID you generate to prevent duplicate transfers. Resubmitting the same key returns the original result. | | amount | Float! | Yes | Amount to transfer. Must be positive.. | | destination | TransferDestination | Depends | Who receives the funds. **Required for Basic Auth**. For Bearer token, defaults to your application if omitted. | | bankCardId | UUID | No | Fund the transfer from the user's linked bank card instead of their cash balance. Bearer token only.. | | bankAccountId | UUID | No | Fund the transfer via ACH from the user's bank account. Bearer token only.. | | paypalVaultId | UUID | No | Fund the transfer from the user's linked PayPal. Bearer token only.. | | memo | String | No | Free-text note to attach to this transaction. Max 255 characters. | | transactionCategory | String | No | Category label to attach to this transaction. Free-form — categories are created automatically on first use. | | attachmentId | UUID | No | ID of a previously uploaded file (PDF or PNG) to attach to this transaction. Upload the file first using the transaction memo attachment endpoint. | > "Only one funding source can be specified per request. If none is provided, the transfer draws from the sender's cash balance. > > Funding sources are not available with Basic Auth." 📘 See [Annotate a Transaction](./annotate-a-transaction) for full details on uploading attachments and working with memos and categories. ### TransferDirection Identify the recipient by account ID or by the external reference ID you assigned when creating the user. Provide one or the other, not both. | Field | Type | Required | Description | | :------------------ | :----- | :------- | :--------------------------------------------------------------------------------------------------------------------------------- | | accountId | UUID | Yes | The recipient's Fluz account ID.. | | externalReferenceId | String | Yes | The external reference ID you assigned to the user in your system.. | | userCashBalanceId | UUID | Depends | Optional. Target a specific cash balance on the recipient's account. If omitted, the system selects the correct one automatically. | > "The recipient must be a registered user of your application." *** ## Response | Field | Type | Description | | :--------- | :------- | :---------------------------------------------------------- | | success | Boolean! | Whether the transfer completed. | | message | String! | Human-readable result description. | | transferId | UUID | The transfer's unique ID. Present when `success` is `true`. | *** ## Examples ### Collect payment from a user (Bearer) ```graphql mutation { createTransfer(input: { idempotencyKey: "550e8400-e29b-41d4-a716-446655440000" amount: 100.00 }) { success message transferId } } ``` ``` Authorization: Bearer ``` No destination needed -- defaults to your application. Optionally include `bankCardId`, `bankAccountId`, or `paypalVaultId` to fund from an external source instead of the user's cash balance. ### Disburse funds to a user (Basic Auth) ```graphql mutation { createTransfer(input: { idempotencyKey: "550e8400-e29b-41d4-a716-446655440001" amount: 50.00 destination: { accountId: "c3d4e5f6-a7b8-9012-cdef-345678901234" } }) { success message transferId } } ``` ``` Authorization: Basic ``` Use `externalReferenceId` instead of `accountId` to identify the recipient by the ID you assigned. ### Transfer between two users (Bearer) ```graphql mutation { createTransfer(input: { idempotencyKey: "550e8400-e29b-41d4-a716-446655440002" amount: 25.00 destination: { accountId: "b2c3d4e5-f6a7-8901-bcde-f23456789012" } }) { success message transferId } } ``` ``` Authorization: Bearer ``` ### Success response ```json { "data": { "createTransfer": { "success": true, "message": "Transfer created successfully.", "transferId": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } } } ``` *** ## Idempotency Every request must include a unique `idempotencyKey` (a string you generate). If the same key is sent more than once, the API returns the result of the original request without creating a duplicate transfer. Keys are valid for 10 minutes. *** ## Errors Errors follow the standard GraphQL error format: ```json { "errors": [ { "message": "Amount must be positive.", "extensions": { "code": "ARG-0001", "name": "InvalidArguments", "status_code": 422 } } ] } ``` ### Common Error | Error | Cause | | :-------------------------------------------------------- | :-------------------------------------------------------------------------------- | | Missing idempotencyKey or amount | Required fields not provided. | | Amount must be positive | Amount is zero or negative. | | Destination is required when using Basic auth | Basic Auth requests must specify a destination. | | Funding sources are not supported when using Basic auth | Remove `bankCardId` / `bankAccountId` / `paypalVaultId` from Basic Auth requests. | | Only one funding source is allowed at a time | Multiple funding sources were provided. Pass only one. | | Provide either accountId or externalReferenceId, not both | Destination has both identifiers. Use one. | | Destination account has not authorized this application | The recipient is not a registered user of your application. | | No user found with this external reference ID | The `externalReferenceId` doesn't match any user in your application. | | User does not have a cash balance configured | The sender or recipient doesn't have a cash balance on the required sponsor bank. | | Basic auth is not supported for personal applications | Upgrade your application to `ACTIVE` status to use Basic Auth transfers. | | Insufficient balance | The sender's cash balance is less than the transfer amount. |