Endpoint pesanan

Pesanan dibuat menggunakan UUID yang anda jana sendiri. UUID itu ialah kunci idempotensi: jika dihantar semula, pesanan asal dipulangkan dan tiada caj dikenakan kali kedua. Status kemudian boleh dibaca bagi setiap pesanan, secara kelompok sehingga 50 pesanan, atau sebagai senarai berhalaman.

POST

/orders/create

Buat pesanan

Buat pesanan baharu. Anda mesti memberikan UUID unik sebagai order_id untuk idempotensi. Dompet akan dicaj serta-merta.

Had kadar5000 permintaan / 60 saat setiap akaun

Nota: order_id ialah kunci idempotensi anda. Jika anda mencuba semula dengan UUID yang sama, pesanan sedia ada akan dipulangkan dan tiada pesanan berganda dibuat.

Body permintaan

Nama	Jenis	Wajib	Penerangan	Contoh
order_id	string (UUID)	Ya	UUID unik untuk pesanan ini (sebarang format: v1, v4, v7 dan lain-lain). Digunakan sebagai kunci idempotensi.	01912345-6789-7abc-8def-0123456789ab
sub_category_id	number	Ya	ID subkategori produk.	999
quantity	number	Ya	Bilangan unit yang ingin dipesan (integer positif).	1
requirements	object	Ya	Maklumat penghantaran pemain. Sertakan semua medan yang dipulangkan oleh endpoint keperluan kategori.	{"player_id": "123456789", "server": "Asia"}
expected_unit_price	string	Tidak	Perlindungan harga. Jika harga semasa melebihi nilai ini, pesanan akan ditolak.	0.950000

Permintaan

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
}'

Contoh respons

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

Dapatkan status pesanan

Dapatkan status semasa dan butiran pesanan tertentu.

Had kadar3 permintaan / 60 saat setiap akaun + order_id

Nota: Status pesanan ialah pending (menunggu), completed (selesai), refunded (bayaran balik) atau partial, iaitu sebahagian unit sudah dihantar dan selebihnya dibayar balik. Setiap sub_transactions[].status pula bernilai pending, completed atau refunded; unit kekal pending sehingga ia dihantar atau dibayar balik. Nilai sub_transactions[].id ialah indeks unit dalam pesanan (1…n), bukan ID pangkalan data. Medan retry_count dan max_retries, jika ada, tidak digunakan lagi dan sentiasa 0.

Parameter laluan

Nama	Jenis	Wajib	Penerangan	Contoh
orderId	string (UUID)	Ya	ID pesanan yang ingin disemak.	01912345-6789-7abc-8def-0123456789ab

Permintaan

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

Contoh respons

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

Dapatkan pesanan secara pukal

Dapatkan beberapa pesanan sekali gus menggunakan ID pesanan. Maksimum 50 ID pesanan bagi setiap permintaan.

Had kadar2 permintaan / 60s bagi setiap akaun

Body permintaan

Nama	Jenis	Wajib	Penerangan	Contoh
order_ids	string[]	Ya	Array UUID pesanan (maksimum 50).	["uuid-1", "uuid-2"]

Permintaan

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"
  ]
}'

Contoh respons

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

Senarai pesanan

Senaraikan pesanan anda mengikut halaman, dengan penapis pilihan untuk status dan julat tarikh.

Had kadar2 permintaan / 60s bagi setiap akaun

Parameter query

Nama	Jenis	Wajib	Penerangan	Contoh
page	number	Tidak	Nombor halaman (lalai: 1).	1
limit	number	Tidak	Bilangan hasil setiap halaman, 1-100 (lalai: 50).	50
status	string	Tidak	Tapis mengikut status: pending, completed, refunded, partial.	completed
created_after	string (ISO 8601)	Tidak	Tapis pesanan yang dibuat selepas tarikh ini.	2024-01-01T00:00:00Z
created_before	string (ISO 8601)	Tidak	Tapis pesanan yang dibuat sebelum tarikh ini.	2024-12-31T23:59:59Z

Permintaan

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"

Contoh respons

{
  "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
  }
}

Hantar permintaan sebenar dari halaman ini

Tampal kunci API untuk memanggil endpoint ini secara langsung. Kunci itu kekal dalam tab pelayar ini dan hanya dihantar kepada API.

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

Pilih endpoint

Order Details

Enter your API key above to try this endpoint.

Jika anda baru di platform ini, mulakan dengan gambaran keseluruhan API top up game untuk reseller, atau baca gambaran keseluruhan program reseller SHOP2TOPUP untuk mengetahui cara akaun rakan kongsi berfungsi.