/api/v2/server-side-api/vc/transactions/ Crear transacción de moneda virtual
Acredita o debita una o más monedas virtuales para un perfil en una única transacción atómica. Usa un amount positivo para acreditar (otorgar) y un amount negativo para debitar (gastar). Todos los elementos se aplican juntos — si algún elemento falla, ninguno se aplica.
Cada código de moneda puede aparecer solo una vez por solicitud. Un crédito a través de este endpoint siempre crea un saldo sin expiración.
Para que la transacción sea utilizable en los análisis de moneda virtual, etiquétala con operation y feature. Todos los campos de etiquetado son opcionales: una solicitud con solo items y metadata se guarda con operation: null.
Header parameters
El ID único del cliente en tu sistema. Se requiere adapty-customer-user-id o adapty-profile-id.
El ID único del perfil en tu sistema. La mejor opción si trabajas con perfiles anónimos. Se requiere adapty-customer-user-id o adapty-profile-id.
Un UUID v4 que hace la solicitud idempotente. Si reintenta una solicitud con la misma clave, Adapty devuelve el resultado de la transacción original sin modificar los saldos de nuevo. Debe ser un UUID v4 válido.
Las claves se recuerdan durante hasta una hora, con alcance a un único perfil. Pasado ese período, una solicitud con la misma clave se aplica como una nueva transacción — por lo tanto, usa la clave para reintentar una llamada de forma segura, no para deduplicar una concesión a largo plazo.
Request body
Cuerpo de la solicitud para crear una transacción de moneda virtual.
Ajustes de saldo que se aplican de forma atómica. Cada código de moneda puede aparecer solo una vez.
El código de moneda virtual a ajustar.
El importe a aplicar. Un valor positivo acredita (otorga) la moneda; un valor negativo debita (gasta) la moneda. No puede ser cero.
Pares clave-valor opcionales almacenados con la transacción. Como máximo 5 claves. Cada clave coincide con ^[a-z0-9_]{1,30}$, y cada valor tiene como máximo 200 caracteres.
El significado de la transacción. La mayoría de las integraciones necesitan cuatro valores: spend, spend_reversal, reward, reward_reversal. Si se omite, la transacción se guarda y se devuelve con operation: null.
Valores: top_up — monedas acreditadas por una compra, una suscripción o una prueba; refund — monedas retiradas porque el dinero fue reembolsado; spend — monedas gastadas en una función o contenido; spend_reversal — monedas devueltas por una acción fallida, como una generación fallida; reward — un bono, una recompensa o una compensación de soporte; reward_reversal — una recompensa retirada; exchange — una conversión entre monedas en una sola transacción, con elementos de signos opuestos; expiry — monedas vencidas; migration — saldos transferidos desde su propio sistema; adjustment — una corrección técnica de saldo fuera de la economía in-app.
One of: "top_up", "refund", "spend", "spend_reversal", "reward", "reward_reversal", "exchange", "expiry", "migration", "adjustment"
En qué se gastaron las monedas o para qué se otorgaron. Una palabra, opcionalmente con un subtipo separado por punto: debe coincidir con ^[a-zA-Z0-9_]{1,32}(\.[a-zA-Z0-9_]{1,32})?$. Se almacena tal como se envía, distinguiendo mayúsculas de minúsculas. No codifique precio, nivel, versión o variante. Ejemplo: power_up.extra_life.
ID de la pantalla o placement en su aplicación donde ocurrió la operación. Este es su propio ID, no un ID de placement de Adapty. Debe coincidir con ^[a-zA-Z0-9_.-]{1,128}$. Se almacena tal como se envía. Ejemplo: onboarding-step-3.
ID del objeto relacionado en su sistema, como una generación, una recompensa o un ticket de soporte. Entre 1 y 128 caracteres; se rechazan caracteres de control, BIDI y de ancho cero. No incluya datos personales aquí. Ejemplo: ticket_48213.
Establezca en true para las monedas que otorgue durante las pruebas.
Store de la compra a la que hace referencia esta transacción: app_store, play_store, stripe, paddle, o el ID de un store personalizado configurado en la aplicación. Hasta 30 caracteres. Si la compra es reembolsada en el store, las monedas acreditadas con esta referencia serán recuperadas. Envíe junto con store_transaction_id.
ID de transacción del store de esa compra. Hasta 50 caracteres. Es solo una referencia: Adapty no verifica que exista ni que sea única. Envíe junto con store.
Responses
Transacción creada. El cuerpo es la transacción creada, con la misma estructura que un elemento del historial de transacciones, más los saldos posteriores a la transacción.
Schema
La transacción creada, con la misma estructura que un elemento del historial de transacciones, más los saldos posteriores a la transacción.
ID único de la transacción.
El origen de la transacción. Uno de los valores: store_purchase, subscription_renewal, trial_start, api_transaction, dashboard_transaction, refund o expiry.
Cambios de saldo por moneda registrados en esta transacción.
El código de la moneda virtual.
El cambio con signo aplicado al saldo. Un valor positivo es un crédito, un valor negativo es un débito.
El saldo de la moneda después de aplicar esta transacción.
Pares clave-valor almacenados con la transacción, si los hay.
Lo que representa la transacción. Adapty lo establece en sus propias transacciones: store_purchase, subscription_renewal y trial_start reciben top_up, refund recibe refund y expiry recibe expiry. En una dashboard_transaction, es la operación que un miembro del equipo seleccionó al ajustar el saldo en el Adapty Dashboard. En una api_transaction, es el valor que usted envió, o null si no envió ninguno.
One of: "top_up", "refund", "spend", "spend_reversal", "reward", "reward_reversal", "exchange", "expiry", "migration", "adjustment"
En qué se gastaron o por qué se otorgaron las monedas, tal como usted lo envió. null en las transacciones creadas por Adapty.
El ID de pantalla o placement de su aplicación, tal como usted lo envió. null en las transacciones creadas por Adapty.
El ID del objeto relacionado en su sistema, tal como usted lo envió. null en las transacciones creadas por Adapty.
Indica si la transacción es de prueba. En las transacciones creadas por Adapty, sigue el entorno de la compra en el store. En una api_transaction, es el valor que usted envió; por defecto es false.
Store de la compra relacionada. Se establece en las transacciones creadas por Adapty a partir de eventos del store (compra, renovación, prueba, reembolso) y en una api_transaction enviada con una referencia de compra.
ID de transacción del store de la compra relacionada. Se establece en las mismas transacciones que store.
Cuándo se registró la transacción.
Momento en que se generó la respuesta, como marca de tiempo Unix en milisegundos.
Saldo posterior a la transacción para cada moneda afectada por esta solicitud (una entrada por elemento en items). Para leer la lista completa de saldos del perfil, utilice GET /api/v2/server-side-api/vc/balances/.
Código de moneda virtual.
Nombre visible de la moneda virtual.
Saldo total, incluidos los importes retenidos actualmente.
Suma de todas las retenciones activas (importes reservados). Actualmente siempre es 0.
Saldo disponible para gastar, calculado como 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
}
]
} Solicitud incorrecta. El campo error_code identifica la causa:
validation_error— el cuerpo o los encabezados no son válidos. Por ejemplo, un campo de etiquetado no cumple su formato,itemsestá vacío o tiene más de 20 entradas, unamountes 0 o está fuera del rango int32, un código de moneda se repite,metadatano cumple sus restricciones, o no se envía niadapty-profile-idniadapty-customer-user-id.errors[].sourceindica el campo. Para una validación que abarca varios campos, comostoreenviado sinstore_transaction_id,sourcees una cadena vacía.parse_error— el cuerpo no es JSON válido.idempotency_key_invalid—Idempotency-Keyno es un UUID v4.unknown_currency— la moneda no está configurada en la aplicación.unknown_store—storees un store personalizado que no está configurado en la aplicación.insufficient_balance— un débito supera el saldo disponible.balance_overflow— un crédito llevaría el saldo más allá del rango int32.
Schema
Fuente del error
Array de mensajes de error
Nombre corto del error
Código de estado 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
} No autorizado. La clave de API falta o no es válida (error_code es not_authenticated).
Schema
Fuente del error
Array de mensajes de error
Nombre corto del error
Código de estado HTTP
Perfil no encontrado (error_code es profile_does_not_exist).
Schema
Fuente del error
Array de mensajes de error
Nombre corto del error
Código de estado HTTP
Conflicto. Una solicitud con el mismo Idempotency-Key todavía está siendo procesada (error_code es idempotency_in_flight). Reintenta después del intervalo indicado en el encabezado de respuesta Retry-After.
Schema
Fuente del error
Array de mensajes de error
Nombre corto del error
Código de estado HTTP
Example
{
"errors": [
{
"source": null,
"errors": [
"A similar request is being processed."
]
}
],
"error_code": "idempotency_in_flight",
"status_code": 409
} Demasiadas solicitudes. Se superó el límite de tasa por aplicación o global (error_code es rate_limited). Los límites predeterminados son 600 solicitudes por minuto por aplicación y 6000 solicitudes por minuto a nivel global.
Schema
Fuente del error
Array de mensajes de error
Nombre corto del error
Código de estado HTTP
Error interno del servidor