POST /api/v2/server-side-api/vc/transactions/

创建虚拟货币交易

在单个原子事务中为用户画像的一种或多种虚拟货币进行增减操作。使用正数 amount 表示增加(授予),负数 amount 表示减少(消耗)。所有条目同时生效——若任一条目失败,则全部不生效。

每种货币代码在单次请求中只能出现一次。通过此端点增加的余额始终为永久有效余额。

若要在虚拟货币数据分析中使用该交易,请使用 operation 和 feature 对其进行标记。所有标记字段均为可选项:仅包含 items 和 metadata 的请求将以 operation: null 保存。

Header parameters

adapty-customer-user-idstring

您系统中客户的唯一 ID。adapty-customer-user-id 或 adapty-profile-id 二者必填其一。

adapty-profile-idstring

您系统中用户画像的唯一 ID。如果您使用的是匿名用户画像,建议优先使用此字段。adapty-customer-user-id 或 adapty-profile-id 二者必填其一。

Idempotency-Keystring · uuid

使请求具有幂等性的 UUID v4。如果您使用相同的密钥重试请求,Adapty 将返回原始交易的结果,而不会再次更改余额。必须是有效的 UUID v4。

密钥的记忆时间最长为一小时,且仅限于单个用户画像。超过该时间窗口后,使用相同密钥的请求将被视为新交易——因此请使用该密钥安全地重试调用,而非用于长期去重授予操作。

Request body

创建虚拟货币交易的请求体。

itemsarray of objectrequired

以原子方式应用的余额调整。每个货币代码只能出现一次。

currency_codestringrequired

要调整的虚拟货币代码。

amountintegerrequired

要应用的金额。正值表示充入(授予)货币;负值表示扣除(消费)货币。不能为零。

metadataobject

随交易一起存储的可选键值对。最多 5 个键。每个键需匹配 ^[a-z0-9_]{1,30}$,每个值最多 200 个字符。

operationstring

交易的类型。大多数集成只需要四个值:spend、spend_reversal、reward、reward_reversal。如果省略,交易将被保存并以 operation: null 返回。 各值含义:top_up — 因购买、订阅或试用而充入的货币;refund — 因退款而扣回的货币;spend — 用于功能或内容消耗的货币;spend_reversal — 因操作失败(如生成失败)而退回的货币;reward — 奖励、赠送或客服补偿;reward_reversal — 被收回的奖励;exchange — 在一笔交易中进行的货币兑换,items 中含有符号相反的条目;expiry — 已过期的货币;migration — 从您自有系统迁移的余额;adjustment — 应用内经济体系之外的技术性余额修正。

One of: "top_up", "refund", "spend", "spend_reversal", "reward", "reward_reversal", "exchange", "expiry", "migration", "adjustment"

featurestring

货币被消耗或发放的用途。一个单词,可选带一个点分子类型,必须匹配 ^[a-zA-Z0-9_]{1,32}(\.[a-zA-Z0-9_]{1,32})?$。按原样存储,区分大小写。请勿编码价格、等级、版本或实验变体。示例:power_up.extra_life。

customer_placement_idstring

应用中发生该操作的页面或版位的 ID。这是您自己的 ID,而非 Adapty 版位 ID。必须匹配 ^[a-zA-Z0-9_.-]{1,128}$。按原样存储。示例:onboarding-step-3。

reference_idstring

您系统中关联对象的 ID,例如某次生成、奖励或支持工单。1–128 个字符;包含控制字符、BIDI 字符或零宽字符将被拒绝。请勿在此存储个人数据。示例:ticket_48213。

is_sandboxboolean

在测试时发放货币时设置为 true。

storestring

该交易所关联购买的商店:app_store、play_store、stripe、paddle,或在应用中配置的自定义商店 ID。最多 30 个字符。如果该购买在商店中发生退款,通过此引用充入的货币将被扣回。请与 store_transaction_id 一同发送。

store_transaction_idstring

该购买的商店交易 ID。最多 50 个字符。仅作为引用使用:Adapty 不会验证其是否存在或唯一。请与 store 一同发送。

Responses

交易已创建。响应体为已创建的交易,格式与交易历史记录中的条目相同,并附有交易后的余额。

Schema

已创建的交易,格式与交易历史记录中的条目相同,并附带交易后余额。

transaction_idstring

交易的唯一 ID。

transaction_typestring

交易来源。可选值为 store_purchase、subscription_renewal、trial_start、api_transaction、dashboard_transaction、refund 或 expiry。

itemsarray of object

此次交易中记录的各币种余额变动。

currency_codestringrequired

虚拟货币代码。

amountintegerrequired

应用于余额的带符号变动量。正值为充值,负值为扣除。

balance_afterintegerrequired

本次交易应用后的货币余额。

metadataobject

与交易一同存储的键值对(如有)。

operationstring

交易所代表的操作类型。Adapty 会在其自身创建的交易上自动设置该字段:store_purchase、subscription_renewal 和 trial_start 对应 top_up,refund 对应 refund,expiry 对应 expiry。对于 dashboard_transaction,该值为团队成员在 Adapty 看板中调整余额时所选择的操作。对于 api_transaction,该值为您传入的值;若未传入则为 null。

