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

Создать транзакцию виртуальной валюты

Начисляет или списывает одну или несколько виртуальных валют для профиля в рамках одной атомарной транзакции. Используйте положительное значение amount для зачисления (выдачи) и отрицательное — для списания (расходования). Все элементы применяются вместе — если хотя бы один не выполняется, ни один не применяется.

Каждый код валюты может встречаться в запросе только один раз. Зачисление через этот эндпоинт всегда создаёт баланс без срока действия.

Чтобы транзакция учитывалась в аналитике виртуальных валют, укажите operation и feature. Все поля разметки необязательны: запрос, содержащий только items и metadata, сохраняется с operation: null.

Header parameters

adapty-customer-user-idstring

Уникальный идентификатор клиента в вашей системе. Требуется либо adapty-customer-user-id, либо adapty-profile-id.

adapty-profile-idstring

Уникальный идентификатор профиля в вашей системе. Оптимальный вариант при работе с анонимными профилями. Требуется либо 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 — конвертация между валютами в одной транзакции с позициями противоположного знака; 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, а не ID плейсмента Adapty. Должен соответствовать шаблону ^[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

Уникальный идентификатор транзакции.

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

На что были потрачены или за что были начислены монеты — так, как вы это передали. null для транзакций, созданных Adapty.

customer_placement_idstring

Идентификатор экрана или плейсмента из вашего приложения, так как вы его передали. null для транзакций, созданных Adapty.

reference_idstring

Идентификатор связанного объекта в вашей системе, так как вы его передали. null для транзакций, созданных Adapty.

is_sandboxboolean

Является ли транзакция тестовой. Для транзакций, созданных Adapty, значение соответствует окружению покупки в сторе. Для api_transaction — это значение, которое вы передали; по умолчанию false.

storestring

Стор связанной покупки. Устанавливается для транзакций, созданных Adapty на основе событий стора (покупка, продление, пробный период, возврат), а также для api_transaction, переданной со ссылкой на покупку.

store_transaction_idstring

Идентификатор транзакции стора для связанной покупки. Устанавливается для тех же транзакций, что и 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-код статуса

Внутренняя ошибка сервера