Application Transfer

Overview

The createTransfer mutation orchestrates balance transfers within the Fluz platform. It automatically infers the source and destination account IDs based on the OAuth token and application settings, simplifying the integration for API consumers.

Property	Value
Endpoint	GraphQL API
Authentication	OAuth Bearer Token
Required Scopes	`MAKE_PAYOUT_TRANSFER_SEND` and/or `MAKE_PAYOUT_TRANSFER_RECEIVE`

Required Scopes

The mutation requires specific OAuth scopes based on the transfer direction:

Direction	Required Scope	Description
`SEND`	`MAKE_PAYOUT_TRANSFER_SEND`	User sends funds or DEPOSITS funds to the operator
`RECEIVE`	`MAKE_PAYOUT_TRANSFER_RECEIVE`	User receives funds of WITHDRAWS funds from the operator

Note: The access token must include the appropriate scope for the direction of the transfer. A token with both scopes can perform transfers in either direction.

Input

CreateTransferInput

Field	Type	Required	Description
idemptokencyKey	String!	Yes	A unique client-generated string to ensure idempotent request processing. If the same key is submitted multiple times, only the first request will be processed.
direction	TransferDirection!	Yes	The direction of the transfer from the user's perspective.
amount	Float!	Yes	The amount to transfer. Must be a positive number.
bankCardId	UUID	No	Bank card ID to fund the transfer (SEND direction only).
bankAccountId	UUID	No	Bank account ID for ACH funding (SEND direction only).
paypalVaultId	UUID	No	PayPal vault ID for PayPal funding (SEND direction only).

TransferDirection Enum

Value	Description
`RECEIVE`	User is receiving money (operator -> user). The operator's balance is debited and the user's balance is credited. The user is making a WITHDRAWAL.
`SEND`	User is spending money (user -> operator). The user's balance is debited and the operator's balance is credited. The user is making a DEPOSIT.

Funding Source Rules

Funding source are only valid for SEND direction transfers
Only one funding source can be specified per request
When no funding source is provided, the transfer uses the user's existing Fluz Cash balance

Output

CreateTransferResponse

Field	Type	Description
success	Boolean!	Indicates whether the transfer was successful.
message	String!	A human-readable message describing the result.
transferId	UUID	The unique identifier for the created transfer. Only present when `success` is `true`.

Examples

Example 1: User Sends Funds to Operator (from Fluz Balance)

Request:

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

Response

{
  "data": {
    "createTransfer": {
      "success": true,
      "message": "Transfer created successfully.",
      "transferId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
    }
  }
}

Example 2: User Sends Funds to Operator (from Bank Card)

Request:

mutation {
  createTransfer(input: {
    idempotencyKey: "550e8400-e29b-41d4-a716-446655440001"
    direction: SEND
    amount: 250.00
    bankCardId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }) {
    success
    message
    transferId
  }
}

Response

{
  "data": {
    "createTransfer": {
      "success": true,
      "message": "Transfer created successfully.",
      "transferId": "8d0f7780-8536-51ef-055c-f18fd2g01bf8"
    }
  }
}

Example 3: Operator Sends Funds to User (RECEIVE)

Request:

mutation {
  createTransfer(input: {
    idempotencyKey: "550e8400-e29b-41d4-a716-446655440002"
    direction: RECEIVE
    amount: 50.00
  }) {
    success
    message
    transferId
  }
}

Response

{
  "data": {
    "createTransfer": {
      "success": true,
      "message": "Transfer created successfully.",
      "transferId": "9e1g8891-9647-62fg-166d-g29ge3h12cg9"
    }
  }
}

Error Handling

Error Response Format

All errors follow a standard GraphQL error format with extended error details:

{
  "errors": [
    {
      "message": "Error message here",
      "extensions": {
        "code": "ERROR_CODE",
        "name": "ErrorName",
        "status_code": 400
      }
    }
  ]
}

Common Error Codes

Code	Name	HTTP Status	Description
`ARG-0001`	InvalidArguments	422	Invalid arguments received (e.g., negative amounts, invalid direction)
`ARG-0002`	MissingArguments	422	Required arguments are missing
`AUTH-0031`	InvalidScope	403	The OAuth token doesn't have the required scope for the transfer direction
`CASH-0002`	UnableToRetrieveCashBalanceDeposit	400	User doesn't have a compatible cash balance configured for the operator's sponsor bank
`APPLICATIONS-0001`	ConfigurationError	422	Application settings are misconfigured (missing cash balance)