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

# 傳送款項

> 透過 sendMoney，將使用者現金餘額中的款項傳送到電子郵件地址、電話號碼、Fluz 帳戶或領取連結，並可取消無人領取的傳送。

使用 [`sendMoney`](https://docs.fluz.app/api-reference/mutations/send-money) 從使用者的 Fluz 現金餘額傳送款項。你可以將收款對象指定為電子郵件地址或電話號碼、Fluz 帳戶 ID，或不指定任何人，此時你會取得領取連結，由你自行傳遞。收款人不必是你應用程式的使用者，也不必已經擁有 Fluz 帳戶。

一筆傳送會以兩種結果之一收場。`SENT` 表示款項已進入收款人的餘額，且無法撤回。`PENDING_CLAIM` 表示 Fluz 先保留款項，直到收款人在 Fluz 頁面上領取。如果到期前無人領取，或你取消了這筆傳送，款項會退回給寄款方。你如何指定傳送對象，決定會出現哪一種結果。

> [!NOTE]
>
> **開始之前**
>
> * 請使用具備 `MAKE_PAYOUT_TRANSFER_SEND` 權限範圍的 Bearer 使用者存取權杖進行呼叫。不接受使用你的 API 金鑰進行的 Basic Auth。
> * 權杖所屬的使用者必須是該帳戶的擁有者或管理者。
> * Fluz 依帳戶逐一開通傳送款項功能。請聯絡你的 Fluz 客戶經理，為每個要傳送款項的帳戶啟用。
> * 帳戶必須已通過身分驗證：個人帳戶需通過 KYC，企業需通過 KYB。
> * 如果使用者已將你的應用程式限制在特定的消費帳戶，請從其中一個消費帳戶傳送。

> [!NOTE]
>
> **與 `createTransfer` 不同。**
>
> [`createTransfer`](https://docs.fluz.app/features/transfer-to-another-fluz-wallet) 在你應用程式的帳戶與已授權你應用程式的帳戶之間移轉資金，也能在兩個這類帳戶之間移轉。`sendMoney` 可以付款給任何能接收付款的 Fluz 帳戶，也能透過電子郵件或電話聯絡到對方。對於新的收款人，它會先保留款項，直到對方領取，並由 Fluz 將領取連結寄給對方。

## 款項如何送達

| 傳送對象 | 處理結果 |
| :- | :- |
| `recipientId` | 款項立即進入該帳戶（`SENT`）。如果該帳戶無法接收付款，這筆傳送會被拒絕，不會被保留。 |
| `recipientEmail` 或 `recipientPhone`，且有 Fluz 使用者已驗證該聯絡方式 | 款項立即進入該使用者的個人帳戶（`SENT`）。 |
| `recipientEmail` 或 `recipientPhone` 不符合任何 Fluz 使用者，或符合的使用者尚未驗證該聯絡方式 | Fluz 保留款項（`PENDING_CLAIM`），並將領取連結寄到你提供的聯絡方式給收款人。 |
| `linkOnly: true` | Fluz 保留款項（`PENDING_CLAIM`）並回傳 `claimLink`。Fluz 不會聯絡任何人，因此由你傳遞連結。 |

Fluz 會比對使用者 Fluz 個人資料中的電子郵件地址與電話號碼。如果任一項符合多位使用者，這筆傳送會被拒絕，你需要改用其他識別資訊。

你可以為同一個人同時傳入 `recipientEmail` 與 `recipientPhone`。如果兩者符合同一位使用者，以電話為準：只有在該使用者已驗證電話時，款項才會立即進入其帳戶。如果兩者符合兩位不同的使用者，Fluz 不會擇一處理，而是保留款項。如果只有其中一項符合某位使用者，則由該聯絡方式單獨決定：只要使用者已驗證它，款項就會立即進入其帳戶，即使另一個聯絡方式不符合任何人。

`recipientId` 不能與電子郵件或電話並用，`linkOnly` 也不能與任何收款人並用。你不能傳送到寄款方自己的帳戶。

如果一筆傳送本應立即進入帳戶卻無法完成，例如收款人的帳戶無法接收付款，或金額超過限額，這筆傳送會以錯誤失敗，Fluz 不會改為保留款項。

## 傳送款項

同一個 mutation 涵蓋所有類型的傳送，只有輸入內容不同。

```graphql Mutation theme={null}
mutation SendMoney($input: SendMoneyInput!) {
  sendMoney(input: $input) {
    result
    transferId
    destinationAccountId
    shareRequestId
    claimLink
    claimStatus
  }
}
```

### 傳送到電子郵件地址或電話號碼

```json Variables theme={null}
{
  "input": {
    "idempotencyKey": "6f2b8c1e-4d3a-4f7b-9a21-3c5e8d9f0a12",
    "amount": 25,
    "sourceCashBalanceId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
    "recipientEmail": "alex@example.com",
    "memo": "Dinner on Friday"
  }
}
```

```json Response (held) theme={null}
{
  "data": {
    "sendMoney": {
      "result": "PENDING_CLAIM",
      "transferId": "c56a4180-65aa-42ec-a945-5fd21dec0538",
      "destinationAccountId": null,
      "shareRequestId": "0b8f2a5e-7c41-4d9e-8f3a-2e6b9c1d4a70",
      "claimLink": "https://fluz-links.short.gy/Xy7Kq2",
      "claimStatus": "PENDING"
    }
  }
}
```

```json Response (sent) theme={null}
{
  "data": {
    "sendMoney": {
      "result": "SENT",
      "transferId": "c56a4180-65aa-42ec-a945-5fd21dec0538",
      "destinationAccountId": "a2c02ec6-357b-41cf-9229-4da34e727019",
      "shareRequestId": null,
      "claimLink": null,
      "claimStatus": null
    }
  }
}
```

`claimLink` 是指向領取頁面的短網址。請原樣使用回傳的連結，不要自行組合或解析。

若要傳送到電話號碼，請改為傳入 E.164 格式的 `recipientPhone`，例如 `+14155551234`，而不是 `recipientEmail`。

### 傳送到 Fluz 帳戶

傳入收款人的帳戶 ID。款項會立即進入該帳戶，否則這筆傳送會被拒絕。

```json Variables theme={null}
{
  "input": {
    "idempotencyKey": "3d1f9a7c-2b5e-4c8d-a6f0-7e9b1c2d3a45",
    "amount": 40.5,
    "sourceCashBalanceId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
    "recipientId": "a2c02ec6-357b-41cf-9229-4da34e727019"
  }
}
```

### 以領取連結傳送

設定 `linkOnly`，並自行傳遞 `claimLink`，例如放在你自己的應用程式或訊息中。

```json Variables theme={null}
{
  "input": {
    "idempotencyKey": "9a4e2c7b-1f3d-4b6a-8c5e-0d2f4a6b8c1e",
    "amount": 15,
    "sourceCashBalanceId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
    "linkOnly": true
  }
}
```

> [!WARNING]
>
> **請像對待密碼一樣保護領取連結。**
>
> 任何取得僅連結傳送之 `claimLink` 的人，只要通過身分驗證，就能領取這筆款項。它的 `shareRequestId` 同樣敏感，因為憑它就能進入領取頁面。請勿將兩者寫入日誌或分析工具。

## 輸入欄位

[`SendMoneyInput`](https://docs.fluz.app/api-reference/types/send-money-input)

| 欄位 | 類型 | 必填 | 說明 |
| :- | :- | :- | :- |
| `idempotencyKey` | `UUID!` | 是 | 你為每筆新傳送產生的 UUID。請參閱[冪等性](#冪等性)。 |
| `amount` | `Float!` | 是 | 必須大於 0，最多 1,000,000，小數最多兩位。 |
| `sourceCashBalanceId` | `UUID!` | 是 | 負責付款的消費帳戶的 `userCashBalanceId`，取自 [`getUserCashBalances`](https://docs.fluz.app/features/get-spend-accounts)（需要 `LIST_PAYMENT` 權限範圍）。它必須是權杖所屬帳戶下處於啟用狀態的消費帳戶。 |
| `recipientEmail` | `String` | 擇一 | 收款人的電子郵件地址。 |
| `recipientPhone` | `String` | 擇一 | 收款人的電話號碼，採 E.164 格式。 |
| `recipientId` | `UUID` | 擇一 | 收款人的 Fluz 帳戶 ID。 |
| `linkOnly` | `Boolean` | 擇一 | 設為 `true` 可取得不指定收件對象的領取連結。 |
| `memo` | `String` | 否 | 給收款人的備註，最多 255 個字元。不能以 `=`、`+`、`-`、`@`、Tab 字元或歸位字元開頭，即使前面有空白字元也不行。 |
| `daysUntilExpiration` | `Int` | 否 | 保留中的傳送可被領取的天數，1 到 365。預設為 30。 |

請使用 `recipientEmail`、`recipientPhone`（可兩者並用）、`recipientId` 或 `linkOnly` 其中一種方式指定傳送對象。

在保留中的傳送上，備註會顯示在領取頁面，任何開啟連結的人都能看到，即使傳送已被領取或退回也一樣。請勿在備註中放入個人資料。

## 回應欄位

[`SendMoneyResponse`](https://docs.fluz.app/api-reference/types/send-money-response)

| 欄位 | 類型 | 說明 |
| :- | :- | :- |
| `result` | `MoneySendResult!` | `SENT` 或 `PENDING_CLAIM`。 |
| `transferId` | `UUID` | 移動款項的轉帳，或在傳送等待期間保留款項的轉帳。 |
| `destinationAccountId` | `UUID` | 收到款項的帳戶。僅在 `result` 為 `SENT` 時才有值。 |
| `shareRequestId` | `UUID` | 識別一筆保留中的傳送。請將它傳給 `cancelMoneySend`。僅在 `result` 為 `PENDING_CLAIM` 時才有值。它和 `claimLink` 一樣能進入領取頁面，請勿將它寫入日誌或分析工具。 |
| `claimLink` | `String` | 收款人開啟以領取款項的連結。僅在 `claimStatus` 為 `PENDING` 時回傳。 |
| `claimStatus` | `MoneySendClaimStatus` | 保留中的傳送目前的進度。請參閱[追蹤保留中的傳送](#追蹤保留中的傳送)。 |

## 收款人需要做什麼

領取是在 Fluz 頁面上進行，而不是透過 API。

**1. 開啟連結**

Fluz 會將領取連結寄到你傳送時指定的電子郵件地址或電話號碼。若是僅連結傳送，則由你傳遞連結。

**2. 登入或建立 Fluz 帳戶**

款項會進入他們領取時所登入的帳戶，不論是個人帳戶或企業帳戶。

**3. 驗證身分**

個人帳戶必須通過 KYC，企業必須通過 KYB，且帳戶必須能夠接收付款。

**4. 驗證聯絡方式**

若是傳送到電話號碼，對方 Fluz 帳戶上的電話必須與之相符且已驗證。若是傳送到電子郵件地址，Fluz 會將 6 位數驗證碼寄到該地址。如果你兩者都傳入，已驗證且相符的電話就足夠；若對方帳戶上的電話相符但尚未驗證，需先完成驗證，否則對方需要輸入電子郵件驗證碼。僅連結傳送只需要連結。

領取頁面會在對方登入之前，就向任何開啟連結的人顯示金額、寄款方姓名與備註。

有人領取時，Fluz 會再次檢查寄款方的帳戶。如果該帳戶已不再通過 KYC 或 KYB，或 Fluz 已限制該帳戶，領取會被拒絕，款項會持續保留，直到你取消這筆傳送或它到期。關閉某個帳戶的傳送款項功能，並不會阻止該帳戶保留中的傳送被領取，因此請取消任何你想停止的傳送。

## 追蹤保留中的傳送

若要查看保留中的傳送目前的進度，請再次呼叫 `sendMoney`，並使用相同的 `idempotencyKey` 與相同的輸入。回應會重複原本的結果與 ID，並附上目前的 `claimStatus`。`claimLink` 只在 `claimStatus` 為 `PENDING` 時才會出現。此呼叫不會移動任何款項。

| `claimStatus` | 意義 |
| :- | :- |
| `PENDING` | 等待收款人領取。你可以取消。 |
| `CLAIMING` | 預留狀態。領取會讓傳送直接從 `PENDING` 變為 `CLAIMED`。 |
| `CLAIMED` | 收款人已領取，款項已進入其餘額。 |
| `RETURNED` | 已到期或已取消，款項已退回給寄款方。 |

重複呼叫會執行與新傳送相同的權限範圍、角色與消費帳戶檢查，因此如果使用者已不再是擁有者或管理者，或你的應用程式已無法使用該消費帳戶，呼叫就會被拒絕。

## 取消保留中的傳送

[`cancelMoneySend`](https://docs.fluz.app/api-reference/mutations/cancel-money-send) 會在 `claimStatus` 為 `PENDING` 時取消該筆傳送，並將款項退回其來源的現金餘額。已是 `SENT` 的傳送無法取消。

```graphql Mutation theme={null}
mutation CancelMoneySend($shareRequestId: UUID!, $idempotencyKey: UUID!) {
  cancelMoneySend(shareRequestId: $shareRequestId, idempotencyKey: $idempotencyKey) {
    cancelled
    transferId
  }
}
```

```json Variables theme={null}
{
  "shareRequestId": "0b8f2a5e-7c41-4d9e-8f3a-2e6b9c1d4a70",
  "idempotencyKey": "4c7e1a9b-6d2f-4e8a-b3c5-1f9d7a2e6b40"
}
```

```json Response theme={null}
{
  "data": {
    "cancelMoneySend": {
      "cancelled": true,
      "transferId": "c56a4180-65aa-42ec-a945-5fd21dec0538"
    }
  }
}
```

取消同樣需要相同的權限範圍，且權杖所屬的使用者必須是寄款帳戶的擁有者或管理者。你可以取消該帳戶下任何保留中的傳送，包括由其他使用者或應用程式發出的傳送。被拒絕的取消會以錯誤回傳，因此 `cancelled` 一律為 `true`。同一使用者在 24 小時內對同一筆傳送以相同的 `idempotencyKey` 重複一次已成功的取消，會回傳相同的回應。被拒絕的取消不會被儲存，因此重複請求會重新執行。

## 到期

保留中的傳送可領取至傳送日起算 `daysUntilExpiration` 天後、當天美東時間結束為止。回應不包含該日期，因此請在傳送時自行記錄。

期限過後，領取會被拒絕，Fluz 會在隔天早上美東時間 9:00 的每日排程作業中，將款項退回寄款方的現金餘額。款項退回之前，`claimStatus` 仍顯示為 `PENDING`，你仍可取消這筆傳送。

## 冪等性

`sendMoney` 與 `cancelMoneySend` 都接受 `idempotencyKey`，這是你自行產生的 UUID。大小寫不影響結果。

* 以相同的金鑰與相同的輸入重複呼叫，會回傳原本的傳送，不會移動款項，並顯示該傳送目前的進度。
* 金鑰會一直與其傳送綁定。Fluz 在 24 小時內從快取回應重複請求，之後則依傳送本身回應，因此同一個金鑰絕不會傳送兩次。每筆新傳送請使用新的金鑰。
* 如果重複呼叫變更了金額、現金餘額或收款人，或對曾用於指定收款人的金鑰設定 `linkOnly`，會以 `ARG-0001` 拒絕。切勿重複使用其他操作的金鑰：用於 `createTransfer` 的金鑰會建立一筆新的傳送，用於外部撥款的金鑰只有在該筆撥款的金鑰為小寫時才會被拒絕。
* 不會比對 `memo` 與 `daysUntilExpiration`。只變更這兩項的重複呼叫，會原樣回傳原本的傳送。
* `sendMoney` 的金鑰屬於帳戶，而不是你的應用程式。帳戶上的其他應用程式或使用者以相同的金鑰與輸入呼叫，會回傳原本的傳送。
* 如果傳送在任何款項移動之前就失敗，例如餘額不足，該金鑰仍可使用。排除原因後，請以相同的金鑰重試。

`G-0409` 表示 Fluz 仍在處理該金鑰，或它的回應已遺失。這筆傳送可能已經完成，因此請以相同的金鑰與相同的輸入重試，直到取得結果。處理中的請求最多會佔用其金鑰 10 分鐘。

## 限額

傳送會計入帳戶的轉帳限額：每日、每週、每月與每年的累計總額，以及每筆傳送的最低與最高金額。保留中的傳送會從傳送時起計入，直到款項退回為止。收款人的接收限額在款項進入帳戶時適用：立即進入帳戶的傳送在傳送時適用，保留中的傳送則在領取時適用。如需了解你的帳戶限額，請洽詢你的 Fluz 客戶經理。

## 錯誤

錯誤會出現在 GraphQL 的 `errors` 陣列中，且 `sendMoney` 或 `cancelMoneySend` 會設為 `null`。請依 `extensions.code` 決定處理方式。`ARG-` 與 `G-0003` 的訊息會指出具體原因，其他訊息可能會變動。

| 代碼 | 發生時機 |
| :- | :- |
| `AUTH-0002` | 請求使用了 Basic Auth。請改用 Bearer 使用者存取權杖。 |
| `AUTH-0031` | 權杖缺少 `MAKE_PAYOUT_TRANSFER_SEND`，或你的應用程式無法使用該現金餘額。 |
| `AUTH-0008` | 權杖所屬的使用者不是該帳戶的擁有者或管理者。 |
| `G-0003` | `Account is not enabled for money sends`：Fluz 尚未為該帳戶開通傳送款項功能。 |
| `G-0003` | `Sender is not authorized to send a payment.`：帳戶尚未通過 KYC 或 KYB。 |
| `G-0003` | `Recipient is not able to receive payments`：你透過 `recipientId` 傳送的對象帳戶無法接收付款，或這筆傳送會超出其接收限額。不會提供原因。 |
| `ARG-0001`、`ARG-0002` | 輸入無效，訊息會指出問題。包括傳送到寄款方自己的帳戶、聯絡方式符合多位使用者，以及以不同輸入重複使用金鑰。 |
| `PT-0007` | 現金餘額不足以支付該金額。 |
| `PT-0008` | 個人帳戶的部分餘額尚未入帳，暫時無法傳送。 |
| `US-0042` | `sourceCashBalanceId` 不屬於該帳戶的消費帳戶。完全不存在的 ID 可能會回傳 `ARG-0001`。 |
| `CASH-0002` | 收款人沒有可接收這筆傳送的現金餘額。 |
| `FLUZ-0113` | 寄款方的帳戶目前無法傳送款項。 |
| `FLUZ-0131`、`FLUZ-0140`、`FLUZ-0132`、`FLUZ-0141` | 這筆傳送會超過每日、每週、每月或每年的限額。 |
| `FLUZ-0142`、`FLUZ-0143` | 金額低於每筆傳送的最低金額，或高於最高金額。 |
| `G-0409` | 金鑰仍在處理中，或其回應已遺失。請以相同的金鑰與輸入重試。 |
| `G-0010` | 傳送至電子郵件地址或電話號碼時，Fluz 的某項服務在設定收款人時失敗。款項未移動。請以相同的金鑰與輸入重試；如果持續失敗，請聯絡你的 Fluz 客戶經理。 |
| `G-0004` | 發生非預期的失敗，或消費帳戶未啟用。請以相同的金鑰與輸入重試；如果持續失敗，請檢查該消費帳戶。 |

立即進入帳戶的傳送還會經過 Fluz 的詐欺審查，審查可能以其他代碼拒絕該筆傳送。對於傳送到 `recipientEmail` 或 `recipientPhone` 的傳送，`FLUZ-` 限額代碼也可能代表收款人的接收限額。

缺少、無效或已撤銷的權杖會在操作執行前遭到拒絕，並回傳 HTTP 401；已過期的權杖則回傳 HTTP 498。這兩種回應都沒有 GraphQL `errors` 陣列。

針對 `cancelMoneySend`：

| 代碼 | 訊息 | 發生時機 |
| :- | :- | :- |
| `ARG-0001` | `Money send not found` | 該 ID 不是款項傳送。 |
| `G-0003` | `You are not the sender of this money send` | 這筆傳送來自其他帳戶。 |
| `G-0003` | `Money send is not cancellable (status USED)` | 收款人已領取。 |
| `G-0003` | `Money send is not cancellable (status EXPIRED)` | 已被取消或退回。 |
| `G-0003` | `Money send escrow was settled concurrently` | 保留的款項已經結算，但該筆傳送仍顯示為 `PENDING`。請提供 `shareRequestId` 聯絡你的 Fluz 客戶經理。 |

## 參考資料

* [`sendMoney`](https://docs.fluz.app/api-reference/mutations/send-money) 與 [`SendMoneyInput`](https://docs.fluz.app/api-reference/types/send-money-input)
* [`SendMoneyResponse`](https://docs.fluz.app/api-reference/types/send-money-response)、[`MoneySendResult`](https://docs.fluz.app/api-reference/types/money-send-result) 與 [`MoneySendClaimStatus`](https://docs.fluz.app/api-reference/types/money-send-claim-status)
* [`cancelMoneySend`](https://docs.fluz.app/api-reference/mutations/cancel-money-send) 與 [`CancelMoneySendResponse`](https://docs.fluz.app/api-reference/types/cancel-money-send-response)


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