/api/v2/server-side-api/vc/transactions/ Tạo giao dịch tiền tệ ảo
Cộng hoặc trừ một hoặc nhiều tiền tệ ảo cho một hồ sơ người dùng trong một giao dịch nguyên tử duy nhất. Dùng amount dương để cộng (tặng) và amount âm để trừ (tiêu). Tất cả các mục được áp dụng cùng nhau — nếu bất kỳ mục nào thất bại, không có mục nào được áp dụng.
Mỗi mã tiền tệ chỉ được xuất hiện một lần trong mỗi yêu cầu. Một khoản cộng thông qua endpoint này luôn tạo ra số dư không hết hạn.
Để giao dịch có thể sử dụng được trong phân tích tiền tệ ảo, hãy gắn nhãn với operation và feature. Tất cả các trường gắn nhãn đều tùy chọn: một yêu cầu chỉ có items và metadata sẽ được lưu với operation: null.
Header parameters
ID duy nhất của khách hàng trong hệ thống của bạn. Yêu cầu phải có adapty-customer-user-id hoặc adapty-profile-id.
ID duy nhất của hồ sơ người dùng trong hệ thống của bạn. Lựa chọn tốt nhất nếu bạn đang làm việc với các hồ sơ người dùng ẩn danh. Yêu cầu phải có adapty-customer-user-id hoặc adapty-profile-id.
Một UUID v4 giúp yêu cầu có tính idempotent. Nếu bạn thử lại yêu cầu với cùng key, Adapty trả về kết quả của giao dịch ban đầu mà không thay đổi số dư thêm lần nữa. Phải là UUID v4 hợp lệ.
Các key được ghi nhớ tối đa một giờ, giới hạn trong phạm vi một hồ sơ người dùng. Sau khoảng thời gian đó, một yêu cầu với cùng key sẽ được áp dụng như một giao dịch mới — vì vậy hãy dùng key để thử lại một lời gọi một cách an toàn, không phải để loại trùng lặp một khoản tặng trong dài hạn.
Request body
Nội dung yêu cầu để tạo giao dịch tiền tệ ảo.
Các điều chỉnh số dư được áp dụng nguyên tử. Mỗi mã tiền tệ chỉ được xuất hiện một lần.
Mã tiền tệ ảo cần điều chỉnh.
Số lượng cần áp dụng. Giá trị dương sẽ cộng thêm (cấp) tiền tệ; giá trị âm sẽ trừ đi (tiêu dùng) tiền tệ. Không được bằng không.
Các cặp key-value tùy chọn được lưu kèm theo giao dịch. Tối đa 5 key. Mỗi key khớp với ^[a-z0-9_]{1,30}$, và mỗi giá trị tối đa 200 ký tự.
Ý nghĩa của giao dịch. Hầu hết các tích hợp chỉ cần bốn giá trị: spend, spend_reversal, reward, reward_reversal. Nếu bỏ qua, giao dịch sẽ được lưu và trả về với operation: null.
Các giá trị: top_up — xu được ghi có cho một sản phẩm mua một lần, một gói đăng ký, hoặc một bản dùng thử; refund — xu bị thu hồi vì tiền đã được hoàn trả; spend — xu được chi tiêu cho một tính năng hoặc nội dung; spend_reversal — xu được trả lại cho một hành động thất bại, chẳng hạn như một lần tạo nội dung thất bại; reward — một phần thưởng, một khoản thưởng, hoặc một khoản bồi thường hỗ trợ; reward_reversal — một phần thưởng bị thu hồi; exchange — chuyển đổi giữa các loại tiền tệ trong một giao dịch, với các mục có dấu ngược nhau; expiry — xu đã hết hạn; migration — số dư được chuyển từ hệ thống của bạn; adjustment — điều chỉnh số dư kỹ thuật nằm ngoài nền kinh tế in-app.
One of: "top_up", "refund", "spend", "spend_reversal", "reward", "reward_reversal", "exchange", "expiry", "migration", "adjustment"
Những gì xu được chi tiêu cho hoặc được cấp vì. Một từ, tùy chọn có một kiểu con phân cách bằng dấu chấm: phải khớp với ^[a-zA-Z0-9_]{1,32}(\.[a-zA-Z0-9_]{1,32})?$. Được lưu nguyên trạng, phân biệt chữ hoa chữ thường. Không mã hóa giá, cấp độ, phiên bản, hoặc biến thể. Ví dụ: power_up.extra_life.
ID của màn hình hoặc placement trong ứng dụng của bạn nơi thao tác xảy ra. Đây là ID của chính bạn, không phải ID placement của Adapty. Phải khớp với ^[a-zA-Z0-9_.-]{1,128}$. Được lưu nguyên trạng. Ví dụ: onboarding-step-3.
ID của đối tượng liên quan trong hệ thống của bạn, chẳng hạn như một lần tạo nội dung, một phần thưởng, hoặc một phiếu hỗ trợ. 1–128 ký tự; các ký tự điều khiển, BIDI, và ký tự có độ rộng bằng không sẽ bị từ chối. Không đặt dữ liệu cá nhân ở đây. Ví dụ: ticket_48213.
Đặt thành true cho xu bạn cấp trong khi kiểm thử.
Cửa hàng của sản phẩm mua một lần mà giao dịch này tham chiếu đến: app_store, play_store, stripe, paddle, hoặc ID của một cửa hàng tùy chỉnh được thiết lập trong ứng dụng. Tối đa 30 ký tự. Nếu sản phẩm mua một lần được hoàn tiền tại cửa hàng, số xu được ghi có với tham chiếu này sẽ bị thu hồi. Gửi cùng với store_transaction_id.
ID giao dịch của cửa hàng cho sản phẩm mua một lần đó. Tối đa 50 ký tự. Đây chỉ là một tham chiếu: Adapty không kiểm tra rằng nó tồn tại hoặc là duy nhất. Gửi cùng với store.
Responses
Giao dịch đã được tạo. Phần body là giao dịch đã tạo, có cùng cấu trúc như một mục trong lịch sử giao dịch, cộng thêm số dư sau giao dịch.
Schema
Giao dịch vừa được tạo, có cùng cấu trúc với một mục trong lịch sử giao dịch, cộng thêm số dư sau giao dịch.
ID duy nhất của giao dịch.
Nguồn gốc của giao dịch. Một trong các giá trị: store_purchase, subscription_renewal, trial_start, api_transaction, dashboard_transaction, refund, hoặc expiry.
Các thay đổi số dư theo từng loại tiền tệ được ghi lại trong giao dịch này.
Mã tiền tệ ảo.
Thay đổi có dấu được áp dụng vào số dư. Giá trị dương là khoản ghi có, giá trị âm là khoản ghi nợ.
Số dư tiền tệ sau khi giao dịch này được áp dụng.
Các cặp key-value được lưu cùng giao dịch, nếu có.
Ý nghĩa của giao dịch. Adapty tự động thiết lập giá trị này cho các giao dịch do hệ thống tạo ra: store_purchase, subscription_renewal và trial_start nhận giá trị top_up, refund nhận giá trị refund, và expiry nhận giá trị expiry. Đối với dashboard_transaction, đây là thao tác mà thành viên trong nhóm đã chọn khi điều chỉnh số dư trong Adapty Dashboard. Đối với api_transaction, đây là giá trị bạn đã gửi, hoặc null nếu bạn không gửi giá trị nào.
One of: "top_up", "refund", "spend", "spend_reversal", "reward", "reward_reversal", "exchange", "expiry", "migration", "adjustment"
Mục đích sử dụng hoặc lý do cấp coins, theo giá trị bạn đã gửi. Giá trị null đối với các giao dịch do Adapty tạo ra.
ID màn hình hoặc placement từ ứng dụng của bạn, theo giá trị bạn đã gửi. Giá trị null đối với các giao dịch do Adapty tạo ra.
ID của đối tượng liên quan trong hệ thống của bạn, theo giá trị bạn đã gửi. Giá trị null đối với các giao dịch do Adapty tạo ra.
Cho biết giao dịch có phải là giao dịch thử nghiệm hay không. Đối với các giao dịch do Adapty tạo ra, giá trị này theo môi trường của giao dịch mua trong cửa hàng. Đối với api_transaction, đây là giá trị bạn đã gửi, mặc định là false.
Cửa hàng của giao dịch mua liên quan. Được thiết lập cho các giao dịch do Adapty tạo ra từ sự kiện cửa hàng (mua hàng, gia hạn, dùng thử, hoàn tiền) và cho api_transaction được gửi kèm tham chiếu giao dịch mua.
ID giao dịch trong cửa hàng của giao dịch mua liên quan. Được thiết lập cho cùng các giao dịch như store.
Thời điểm giao dịch được ghi lại.
Thời điểm phản hồi được tạo, dưới dạng Unix timestamp tính bằng mili giây.
Số dư sau giao dịch của từng loại tiền tệ bị ảnh hưởng bởi yêu cầu này (một mục cho mỗi phần tử trong items). Để xem toàn bộ danh sách số dư của hồ sơ người dùng, hãy sử dụng GET /api/v2/server-side-api/vc/balances/.
Mã tiền tệ ảo.
Tên hiển thị của tiền tệ ảo.
Tổng số dư, bao gồm các khoản đang được giữ.
Tổng của tất cả các khoản giữ đang hoạt động (số tiền đã đặt trước). Hiện tại luôn là 0.
Số dư có thể sử dụng, được tính bằng 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
}
]
} Yêu cầu không hợp lệ. Trường error_code xác định nguyên nhân:
validation_error— body hoặc headers không hợp lệ. Ví dụ: một trường gắn nhãn vi phạm định dạng,itemstrống hoặc có hơn 20 mục, mộtamountbằng 0 hoặc ngoài phạm vi int32, mã tiền tệ bị lặp lại,metadatavi phạm các ràng buộc, hoặc không cóadapty-profile-idlẫnadapty-customer-user-idnào được gửi.errors[].sourcechỉ ra trường bị lỗi. Đối với kiểm tra liên quan đến nhiều trường, chẳng hạn nhưstoređược gửi mà không cóstore_transaction_id,sourcelà chuỗi rỗng.parse_error— body không phải JSON hợp lệ.idempotency_key_invalid—Idempotency-Keykhông phải UUID v4.unknown_currency— tiền tệ chưa được thiết lập trong ứng dụng.unknown_store—storelà một cửa hàng tùy chỉnh chưa được thiết lập trong ứng dụng.insufficient_balance— một khoản trừ vượt quá số dư khả dụng.balance_overflow— một khoản cộng sẽ đưa số dư vượt quá phạm vi int32.
Schema
Nguồn gốc của lỗi
Mảng các thông báo lỗi
Tên lỗi rút gọn
Mã trạng thái 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
} Không được phép. API key bị thiếu hoặc không hợp lệ (error_code là not_authenticated).
Schema
Nguồn gốc của lỗi
Mảng các thông báo lỗi
Tên lỗi rút gọn
Mã trạng thái HTTP
Không tìm thấy hồ sơ người dùng (error_code là profile_does_not_exist).
Schema
Nguồn gốc của lỗi
Mảng các thông báo lỗi
Tên lỗi rút gọn
Mã trạng thái HTTP
Xung đột. Một yêu cầu với cùng Idempotency-Key vẫn đang được xử lý (error_code là idempotency_in_flight). Thử lại sau khoảng thời gian trong response header Retry-After.
Schema
Nguồn gốc của lỗi
Mảng các thông báo lỗi
Tên lỗi rút gọn
Mã trạng thái HTTP
Example
{
"errors": [
{
"source": null,
"errors": [
"A similar request is being processed."
]
}
],
"error_code": "idempotency_in_flight",
"status_code": 409
} Quá nhiều yêu cầu. Giới hạn tốc độ theo ứng dụng hoặc giới hạn toàn cục đã bị vượt quá (error_code là rate_limited). Giới hạn mặc định là 600 yêu cầu mỗi phút mỗi ứng dụng và 6000 yêu cầu mỗi phút trên toàn hệ thống.
Schema
Nguồn gốc của lỗi
Mảng các thông báo lỗi
Tên lỗi rút gọn
Mã trạng thái HTTP
Lỗi máy chủ nội bộ