獎勵自動轉入

獎勵自動轉入功能會每天一次，將某個帳戶的可用獎勵轉入另一個 Fluz 帳戶的消費帳戶，無需使用者進行任何操作。您的應用程式會將使用者的帳戶連結至已核准的目標帳戶，其餘由 Fluz 執行轉入。當您的平台需要收取使用者在 Fluz 上賺取的獎勵時，就可以使用此功能。例如，將會員賺取的現金回饋自動轉入您平台的營運消費帳戶。本頁涵蓋 TGS GraphQL 介面：

運作方式

Fluz 核准您的目標帳戶、設定獎勵轉入的消費帳戶，並將您的應用程式加入允許清單。這是由 Fluz 執行的一次性設定，完成前其他功能都無法運作。請參閱與 Fluz 完成設定。
使用者授權您的應用程式。您的應用程式使用使用者的存取權杖和您的目標帳戶 ID 呼叫 createRewardsSweepConnection。
每個紐約日曆日一次，Fluz 會將使用者的全部可用獎勵餘額轉入您的目標消費帳戶。
若要停止，您的應用程式使用使用者的存取權杖呼叫 deleteRewardsSweepConnection。

在本頁中，來源帳戶是被轉出獎勵的使用者帳戶，目標帳戶是接收款項的帳戶，消費帳戶則是款項實際轉入的目標帳戶之消費帳戶。

只會轉入可用獎勵。轉入作業會在執行當下取用可花費的獎勵餘額。待處理或鎖定的獎勵會保留在來源帳戶，等待之後的轉入作業處理。系統不會預先保留任何款項：在轉入執行之前，使用者可以正常花費其獎勵。

與 Fluz 完成設定

在您連結任何帳戶之前，Fluz 必須先核准您的目標帳戶並將您的應用程式加入允許清單。您無法自行透過 API 完成此設定。在 Fluz 完成這兩項作業之前，createRewardsSweepConnection 會失敗，並回傳 App is not allowed to create a rewards sweep connection 或 Target account is not approved for rewards sweep。

請聯絡您的 Fluz 客戶經理，並提供以下資訊：

提供給 Fluz	原因
您的目標帳戶 ID	接收轉入獎勵的帳戶。Fluz 會將其加入已核准的目標。
該目標帳戶上的消費帳戶	款項轉入的位置。它必須屬於該目標帳戶。每個目標僅有一個目的地消費帳戶。
您的應用程式 ID（可多個）	Fluz 會將每個會呼叫獎勵自動轉入 mutation 的應用程式加入允許清單。

目標核准且應用程式加入允許清單後，Fluz 會通知您。若之後要變更目的地消費帳戶或新增其他應用程式，請再次聯絡 Fluz。您的應用程式無法自行變更其設定。 Fluz 也可以透過自己的後台將帳戶連結至您的目標，無需呼叫 API。

每次呼叫的需求

需求	值
驗證	來源帳戶的 Bearer 權杖。不支援 Basic Auth。
範圍	`MAKE_PAYOUT_TRANSFER_SEND`（與 `createTransfer` 相同的範圍）。請在使用者授權您的應用程式時申請。
應用程式	已由 Fluz 加入獎勵自動轉入的允許清單
目標	已由 Fluz 核准用於獎勵自動轉入

連結帳戶

使用使用者的存取權杖呼叫 createRewardsSweepConnection。來源帳戶一律取自權杖。請傳入您的目標帳戶 ID，而非消費帳戶 ID。

mutation {
  createRewardsSweepConnection(input: {
    targetAccountId: "b2c3d4e5-f6a7-8901-bcde-f23456789012"
  }) {
    rewardsSweepSourceAccountId
    sourceAccountId
    targetAccountId
  }
}

Authorization: Bearer <user-access-token>

{
  "data": {
    "createRewardsSweepConnection": {
      "rewardsSweepSourceAccountId": "7c1e2d3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
      "sourceAccountId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "targetAccountId": "b2c3d4e5-f6a7-8901-bcde-f23456789012"
    }
  }
}

規則

一個來源帳戶同一時間只能連結至一個目標。
以相同目標再次呼叫 create 是安全的，會回傳現有的連結。
在已有連結的情況下，以不同目標呼叫 create 會失敗。若要變更目標，請先中斷連結，再連結至新目標。
來源帳戶與目標帳戶必須不同。
Fluz 也可以從其後台為帳戶建立連結。該連結的行為相同，並可透過 deleteRewardsSweepConnection 移除。

