傳送款項

使用 sendMoney 從使用者的 Fluz 現金餘額傳送款項。你可以將收款對象指定為電子郵件地址或電話號碼、Fluz 帳戶 ID，或不指定任何人，此時你會取得領取連結，由你自行傳遞。收款人不必是你應用程式的使用者，也不必已經擁有 Fluz 帳戶。一筆傳送會以兩種結果之一收場。SENT 表示款項已進入收款人的餘額，且無法撤回。PENDING_CLAIM 表示 Fluz 先保留款項，直到收款人在 Fluz 頁面上領取。如果到期前無人領取，或你取消了這筆傳送，款項會退回給寄款方。你如何指定傳送對象，決定會出現哪一種結果。

開始之前

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

與 createTransfer 不同。createTransfer 在你應用程式的帳戶與已授權你應用程式的帳戶之間移轉資金，也能在兩個這類帳戶之間移轉。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 涵蓋所有類型的傳送，只有輸入內容不同。

Mutation

mutation SendMoney($input: SendMoneyInput!) {
  sendMoney(input: $input) {
    result
    transferId
    destinationAccountId
    shareRequestId
    claimLink
    claimStatus
  }
}

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

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

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

{
  "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。款項會立即進入該帳戶，否則這筆傳送會被拒絕。

Variables

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

以領取連結傳送

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

Variables

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

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

輸入欄位

SendMoneyInput

欄位	類型	必填	說明
`idempotencyKey`	`UUID!`	是	你為每筆新傳送產生的 UUID。請參閱冪等性。
`amount`	`Float!`	是	必須大於 0，最多 1,000,000，小數最多兩位。
`sourceCashBalanceId`	`UUID!`	是	負責付款的消費帳戶的 `userCashBalanceId`，取自 `getUserCashBalances`（需要 `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

欄位	類型	說明
`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。

開啟連結

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

登入或建立 Fluz 帳戶

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

驗證身分

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

驗證聯絡方式

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

領取頁面會在對方登入之前，就向任何開啟連結的人顯示金額、寄款方姓名與備註。有人領取時，Fluz 會再次檢查寄款方的帳戶。如果該帳戶已不再通過 KYC 或 KYB，或 Fluz 已限制該帳戶，領取會被拒絕，款項會持續保留，直到你取消這筆傳送或它到期。關閉某個帳戶的傳送款項功能，並不會阻止該帳戶保留中的傳送被領取，因此請取消任何你想停止的傳送。

追蹤保留中的傳送

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

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

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

取消保留中的傳送

cancelMoneySend 會在 claimStatus 為 PENDING 時取消該筆傳送，並將款項退回其來源的現金餘額。已是 SENT 的傳送無法取消。

Mutation

mutation CancelMoneySend($shareRequestId: UUID!, $idempotencyKey: UUID!) {
  cancelMoneySend(shareRequestId: $shareRequestId, idempotencyKey: $idempotencyKey) {
    cancelled
    transferId
  }
}

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

{
  "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 客戶經理。

​款項如何送達

​傳送款項

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

​傳送到 Fluz 帳戶

​以領取連結傳送

​輸入欄位

​回應欄位

​收款人需要做什麼

​追蹤保留中的傳送

​取消保留中的傳送

​到期

​冪等性

​限額

​錯誤

​參考資料

款項如何送達

傳送款項

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

傳送到 Fluz 帳戶

以領取連結傳送

輸入欄位

回應欄位

收款人需要做什麼

追蹤保留中的傳送

取消保留中的傳送

到期

冪等性

限額

錯誤

參考資料