Endpoint đơn hàng

Mỗi đơn hàng được tạo bằng một UUID do bạn sinh ra. UUID đó chính là idempotency key: gửi lại cùng UUID sẽ trả về đơn ban đầu chứ không trừ tiền lần hai. Sau đó, bạn có thể đọc trạng thái theo từng đơn, theo lô tối đa 50 đơn, hoặc dưới dạng danh sách phân trang.

POST

/orders/create

Tạo đơn hàng

Đặt đơn hàng mới. Bạn phải gửi một UUID duy nhất làm order_id để đảm bảo idempotency. Tiền sẽ bị trừ khỏi ví ngay lập tức.

Giới hạn tần suất5000 yêu cầu / 60 giây mỗi tài khoản

Lưu ý: order_id chính là idempotency key của bạn. Gửi lại với cùng UUID thì API trả về đơn đã có, không tạo đơn trùng.

Body yêu cầu

Tên	Kiểu	Bắt buộc	Mô tả	Ví dụ
order_id	string (UUID)	Có	UUID duy nhất cho đơn này (định dạng nào cũng được: v1, v4, v7, v.v.). Dùng làm idempotency key.	01912345-6789-7abc-8def-0123456789ab
sub_category_id	number	Có	ID danh mục con của sản phẩm.	999
quantity	number	Có	Số lượng cần đặt (số nguyên dương).	1
requirements	object	Có	Thông tin người chơi để giao hàng. Gửi đủ các trường mà endpoint "Lấy trường yêu cầu của danh mục" trả về.	{"player_id": "123456789", "server": "Asia"}
expected_unit_price	string	Không	Bảo vệ giá. Nếu giá hiện tại cao hơn giá trị này, đơn hàng sẽ bị từ chối.	0.950000

Yêu cầu

curl -s -X POST "https://shop2topup.com/api/endpoints/v1/orders/create" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "order_id": "01912345-6789-7abc-8def-0123456789ab",
  "sub_category_id": 999,
  "quantity": 1,
  "requirements": {
    "player_id": "123456789",
    "server": "Asia"
  },
  "expected_unit_price": 0.95
}'

Phản hồi mẫu

{
  "success": true,
  "order": {
    "order_id": "01912345-6789-7abc-8def-0123456789ab",
    "status": "pending",
    "player_id": "123456789",
    "player_name": "ProGamer99",
    "subcategory_name": "FF 100 Diamonds",
    "quantity": 1,
    "charged_amount": "0.950000",
    "currency": "USD",
    "created_at": "2024-06-15T12:00:00Z"
  }
}

GET

/orders/:orderId

Xem trạng thái đơn hàng

Xem trạng thái hiện tại và chi tiết của một đơn hàng.

Giới hạn tần suất3 yêu cầu / 60 giây cho mỗi cặp tài khoản + order_id

Lưu ý: Trạng thái đơn hàng là một trong các giá trị pending (chờ xử lý), completed (hoàn tất), refunded (đã hoàn tiền) hoặc partial (một số đơn vị đã giao, phần còn lại được hoàn tiền). Mỗi phần tử trong sub_transactions[] có status là pending, completed hoặc refunded; đơn vị nào chưa được giao hoặc hoàn tiền thì vẫn ở pending. Giá trị id trong sub_transactions[] là số thứ tự của đơn vị trong đơn hàng (1…n), không phải ID trong cơ sở dữ liệu. Các trường retry_count và max_retries, nếu xuất hiện, đã ngừng sử dụng và luôn bằng 0.

Tham số đường dẫn

Tên	Kiểu	Bắt buộc	Mô tả	Ví dụ
orderId	string (UUID)	Có	ID đơn hàng cần tra cứu.	01912345-6789-7abc-8def-0123456789ab

Yêu cầu

curl -s "https://shop2topup.com/api/endpoints/v1/orders/01912345-6789-7abc-8def-0123456789ab" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET"

Phản hồi mẫu

