现金奖励

商户可以给玩家发放活动现金奖励，例如签到奖励、补偿金。奖励直接加到玩家余额：

• 转账钱包：加到平台账本余额。
• 单一钱包：平台调用商户的改变玩家余额，kind=GIFT。

这个功能需要开通。请先确认 capabilities.operations 中 gift_tasks 的 supported=true。

与游戏无关

现金奖励是独立的资金操作，不影响游戏结果，也不计入注单的派奖。

创建奖励任务

POST {API_URL}/v1/gift-tasks

Idempotency-Key 必须与 external_id 完全相同。

参数	必填	类型	说明
external_id	是	string	商户活动订单号，[A-Za-z0-9._:-]，1–128，永久唯一
player_id	是	string	平台玩家 ID
currency	是	string	币种代码
amount	是	decimal string	大于 0，精度不超过 decimal_scale
reason	是	string	发放原因，1–256 字节

{
  "external_id": "gift-20260923-0001",
  "player_id": "0192f6a4-3c1e-7b2a-9d40-5e8f1a2b3c4d",
  "currency": "USD",
  "amount": "5.00",
  "reason": "daily check-in"
}

成功响应

任务已完成返回 201；还在排队或执行中返回 202。

{
  "data": {
    "task_id": "0192f710-8091-7b2c-d3e4-1f2a3b4c5d6e",
    "transaction_id": "0192f710-8091-7b2c-d3e4-1f2a3b4c5d6f",
    "external_id": "gift-20260923-0001",
    "task_status": "QUEUED",
    "transaction_status": "PENDING"
  },
  "request_id": "0192f710-req-0001"
}

查询奖励任务

GET {API_URL}/v1/gift-tasks/{task_id}

字段	说明
task_id / transaction_id / external_id	任务、资金交易和商户订单号
task_status	任务状态，见下表
transaction_status	资金状态：PENDING、UNKNOWN、SUCCEEDED、FAILED
amount / currency	金额和币种
created_at / updated_at	时间
failure	失败时出现，{"code":"..."}
recovery_reason	资金结果暂时无法确认时出现，说明平台正在恢复的原因

task_status	transaction_status	含义
QUEUED	PENDING	排队中，还没有发放，可以取消
EXECUTING	PENDING 或 UNKNOWN	正在发放。UNKNOWN 时带 recovery_reason，平台会自动恢复，不是失败
SUCCEEDED	SUCCEEDED	已到账
FAILED	FAILED	发放失败，没有到账，原因见 failure.code
CANCELLED	FAILED	已在发放前取消，failure.code=CANCELLED_BEFORE_DISPATCH

取消奖励任务

POST {API_URL}/v1/gift-tasks/{task_id}/cancellations

需要 Idempotency-Key。

参数	必填	说明
reason	是	取消原因，1–256 字节

只有 QUEUED 状态的任务可以取消。取消成功返回 200：

{
  "data": {
    "task_id": "0192f710-8091-7b2c-d3e4-1f2a3b4c5d6e",
    "transaction_id": "0192f710-8091-7b2c-d3e4-1f2a3b4c5d6f",
    "task_status": "CANCELLED",
    "transaction_status": "FAILED",
    "failure": { "code": "CANCELLED_BEFORE_DISPATCH" }
  },
  "request_id": "0192f710-req-0002"
}

任务已经开始发放、结果未知或已完成时，返回 409 CANCELLATION_NOT_ALLOWED，请继续查询任务等待结果。

已到账的奖励不能撤回

取消只能阻止尚未发放的奖励。已经成功发放的奖励不能通过取消扣回。