One of: "top_up", "refund", "spend", "spend_reversal", "reward", "reward_reversal", "exchange", "expiry", "migration", "adjustment"

featurestring

您传入的币种消费用途或发放原因。由 Adapty 创建的交易上该值为 null。

customer_placement_idstring

您传入的应用内页面或版位 ID。由 Adapty 创建的交易上该值为 null。

reference_idstring

您传入的系统中相关对象的 ID。由 Adapty 创建的交易上该值为 null。

is_sandboxboolean

该交易是否为测试交易。对于由 Adapty 创建的交易,该值与对应商店购买的环境保持一致。对于 api_transaction,该值为您传入的值,默认为 false。

storestring

相关购买所在的商店。在 Adapty 根据商店事件(购买、续订、试用、退款)创建的交易以及携带购买引用的 api_transaction 上会设置该字段。

store_transaction_idstring

相关购买的商店交易 ID。与 store 字段在相同交易上设置。

created_atstring

交易记录的时间。

response_created_atinteger

响应生成的时间,以毫秒为单位的 Unix 时间戳。

balancesarray of object

本次请求所影响的每种货币在交易后的余额(每个 items 条目对应一条记录)。如需读取用户画像的完整余额列表,请使用 GET /api/v2/server-side-api/vc/balances/。

codestringrequired

虚拟货币代码。

namestringrequired

虚拟货币的显示名称。

balanceintegerrequired

总余额,包含当前持有的金额。

heldintegerrequired

所有有效持有金额的总和(已预留金额)。当前始终为 0。

availableintegerrequired

可用于消费的余额,计算方式为 balance - held。

Example
{
  "transaction_id": "019a7c3e-5b2a-7c1d-9e4f-0a1b2c3d4e5f",
  "transaction_type": "api_transaction",
  "items": [
    {
      "currency_code": "COINS",
      "amount": -10,
      "balance_after": 90
    }
  ],
  "metadata": null,
  "operation": "spend",
  "feature": "power_up.extra_life",
  "customer_placement_id": "level-complete",
  "reference_id": "session_7781",
  "is_sandbox": false,
  "store": null,
  "store_transaction_id": null,
  "created_at": "2026-11-12T10:00:00.123Z",
  "response_created_at": 1794477600123,
  "balances": [
    {
      "code": "COINS",
      "name": "Coins",
      "balance": 90,
      "held": 0,
      "available": 90
    }
  ]
}

请求无效。error_code 字段标识原因:

  • validation_error — 请求体或请求头无效。例如,标记字段格式错误、items 为空或超过 20 个条目、amount 为 0 或超出 int32 范围、货币代码重复、metadata 不符合约束条件,或未发送 adapty-profile-id 也未发送 adapty-customer-user-id。errors[].source 指明了出错字段。对于跨多个字段的检查(例如发送了 store 但未发送 store_transaction_id),source 为空字符串。
  • parse_error — 请求体不是有效的 JSON。
  • idempotency_key_invalid — Idempotency-Key 不是 UUID v4。
  • unknown_currency — 该货币未在应用中配置。
  • unknown_store — store 是一个未在应用中配置的自定义商店。
  • insufficient_balance — 扣除金额超过可用余额。
  • balance_overflow — 增加金额将导致余额超出 int32 范围。
Schema
errorsarray of objectrequired
sourcestring

错误来源

errorsarray of string

错误消息数组

error_codestringrequired

简短错误名称

status_codeintegerrequired

HTTP 状态码

Example
{
  "errors": [
    {
      "source": "feature",
      "errors": [
        "String should match pattern '^[a-zA-Z0-9_]{1,32}(\\.[a-zA-Z0-9_]{1,32})?$'"
      ]
    }
  ],
  "error_code": "validation_error",
  "status_code": 400
}

未授权。API 密钥缺失或无效(error_code 为 not_authenticated)。

Schema
errorsarray of objectrequired
sourcestring

错误来源

errorsarray of string

错误消息数组

error_codestringrequired

简短错误名称

status_codeintegerrequired

HTTP 状态码

未找到用户画像(error_code 为 profile_does_not_exist)。

Schema
errorsarray of objectrequired
sourcestring

错误来源

errorsarray of string

错误消息数组

error_codestringrequired

简短错误名称

status_codeintegerrequired

HTTP 状态码

冲突。使用相同 Idempotency-Key 的请求仍在处理中(error_code 为 idempotency_in_flight)。请在 Retry-After 响应头指定的时间间隔后重试。

Schema
errorsarray of objectrequired
sourcestring

错误来源

errorsarray of string

错误消息数组

error_codestringrequired

简短错误名称

status_codeintegerrequired

HTTP 状态码

Example
{
  "errors": [
    {
      "source": null,
      "errors": [
        "A similar request is being processed."
      ]
    }
  ],
  "error_code": "idempotency_in_flight",
  "status_code": 409
}

请求过于频繁。超出了每个应用或全局的速率限制(error_code 为 rate_limited)。默认限制为每个应用每分钟 600 次请求,全局每分钟 6000 次请求。

Schema
errorsarray of objectrequired
sourcestring

错误来源

errorsarray of string

错误消息数组

error_codestringrequired

简短错误名称

status_codeintegerrequired

HTTP 状态码

服务器内部错误