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

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

Sample Mutation — Application to User

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

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

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.

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

No transfer is executed when a request is declined.