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

Créer une transaction de monnaie virtuelle

Crédite ou débite une ou plusieurs monnaies virtuelles pour un profil dans une seule transaction atomique. Utilisez un amount positif pour créditer (accorder) et un amount négatif pour débiter (dépenser). Tous les éléments sont appliqués ensemble — si un élément échoue, aucun n'est appliqué.

Chaque code de monnaie ne peut apparaître qu'une seule fois par requête. Un crédit effectué via cet endpoint crée toujours un solde non expirant.

Pour rendre la transaction utilisable dans les analyses de monnaie virtuelle, étiquetez-la avec operation et feature. Tous les champs d'étiquetage sont facultatifs : une requête contenant uniquement items et metadata est enregistrée avec operation: null.

Header parameters

adapty-customer-user-idstring

L'identifiant unique du client dans votre système. adapty-customer-user-id ou adapty-profile-id est requis.

adapty-profile-idstring

L'identifiant unique du profil dans votre système. Votre meilleure option si vous travaillez avec des profils anonymes. adapty-customer-user-id ou adapty-profile-id est requis.

Idempotency-Keystring · uuid

Un UUID v4 qui rend la requête idempotente. Si vous relancez une requête avec la même clé, Adapty retourne le résultat de la transaction originale sans modifier à nouveau les soldes. Doit être un UUID v4 valide.

Les clés sont mémorisées pendant une heure au maximum, limitées à un seul profil. Passé ce délai, une requête avec la même clé est appliquée comme une nouvelle transaction — utilisez donc cette clé pour relancer un appel en toute sécurité, et non pour dédupliquer un crédit sur le long terme.

Request body

Corps de la requête pour créer une transaction en devise virtuelle.

itemsarray of objectrequired

Ajustements de solde à appliquer de manière atomique. Chaque code de devise ne peut apparaître qu'une seule fois.

currency_codestringrequired

Le code de la devise virtuelle à ajuster.

amountintegerrequired

Le montant à appliquer. Une valeur positive crédite (accorde) la devise ; une valeur négative la débite (dépense). Ne peut pas être nul.

metadataobject

Paires clé-valeur optionnelles stockées avec la transaction. Au maximum 5 clés. Chaque clé correspond à ^[a-z0-9_]{1,30}$, et chaque valeur fait au plus 200 caractères.

operationstring

La signification de la transaction. La plupart des intégrations n'ont besoin que de quatre valeurs : spend, spend_reversal, reward, reward_reversal. Si omis, la transaction est enregistrée et retournée avec operation: null. Valeurs : top_up — crédits accordés pour un achat, un abonnement ou un essai ; refund — crédits repris suite à un remboursement ; spend — crédits dépensés pour une fonctionnalité ou du contenu ; spend_reversal — crédits restitués pour une action échouée, comme une génération échouée ; reward — un bonus, une récompense ou une compensation du support ; reward_reversal — une récompense reprise ; exchange — une conversion entre devises en une seule transaction, avec des éléments de signes opposés ; expiry — crédits expirés ; migration — soldes transférés depuis votre propre système ; adjustment — une correction technique de solde en dehors de l'économie intégrée.

One of: "top_up", "refund", "spend", "spend_reversal", "reward", "reward_reversal", "exchange", "expiry", "migration", "adjustment"

featurestring

Ce pour quoi les crédits ont été dépensés ou accordés. Un seul mot, optionnellement avec un sous-type séparé par un point : doit correspondre à ^[a-zA-Z0-9_]{1,32}(\.[a-zA-Z0-9_]{1,32})?$. Stocké tel quel, sensible à la casse. Ne pas encoder le prix, le niveau, la version ou la variante. Exemple : power_up.extra_life.

customer_placement_idstring

ID de l'écran ou du placement dans votre application où l'opération a eu lieu. Il s'agit de votre propre ID, et non d'un ID de placement Adapty. Doit correspondre à ^[a-zA-Z0-9_.-]{1,128}$. Stocké tel quel. Exemple : onboarding-step-3.

reference_idstring

ID de l'objet associé dans votre système, tel qu'une génération, une récompense ou un ticket de support. 1 à 128 caractères ; les caractères de contrôle, BIDI et de largeur nulle sont rejetés. Ne pas inclure de données personnelles ici. Exemple : ticket_48213.

is_sandboxboolean

Définissez sur true pour les crédits accordés lors des tests.

storestring

Store de l'achat auquel cette transaction fait référence : app_store, play_store, stripe, paddle, ou l'ID d'un store personnalisé configuré dans l'application. Jusqu'à 30 caractères. Si l'achat est remboursé dans le store, les crédits accordés avec cette référence sont récupérés. À envoyer conjointement avec store_transaction_id.

store_transaction_idstring

ID de transaction du store pour cet achat. Jusqu'à 50 caractères. Il s'agit uniquement d'une référence : Adapty ne vérifie pas qu'elle existe ou qu'elle est unique. À envoyer conjointement avec store.

Responses

Transaction créée. Le corps correspond à la transaction créée, dans le même format qu'un élément de l'historique des transactions, plus les soldes après transaction.

Schema

La transaction créée, dans le même format qu'un élément de l'historique des transactions, avec les soldes après transaction.

transaction_idstring

Identifiant unique de la transaction.

transaction_typestring

La source de la transaction. L'une des valeurs suivantes : store_purchase, subscription_renewal, trial_start, api_transaction, dashboard_transaction, refund ou expiry.

itemsarray of object

Modifications du solde par devise enregistrées dans cette transaction.

currency_codestringrequired

Le code de la devise virtuelle.

amountintegerrequired

