POST /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

adapty-customer-user-idstring

El ID único del cliente en tu sistema. Se requiere adapty-customer-user-id o adapty-profile-id.

adapty-profile-idstring

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.

Idempotency-Keystring · uuid

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.

itemsarray of objectrequired

Ajustes de saldo que se aplican de forma atómica. Cada código de moneda puede aparecer solo una vez.

currency_codestringrequired

El código de moneda virtual a ajustar.

amountintegerrequired

El importe a aplicar. Un valor positivo acredita (otorga) la moneda; un valor negativo debita (gasta) la moneda. No puede ser cero.

metadataobject

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.

operationstring

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"

featurestring

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.

customer_placement_idstring

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.

reference_idstring

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.

is_sandboxboolean

Establezca en true para las monedas que otorgue durante las pruebas.

storestring

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.

store_transaction_idstring

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.

transaction_idstring

ID único de la transacción.

transaction_typestring

El origen de la transacción. Uno de los valores: store_purchase, subscription_renewal, trial_start, api_transaction, dashboard_transaction, refund o expiry.

itemsarray of object

Cambios de saldo por moneda registrados en esta transacción.

currency_codestringrequired

El código de la moneda virtual.

amountintegerrequired

El cambio con signo aplicado al saldo. Un valor positivo es un crédito, un valor negativo es un débito.

balance_afterintegerrequired

El saldo de la moneda después de aplicar esta transacción.

metadataobject

Pares clave-valor almacenados con la transacción, si los hay.

operationstring

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"

featurestring

En qué se gastaron o por qué se otorgaron las monedas, tal como usted lo envió. null en las transacciones creadas por Adapty.

customer_placement_idstring

El ID de pantalla o placement de su aplicación, tal como usted lo envió. null en las transacciones creadas por Adapty.

reference_idstring

El ID del objeto relacionado en su sistema, tal como usted lo envió. null en las transacciones creadas por Adapty.

is_sandboxboolean

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.

storestring

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.

store_transaction_idstring

ID de transacción del store de la compra relacionada. Se establece en las mismas transacciones que store.

created_atstring

Cuándo se registró la transacción.

response_created_atinteger

Momento en que se generó la respuesta, como marca de tiempo Unix en milisegundos.

balancesarray of object

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/.

codestringrequired

Código de moneda virtual.

namestringrequired

Nombre visible de la moneda virtual.

balanceintegerrequired

Saldo total, incluidos los importes retenidos actualmente.

heldintegerrequired

Suma de todas las retenciones activas (importes reservados). Actualmente siempre es 0.

availableintegerrequired

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, items está vacío o tiene más de 20 entradas, un amount es 0 o está fuera del rango int32, un código de moneda se repite, metadata no cumple sus restricciones, o no se envía ni adapty-profile-id ni adapty-customer-user-id. errors[].source indica el campo. Para una validación que abarca varios campos, como store enviado sin store_transaction_id, source es una cadena vacía.
  • parse_error — el cuerpo no es JSON válido.
  • idempotency_key_invalid — Idempotency-Key no es un UUID v4.
  • unknown_currency — la moneda no está configurada en la aplicación.
  • unknown_store — store es 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
errorsarray of objectrequired
sourcestring

Fuente del error

errorsarray of string

Array de mensajes de error

error_codestringrequired

Nombre corto del error

status_codeintegerrequired

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
errorsarray of objectrequired
sourcestring

Fuente del error

errorsarray of string

Array de mensajes de error

error_codestringrequired

Nombre corto del error

status_codeintegerrequired

Código de estado HTTP

Perfil no encontrado (error_code es profile_does_not_exist).

Schema
errorsarray of objectrequired
sourcestring

Fuente del error

errorsarray of string

Array de mensajes de error

error_codestringrequired

Nombre corto del error

status_codeintegerrequired

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
errorsarray of objectrequired
sourcestring

Fuente del error

errorsarray of string

Array de mensajes de error

error_codestringrequired

Nombre corto del error

status_codeintegerrequired

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
errorsarray of objectrequired
sourcestring

Fuente del error

errorsarray of string

Array de mensajes de error

error_codestringrequired

Nombre corto del error

status_codeintegerrequired

Código de estado HTTP

Error interno del servidor