/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
L'identifiant unique du client dans votre système. adapty-customer-user-id ou adapty-profile-id est requis.
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.
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.
Ajustements de solde à appliquer de manière atomique. Chaque code de devise ne peut apparaître qu'une seule fois.
Le code de la devise virtuelle à ajuster.
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.
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.
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"
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.
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.
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.
Définissez sur true pour les crédits accordés lors des tests.
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.
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.
Identifiant unique de la transaction.
La source de la transaction. L'une des valeurs suivantes : store_purchase, subscription_renewal, trial_start, api_transaction, dashboard_transaction, refund ou expiry.
Modifications du solde par devise enregistrées dans cette transaction.
Le code de la devise virtuelle.
La variation signée appliquée au solde. Une valeur positive est un crédit, une valeur négative est un débit.
Le solde de la devise après l'application de cette transaction.
Paires clé-valeur stockées avec la transaction, le cas échéant.
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"
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.
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.
L'identifiant de l'objet associé dans votre système, tel que vous l'avez envoyé. null pour les transactions créées par Adapty.
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.
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.
Identifiant de transaction du store pour l'achat associé. Défini pour les mêmes transactions que store.
Date à laquelle la transaction a été enregistrée.
Date de génération de la réponse, sous forme d'horodatage Unix en millisecondes.
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/.
Code de la monnaie virtuelle.
Nom d'affichage de la monnaie virtuelle.
Solde total, incluant les montants actuellement retenus.
Somme de toutes les retenues actives (montants réservés). Actuellement toujours 0.
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,itemsest vide ou contient plus de 20 entrées, unamountest 0 ou hors de la plage int32, un code de monnaie est répété,metadatane respecte pas ses contraintes, ou niadapty-profile-idniadapty-customer-user-idn'est envoyé.errors[].sourceindique le champ concerné. Pour une vérification portant sur plusieurs champs, commestoreenvoyé sansstore_transaction_id,sourceest une chaîne vide.parse_error— le corps n'est pas un JSON valide.idempotency_key_invalid—Idempotency-Keyn'est pas un UUID v4.unknown_currency— la monnaie n'est pas configurée dans l'application.unknown_store—storeest 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
Source de l'erreur
Tableau de messages d'erreur
Nom court de l'erreur
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
Source de l'erreur
Tableau de messages d'erreur
Nom court de l'erreur
Code de statut HTTP
Profil introuvable (error_code est profile_does_not_exist).
Schema
Source de l'erreur
Tableau de messages d'erreur
Nom court de l'erreur
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
Source de l'erreur
Tableau de messages d'erreur
Nom court de l'erreur
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
Source de l'erreur
Tableau de messages d'erreur
Nom court de l'erreur
Code de statut HTTP
Erreur interne du serveur