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

Liệt kê các giao dịch tiền tệ ảo

Trả về lịch sử giao dịch tiền tệ ảo cho một hồ sơ người dùng, mới nhất trước. Kết quả sử dụng phân trang con trỏ: khi response bao gồm pagination.next_cursor khác null, hãy truyền lại giá trị đó dưới dạng tham số truy vấn cursor để lấy trang tiếp theo.

Query parameters

currency_codestring

Lọc lịch sử theo một mã tiền tệ ảo duy nhất.

cursorstring

Con trỏ phân trang mờ được trả về dưới dạng pagination.next_cursor trong response trước. Bỏ qua để lấy trang đầu tiên.

limitinteger

Số lượng giao dịch tối đa trả về mỗi trang. Mặc định là 50.

Header parameters

adapty-customer-user-idstring

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.

adapty-profile-idstring

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.

Responses

Lịch sử giao dịch được trả về thành công

Schema

Danh sách phân trang các giao dịch tiền tệ ảo cho một hồ sơ người dùng.

dataarray of objectrequired
transaction_idstringrequired

ID duy nhất của giao dịch.

transaction_typestringrequired

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.

itemsarray of objectrequired

Các thay đổi số dư theo từng loại tiền tệ được ghi lại trong giao dịch này.

currency_codestringrequired

Mã tiền tệ ảo.

amountintegerrequired

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

balance_afterintegerrequired

Số dư tiền tệ sau khi giao dịch này được áp dụng.

metadataobject

Các cặp key-value được lưu cùng giao dịch, nếu có.

operationstringrequired

Ý 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"

featurestringrequired

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.

customer_placement_idstringrequired

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.

reference_idstringrequired

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.

is_sandboxbooleanrequired

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.

storestringrequired

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.

store_transaction_idstringrequired

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.

created_atstringrequired

Thời điểm giao dịch được ghi lại.

paginationobjectrequired
next_cursorstringrequired

Con trỏ không rõ ràng cho trang tiếp theo. Truyền nó dưới dạng tham số truy vấn cursor để tải thêm kết quả. Null khi không còn trang nào nữa.

Example
{
  "data": [
    {
      "transaction_id": "0190e8a4-1c2b-7def-8abc-2c1a4b6d8e90",
      "transaction_type": "api_transaction",
      "items": [
        {
          "currency_code": "COINS",
          "amount": 500,
          "balance_after": 12950
        }
      ],
      "metadata": null,
      "operation": "reward",
      "feature": "daily_bonus",
      "customer_placement_id": "home-screen",
      "reference_id": null,
      "is_sandbox": false,
      "store": null,
      "store_transaction_id": null,
      "created_at": "2026-05-23T10:30:00Z"
    },
    {
      "transaction_id": "0190e7b2-9a44-7c10-bb31-7d2e9f0a1c55",
      "transaction_type": "store_purchase",
      "items": [
        {
          "currency_code": "COINS",
          "amount": 1000,
          "balance_after": 12450
        }
      ],
      "metadata": null,
      "operation": "top_up",
      "feature": null,
      "customer_placement_id": null,
      "reference_id": null,
      "is_sandbox": false,
      "store": "app_store",
      "store_transaction_id": "2000001218103228",
      "created_at": "2026-05-22T18:05:12Z"
    },
    {
      "transaction_id": "0190e5c0-3f18-7b9a-9e6d-44a1c8b27e03",
      "transaction_type": "subscription_renewal",
      "items": [
        {
          "currency_code": "GEMS",
          "amount": 200,
          "balance_after": 3280
        }
      ],
      "metadata": null,
      "operation": "top_up",
      "feature": null,
      "customer_placement_id": null,
      "reference_id": null,
      "is_sandbox": false,
      "store": "play_store",
      "store_transaction_id": "GPA.3345-1234-5678-90123",
      "created_at": "2026-05-20T09:00:00Z"
    }
  ],
  "pagination": {
    "next_cursor": "MjAyNi0wNS0yMFQwOTowMDowMFowMTkwZTVjMC0zZjE4LTdiOWEtOWU2ZC00NGExYzhiMjdlMDM="
  }
}

Yêu cầu không hợp lệ. Trường error_code xác định nguyên nhân:

  • validation_error — limit nằm ngoài phạm vi 1–100, hoặc không có adapty-profile-id lẫn adapty-customer-user-id nào được gửi.
  • invalid_cursor — giá trị cursor không thể phân tích được.
Schema
errorsarray of objectrequired
sourcestring

Nguồn gốc của lỗi

errorsarray of string

Mảng các thông báo lỗi

error_codestringrequired

Tên lỗi rút gọn

status_codeintegerrequired

Mã trạng thái HTTP

Không được phép. API key bị thiếu hoặc không hợp lệ (error_code là not_authenticated).

Schema
errorsarray of objectrequired
sourcestring

Nguồn gốc của lỗi

errorsarray of string

Mảng các thông báo lỗi

error_codestringrequired

Tên lỗi rút gọn

status_codeintegerrequired

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

Nguồn gốc của lỗi

errorsarray of string

Mảng các thông báo lỗi

error_codestringrequired

Tên lỗi rút gọn

status_codeintegerrequired

Mã trạng thái HTTP

Lỗi máy chủ nội bộ