/api/v2/server-side-api/vc/transactions/ Создать транзакцию виртуальной валюты
Начисляет или списывает одну или несколько виртуальных валют для профиля в рамках одной атомарной транзакции. Используйте положительное значение amount для зачисления (выдачи) и отрицательное — для списания (расходования). Все элементы применяются вместе — если хотя бы один не выполняется, ни один не применяется.
Каждый код валюты может встречаться в запросе только один раз. Зачисление через этот эндпоинт всегда создаёт баланс без срока действия.
Чтобы транзакция учитывалась в аналитике виртуальных валют, укажите operation и feature. Все поля разметки необязательны: запрос, содержащий только items и metadata, сохраняется с operation: null.
Header parameters
Уникальный идентификатор клиента в вашей системе. Требуется либо adapty-customer-user-id, либо adapty-profile-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 — конвертация между валютами в одной транзакции с позициями противоположного знака; 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, а не ID плейсмента Adapty. Должен соответствовать шаблону ^[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
Созданная транзакция в том же формате, что и элемент истории транзакций, плюс балансы после транзакции.
Уникальный идентификатор транзакции.
Источник транзакции. Одно из значений: 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"
На что были потрачены или за что были начислены монеты — так, как вы это передали. null для транзакций, созданных Adapty.
Идентификатор экрана или плейсмента из вашего приложения, так как вы его передали. null для транзакций, созданных Adapty.
Идентификатор связанного объекта в вашей системе, так как вы его передали. null для транзакций, созданных Adapty.
Является ли транзакция тестовой. Для транзакций, созданных Adapty, значение соответствует окружению покупки в сторе. Для api_transaction — это значение, которое вы передали; по умолчанию false.
Стор связанной покупки. Устанавливается для транзакций, созданных Adapty на основе событий стора (покупка, продление, пробный период, возврат), а также для api_transaction, переданной со ссылкой на покупку.
Идентификатор транзакции стора для связанной покупки. Устанавливается для тех же транзакций, что и 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-код статуса
Внутренняя ошибка сервера