返现自动归集

返现自动归集会每天一次,无需用户任何操作,将某个账户的可用返现转入另一个 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(或多个 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 完成设置

每次调用的要求

连接账户

断开账户

归集行为

账户中显示的内容

查看连接

错误