Create Wallet Transfer to Another Fluz Account

"Requirement: Your application must be a public app."

Quick Start

Send $10 from a user to your application:

mutation {
  createTransfer(input: {
    idempotencyKey: "550e8400-e29b-41d4-a716-446655440000"
    amount: 10
  }) {
    success
    message
    transferId
  }
}

Authorization: Bearer <user-oauth-token>

Send $10 from your application to a user:

mutation {
  createTransfer(input: {
    idempotencyKey: "550e8400-e29b-41d4-a716-446655440001"
    amount: 10.00
    destination: {
      accountId: "c3d4e5f6-a7b8-9012-cdef-345678901234"
    }
  }) {
    success
    message
    transferId
  }
}

Authorization: Basic <Api-Key>

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

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

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)

mutation {
  createTransfer(input: {
    idempotencyKey: "550e8400-e29b-41d4-a716-446655440000"
    amount: 100.00
  }) {
    success
    message
    transferId
  }
}

Authorization: Bearer <user-oauth-token>

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)

mutation {
  createTransfer(input: {
    idempotencyKey: "550e8400-e29b-41d4-a716-446655440001"
    amount: 50.00
    destination: {
      accountId: "c3d4e5f6-a7b8-9012-cdef-345678901234"
    }
  }) {
    success
    message
    transferId
  }
}

Authorization: Basic <API-Key>

Use externalReferenceId instead of accountId to identify the recipient by the ID you assigned.

Transfer between two users (Bearer)

mutation {
  createTransfer(input: {
    idempotencyKey: "550e8400-e29b-41d4-a716-446655440002"
    amount: 25.00
    destination: {
      accountId: "b2c3d4e5-f6a7-8901-bcde-f23456789012"
    }
  }) {
    success
    message
    transferId
  }
}

Authorization: Bearer <user-oauth-token>

Success response

{
  "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:

{
  "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.