中斷帳戶連結

使用使用者的存取權杖呼叫 deleteRewardsSweepConnection。它不需要任何輸入，會移除權杖所屬帳戶的連結。

mutation {
  deleteRewardsSweepConnection {
    sourceAccountId
    disconnected
  }
}

{
  "data": {
    "deleteRewardsSweepConnection": {
      "sourceAccountId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "disconnected": true
    }
  }
}

當帳戶沒有任何連結時，disconnected 為 false。這並非錯誤，因此可以安全地重複呼叫。若您在當日轉入已排程之後、款項移動之前中斷連結，當日的轉入會被取消，且不會扣款。

轉入行為


頻率	每個來源帳戶每個日曆日最多轉入一次，以 `America/New_York` 時間為準。執行時間由 Fluz 設定。
金額	轉入執行當下的全部可用獎勵餘額，無條件捨去至整數分。不足一分的部分會保留在來源帳戶。
餘額為零	不會進行轉帳。該日仍視為已完成轉入。
目的地	當日轉入排程時，為該目標所設定的消費帳戶。
重試	每日轉入都有固定的冪等鍵，因此重試絕不會重複轉移款項。
餘額不足	若餘額在款項移動前發生變動，轉入作業會重新讀取餘額並重試。
被拒絕的轉入	若 Fluz 無法移動該帳戶的款項，例如帳戶正在審查中，當日的轉入會停止且不會重試。獎勵會保留在來源帳戶，隔天的轉入會再次嘗試。
已中斷連結	若帳戶在當日轉入排程之後、款項移動之前被中斷連結，則不會扣款。

帳戶端的顯示

每次轉入都是一筆帳戶對帳戶的轉帳，並會在兩個帳戶的活動紀錄中顯示，說明為 Rewards transfer。

帳戶	活動紀錄列
來源	款項從 Fluz 獎勵餘額轉出至目標帳戶及消費帳戶
目標	款項從來源帳戶轉入並進入消費帳戶

檢查連結

目前沒有可讀取連結或過往轉入紀錄的查詢。請根據 createRewardsSweepConnection 和 deleteRewardsSweepConnection 的回應，在您這邊儲存連結資訊。您可以從目標帳戶的交易活動確認轉入紀錄。

錯誤

失敗時會使用標準的 GraphQL 錯誤格式。

{
  "data": null,
  "errors": [
    {
      "message": "Target account is not approved for rewards sweep",
      "extensions": {
        "code": "APPLICATIONS-0012",
        "errorName": "InvalidArgument",
        "statusCode": 422
      }
    }
  ]
}

錯誤會依下列順序檢查：

代碼	訊息	時機
`AUTH-0002`	Basic auth is not supported for this operation.	請求使用了 Basic Auth。請改用使用者的 Bearer 權杖。
`AUTH-0031`	Insufficient permissions: `<mutation>` requires MAKE_PAYOUT_TRANSFER_SEND	權杖缺少 `MAKE_PAYOUT_TRANSFER_SEND` 範圍。
`AUTH-0008`	Authenticated account is required.	權杖無法對應到任何帳戶。
`AUTH-0008`	App is not allowed to create a rewards sweep connection	您的應用程式未加入獎勵自動轉入的允許清單。Delete 會回傳相同訊息，但為 “delete”。
`APPLICATIONS-0012`	Target account is not approved for rewards sweep	`targetAccountId` 不是已登記的目標，或沒有消費帳戶。僅限 create。
`APPLICATIONS-0012`	Source and target accounts must be different.	權杖所屬帳戶即為目標帳戶。僅限 create。
`APPLICATIONS-0012`	Source account is already connected to a rewards sweep target	該帳戶已連結至不同的目標。請先中斷連結。僅限 create。

缺少、無效或過期的存取權杖會在 GraphQL 執行前被拒絕，並回傳 HTTP 錯誤，而非 GraphQL 錯誤。請參閱驗證。

​運作方式

​與 Fluz 完成設定

​每次呼叫的需求

​連結帳戶

​中斷帳戶連結

​轉入行為

​帳戶端的顯示

​檢查連結

​錯誤

運作方式

與 Fluz 完成設定

每次呼叫的需求

連結帳戶

中斷帳戶連結

轉入行為

帳戶端的顯示

檢查連結

錯誤