/api/v2/server-side-api/vc/transactions/ 创建虚拟货币交易
在单个原子事务中为用户画像的一种或多种虚拟货币进行增减操作。使用正数 amount 表示增加(授予),负数 amount 表示减少(消耗)。所有条目同时生效——若任一条目失败,则全部不生效。
每种货币代码在单次请求中只能出现一次。通过此端点增加的余额始终为永久有效余额。
若要在虚拟货币数据分析中使用该交易,请使用 operation 和 feature 对其进行标记。所有标记字段均为可选项:仅包含 items 和 metadata 的请求将以 operation: null 保存。
Header parameters
您系统中客户的唯一 ID。adapty-customer-user-id 或 adapty-profile-id 二者必填其一。
您系统中用户画像的唯一 ID。如果您使用的是匿名用户画像,建议优先使用此字段。adapty-customer-user-id 或 adapty-profile-id 二者必填其一。
使请求具有幂等性的 UUID v4。如果您使用相同的密钥重试请求,Adapty 将返回原始交易的结果,而不会再次更改余额。必须是有效的 UUID v4。
密钥的记忆时间最长为一小时,且仅限于单个用户画像。超过该时间窗口后,使用相同密钥的请求将被视为新交易——因此请使用该密钥安全地重试调用,而非用于长期去重授予操作。
Request body
创建虚拟货币交易的请求体。
以原子方式应用的余额调整。每个货币代码只能出现一次。
要调整的虚拟货币代码。
要应用的金额。正值表示充入(授予)货币;负值表示扣除(消费)货币。不能为零。
随交易一起存储的可选键值对。最多 5 个键。每个键需匹配 ^[a-z0-9_]{1,30}$,每个值最多 200 个字符。
交易的类型。大多数集成只需要四个值: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"
货币被消耗或发放的用途。一个单词,可选带一个点分子类型,必须匹配 ^[a-zA-Z0-9_]{1,32}(\.[a-zA-Z0-9_]{1,32})?$。按原样存储,区分大小写。请勿编码价格、等级、版本或实验变体。示例:power_up.extra_life。
应用中发生该操作的页面或版位的 ID。这是您自己的 ID,而非 Adapty 版位 ID。必须匹配 ^[a-zA-Z0-9_.-]{1,128}$。按原样存储。示例:onboarding-step-3。
您系统中关联对象的 ID,例如某次生成、奖励或支持工单。1–128 个字符;包含控制字符、BIDI 字符或零宽字符将被拒绝。请勿在此存储个人数据。示例:ticket_48213。
在测试时发放货币时设置为 true。
该交易所关联购买的商店:app_store、play_store、stripe、paddle,或在应用中配置的自定义商店 ID。最多 30 个字符。如果该购买在商店中发生退款,通过此引用充入的货币将被扣回。请与 store_transaction_id 一同发送。
该购买的商店交易 ID。最多 50 个字符。仅作为引用使用:Adapty 不会验证其是否存在或唯一。请与 store 一同发送。
Responses
交易已创建。响应体为已创建的交易,格式与交易历史记录中的条目相同,并附有交易后的余额。
Schema
已创建的交易,格式与交易历史记录中的条目相同,并附带交易后余额。
交易的唯一 ID。
交易来源。可选值为 store_purchase、subscription_renewal、trial_start、api_transaction、dashboard_transaction、refund 或 expiry。
此次交易中记录的各币种余额变动。
虚拟货币代码。
应用于余额的带符号变动量。正值为充值,负值为扣除。
本次交易应用后的货币余额。
与交易一同存储的键值对(如有)。
交易所代表的操作类型。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"
您传入的币种消费用途或发放原因。由 Adapty 创建的交易上该值为 null。
您传入的应用内页面或版位 ID。由 Adapty 创建的交易上该值为 null。
您传入的系统中相关对象的 ID。由 Adapty 创建的交易上该值为 null。
该交易是否为测试交易。对于由 Adapty 创建的交易,该值与对应商店购买的环境保持一致。对于 api_transaction,该值为您传入的值,默认为 false。
相关购买所在的商店。在 Adapty 根据商店事件(购买、续订、试用、退款)创建的交易以及携带购买引用的 api_transaction 上会设置该字段。
相关购买的商店交易 ID。与 store 字段在相同交易上设置。
交易记录的时间。
响应生成的时间,以毫秒为单位的 Unix 时间戳。
本次请求所影响的每种货币在交易后的余额(每个 items 条目对应一条记录)。如需读取用户画像的完整余额列表,请使用 GET /api/v2/server-side-api/vc/balances/。
虚拟货币代码。
虚拟货币的显示名称。
总余额,包含当前持有的金额。
所有有效持有金额的总和(已预留金额)。当前始终为 0。
可用于消费的余额,计算方式为 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
错误来源
错误消息数组
简短错误名称
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
错误来源
错误消息数组
简短错误名称
HTTP 状态码
未找到用户画像(error_code 为 profile_does_not_exist)。
Schema
错误来源
错误消息数组
简短错误名称
HTTP 状态码
冲突。使用相同 Idempotency-Key 的请求仍在处理中(error_code 为 idempotency_in_flight)。请在 Retry-After 响应头指定的时间间隔后重试。
Schema
错误来源
错误消息数组
简短错误名称
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
错误来源
错误消息数组
简短错误名称
HTTP 状态码
服务器内部错误