{
  "success": true,
  "order": {
    "order_id": "01912345-6789-7abc-8def-0123456789ab",
    "status": "completed",
    "player_id": "123456789",
    "player_name": "ProGamer99",
    "subcategory_name": "FF 100 Diamonds",
    "quantity": 1,
    "charged_amount": "0.950000",
    "currency": "USD",
    "created_at": "2024-06-15T12:00:00Z",
    "completed_at": "2024-06-15T12:00:05Z",
    "vouchers": [],
    "sub_transactions": [
      {
        "id": 1,
        "status": "completed",
        "player_id": "123456789",
        "player_name": "ProGamer99",
        "amount": "0.950000",
        "created_at": "2024-06-15T12:00:00Z",
        "completed_at": "2024-06-15T12:00:05Z"
      }
    ]
  }
}

POST

/orders/batch

Lấy nhiều đơn hàng cùng lúc

Lấy nhiều đơn hàng cùng lúc theo ID. Mỗi yêu cầu tối đa 50 ID đơn hàng.

Giới hạn tần suất2 yêu cầu / 60 giây cho mỗi tài khoản

Body yêu cầu

Tên	Kiểu	Bắt buộc	Mô tả	Ví dụ
order_ids	string[]	Có	Mảng UUID của đơn hàng (tối đa 50).	["uuid-1", "uuid-2"]

Yêu cầu

curl -s -X POST "https://shop2topup.com/api/endpoints/v1/orders/batch" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "order_ids": [
    "uuid-1",
    "uuid-2"
  ]
}'

Phản hồi mẫu

{
  "success": true,
  "orders": [
    {
      "order_id": "01912345-6789-7abc-8def-0123456789ab",
      "status": "completed",
      "charged_amount": "0.950000"
    }
  ],
  "not_found": [
    "uuid-that-does-not-exist"
  ]
}

GET

/orders

Danh sách đơn hàng

Lấy danh sách đơn hàng của bạn theo từng trang, có thể lọc thêm theo trạng thái và khoảng ngày.

Giới hạn tần suất2 yêu cầu / 60 giây cho mỗi tài khoản

Tham số query

Tên	Kiểu	Bắt buộc	Mô tả	Ví dụ
page	number	Không	Số trang (mặc định: 1).	1
limit	number	Không	Số kết quả mỗi trang, 1-100 (mặc định: 50).	50
status	string	Không	Lọc theo trạng thái: pending, completed, refunded hoặc partial.	completed
created_after	string (ISO 8601)	Không	Chỉ lấy các đơn hàng được tạo sau ngày này.	2024-01-01T00:00:00Z
created_before	string (ISO 8601)	Không	Chỉ lấy các đơn hàng được tạo trước ngày này.	2024-12-31T23:59:59Z

Yêu cầu

curl -s "https://shop2topup.com/api/endpoints/v1/orders?page=1&limit=50&status=completed&created_after=2024-01-01T00:00:00Z&created_before=2024-12-31T23:59:59Z" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET"

Phản hồi mẫu

{
  "success": true,
  "orders": [
    {
      "order_id": "01912345-6789-7abc-8def-0123456789ab",
      "status": "completed",
      "subcategory_name": "FF 100 Diamonds",
      "quantity": 1,
      "charged_amount": "0.950000",
      "created_at": "2024-06-15T12:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "total_pages": 1
  }
}

Gửi yêu cầu thật ngay trên trang này

Dán khóa API để gọi trực tiếp các endpoint này. Khóa chỉ nằm trong tab trình duyệt này và chỉ được gửi tới chính API.

Enter your API key to use the interactive playground. Get your API key

Chọn endpoint

Order Details

Enter your API key above to try this endpoint.

Nếu bạn mới dùng nền tảng, hãy bắt đầu với trang tổng quan API nạp game dành cho đại lý, hoặc đọc tổng quan chương trình đại lý SHOP2TOPUP để biết tài khoản đối tác hoạt động ra sao.