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

# 使用回饋金支付

> 在 createTransfer 或 requestAccountTransfer 中傳入 useRewardsBalance,即可使用寄件者的回饋金餘額(可單獨使用,或搭配現金餘額)向 Fluz 帳戶轉帳。

設定 `useRewardsBalance: true`,即可讓寄件者在向 Fluz 帳戶轉帳時使用其**回饋金餘額**付款。Fluz 會先扣除寄件者的現金,不足的部分再使用回饋金。如果寄件者沒有可用現金,則整筆金額都從回饋金支付。

此功能適用於兩個操作:

| 操作 | 輸入 | 範圍 | 驗證 |
| :- | :- | :- | :- |
| [`createTransfer`](https://docs.fluz.app/features/send-to-a-fluz-account) | `CreateTransferInput` | `MAKE_PAYOUT_TRANSFER_SEND` | Bearer 權杖,或在 `ACTIVE` 公開應用程式上使用 Basic Auth |
| [`requestAccountTransfer`](https://docs.fluz.app/features/request-account-transfer-approval) | `RequestAccountTransferInput` | `REQUEST_ACCOUNT_TRANSFER` | 與 `createTransfer` 相同 |

轉帳的其他部分,例如目的地、驗證與冪等性,皆與[匯款](https://docs.fluz.app/features/send-to-a-fluz-account)中所述相同。

> [!NOTE]
>
> **回饋金僅能用於向 Fluz 帳戶轉帳。**
>
> * `sendMoney` 與 `createExternalPayout` 僅能使用現金餘額。
> * 若要將回饋金轉入使用者自己的銀行帳戶,請使用 [`withdrawCashBalance`](https://docs.fluz.app/features/withdraw-to-external-account) 並設定 `source: REWARDS_BALANCE`。每次提領請求只能指定一種來源,現金或回饋金,不能同時使用。
> * 預付款/禮品卡餘額無法用於任何轉帳。

***

## useRewardsBalance

`useRewardsBalance: Boolean` 在兩種輸入中皆為選填。

| 值 | 資金來源 |
| :- | :- |
| 省略或 `false` | 僅使用寄件者的消費帳戶。此為預設值。 |
| `true` | 先使用寄件者的消費帳戶,最多至轉帳金額,其餘由回饋金支付。若消費帳戶沒有可用現金,則整筆金額都從回饋金支付。 |

收款人一律會將款項收入消費帳戶。您無法將款項轉入他人的回饋金餘額。

***

## createTransfer

```graphql theme={null}
mutation {
  createTransfer(input: {
    idempotencyKey: "550e8400-e29b-41d4-a716-446655440010"
    amount: 25.00
    useRewardsBalance: true
    destination: {
      accountId: "b2c3d4e5-f6a7-8901-bcde-f23456789012"
    }
  }) {
    success
    message
    transferId
  }
}
```

```text theme={null}
Authorization: Bearer <user-access-token>
```

這與僅使用現金的轉帳相同,只是多加了 `useRewardsBalance: true`。

### 搭配已連結的資金來源

`bankCardId`、`bankAccountId` 與 `paypalVaultId` 仍可搭配 Bearer 權杖使用,每次請求限用一個。Fluz 會先從該來源存入寄件者的消費帳戶,而 `useRewardsBalance` 仍會套用於該筆轉帳。

***

## requestAccountTransfer

`requestAccountTransfer` 會將轉帳送交核准,而不是立即轉出。請在請求中傳入 `useRewardsBalance`,核准者核准時便會使用該設定。

```graphql theme={null}
mutation {
  requestAccountTransfer(input: {
    idempotencyKey: "550e8400-e29b-41d4-a716-446655440011"
    amount: 25.00
    useRewardsBalance: true
    destination: {
      accountId: "b2c3d4e5-f6a7-8901-bcde-f23456789012"
    }
  }) {
    success
    messageId
    error {
      code
      message
    }
  }
}
```

使用 `approveApprovalRequest` 或 `declineApprovalRequest` 來核准或拒絕,這兩者需要 `MANAGE_APPROVALS`。請參閱[請求帳戶轉帳核准](https://docs.fluz.app/features/request-account-transfer-approval.md)。

***

## 錯誤

錯誤會以標準 GraphQL 格式回傳。當轉帳無法完成時,`createTransfer` 會回傳 `null`。

```json theme={null}
{
  "data": {
    "createTransfer": null
  },
  "errors": [
    {
      "message": "Insufficient funds",
      "extensions": {
        "code": "WDR-0001",
        "name": "InsufficientBalanceError",
        "status_code": 400
      }
    }
  ]
}
```

| 代碼 | 時機 |
| :- | :- |
| `WDR-0001` | 現金加回饋金,或僅回饋金,無法涵蓋該金額。不會進行任何轉帳。 |
| 其他 `createTransfer` 錯誤 | 一般的目的地、驗證、冪等性與資金來源規則仍然適用。請參閱[匯款](https://docs.fluz.app/features/send-to-a-fluz-account#errors)。 |

請參閱 API 參考中的 [`createTransfer`](https://docs.fluz.app/api-reference/mutations/create-transfer) 與 [`CreateTransferInput`](https://docs.fluz.app/api-reference/types/create-transfer-input)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.