La variation signée appliquée au solde. Une valeur positive est un crédit, une valeur négative est un débit.

balance_afterintegerrequired

Le solde de la devise après l'application de cette transaction.

metadataobject

Paires clé-valeur stockées avec la transaction, le cas échéant.

operationstring

Ce que représente la transaction. Adapty le définit automatiquement pour ses propres transactions : store_purchase, subscription_renewal et trial_start reçoivent top_up, refund reçoit refund, et expiry reçoit expiry. Pour une dashboard_transaction, il s'agit de l'opération sélectionnée par un membre de l'équipe lors de l'ajustement du solde dans l'Adapty Dashboard. Pour une api_transaction, il s'agit de la valeur que vous avez envoyée, ou null si vous n'en avez envoyé aucune.

One of: "top_up", "refund", "spend", "spend_reversal", "reward", "reward_reversal", "exchange", "expiry", "migration", "adjustment"

featurestring

Ce pour quoi les crédits ont été dépensés ou accordés, tel que vous l'avez envoyé. null pour les transactions créées par Adapty.

customer_placement_idstring

L'identifiant de l'écran ou du placement dans votre application, tel que vous l'avez envoyé. null pour les transactions créées par Adapty.

reference_idstring

L'identifiant de l'objet associé dans votre système, tel que vous l'avez envoyé. null pour les transactions créées par Adapty.

is_sandboxboolean

Indique si la transaction est une transaction de test. Pour les transactions créées par Adapty, cette valeur suit l'environnement de l'achat dans le store. Pour une api_transaction, il s'agit de la valeur que vous avez envoyée, false par défaut.

storestring

Store de l'achat associé. Défini pour les transactions créées par Adapty à partir d'événements du store (achat, renouvellement, essai, remboursement), ainsi que pour une api_transaction envoyée avec une référence d'achat.

store_transaction_idstring

Identifiant de transaction du store pour l'achat associé. Défini pour les mêmes transactions que store.

created_atstring

Date à laquelle la transaction a été enregistrée.

response_created_atinteger

Date de génération de la réponse, sous forme d'horodatage Unix en millisecondes.

balancesarray of object

Solde après transaction pour chaque devise affectée par cette requête (une entrée par élément dans items). Pour consulter la liste complète des soldes du profil, utilisez GET /api/v2/server-side-api/vc/balances/.

codestringrequired

Code de la monnaie virtuelle.

namestringrequired

Nom d'affichage de la monnaie virtuelle.

balanceintegerrequired

Solde total, incluant les montants actuellement retenus.

heldintegerrequired

Somme de toutes les retenues actives (montants réservés). Actuellement toujours 0.

availableintegerrequired

Solde disponible à dépenser, calculé comme 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
    }
  ]
}

Requête invalide. Le champ error_code identifie la cause :

  • validation_error — le corps ou les en-têtes sont invalides. Par exemple, un champ d'étiquetage ne respecte pas son format, items est vide ou contient plus de 20 entrées, un amount est 0 ou hors de la plage int32, un code de monnaie est répété, metadata ne respecte pas ses contraintes, ou ni adapty-profile-id ni adapty-customer-user-id n'est envoyé. errors[].source indique le champ concerné. Pour une vérification portant sur plusieurs champs, comme store envoyé sans store_transaction_id, source est une chaîne vide.
  • parse_error — le corps n'est pas un JSON valide.
  • idempotency_key_invalid — Idempotency-Key n'est pas un UUID v4.
  • unknown_currency — la monnaie n'est pas configurée dans l'application.
  • unknown_store — store est un store personnalisé qui n'est pas configuré dans l'application.
  • insufficient_balance — un débit dépasse le solde disponible.
  • balance_overflow — un crédit porterait le solde au-delà de la plage int32.
Schema
errorsarray of objectrequired
sourcestring

Source de l'erreur

errorsarray of string

Tableau de messages d'erreur

error_codestringrequired

Nom court de l'erreur

status_codeintegerrequired

Code de statut 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
}

Non autorisé. La clé API est manquante ou invalide (error_code est not_authenticated).

Schema
errorsarray of objectrequired
sourcestring

Source de l'erreur

errorsarray of string

Tableau de messages d'erreur

error_codestringrequired

Nom court de l'erreur

status_codeintegerrequired

Code de statut HTTP

Profil introuvable (error_code est profile_does_not_exist).

Schema
errorsarray of objectrequired
sourcestring

Source de l'erreur

errorsarray of string

Tableau de messages d'erreur

error_codestringrequired

Nom court de l'erreur

status_codeintegerrequired

Code de statut HTTP

Conflit. Une requête avec le même Idempotency-Key est encore en cours de traitement (error_code est idempotency_in_flight). Réessayez après l'intervalle indiqué dans l'en-tête de réponse Retry-After.

Schema
errorsarray of objectrequired
sourcestring

Source de l'erreur

errorsarray of string

Tableau de messages d'erreur

error_codestringrequired

Nom court de l'erreur

status_codeintegerrequired

Code de statut HTTP

Example
{
  "errors": [
    {
      "source": null,
      "errors": [
        "A similar request is being processed."
      ]
    }
  ],
  "error_code": "idempotency_in_flight",
  "status_code": 409
}

Trop de requêtes. La limite de débit par application ou globale a été dépassée (error_code est rate_limited). Les limites par défaut sont de 600 requêtes par minute par application et de 6 000 requêtes par minute au niveau global.

Schema
errorsarray of objectrequired
sourcestring

Source de l'erreur

errorsarray of string

Tableau de messages d'erreur

error_codestringrequired

Nom court de l'erreur

status_codeintegerrequired

Code de statut HTTP

Erreur interne du serveur