การชำระเงิน Web PG
API การชำระเงิน PG บนเว็บคือ API ที่ใช้เมื่อคุณต้องการนำการชำระเงิน PG ไปใช้ในเว็บไซต์ แม้ว่าจะไม่ใช้ Hive SDK billing เมื่อพัฒนาแอป Windows API การชำระเงิน PG บนเว็บจะแตกต่างจาก API ที่ใช้การชำระเงิน PG ในแอป
Note
ในการใช้การชำระเงิน PG ในแอป คุณต้องใช้ Hive SDK Billing และ General PG Payment API.
การสอบถามรายการสินค้า¶
ดึงข้อมูลผลิตภัณฑ์ ใช้ในการ implement รายการผลิตภัณฑ์ในแอป
URL คำขอ¶
สภาพแวดล้อม | URL |
---|---|
URL การผลิต | https://store.withhive.com/external/api/product |
URL แซนด์บ็อกซ์ | https://sandbox-store.withhive.com/external/api/product |
วิธีการ HTTP | POST |
ประเภทเนื้อหา | text/html; charset=utf-8 |
รูปแบบข้อมูล | JSON |
การอนุญาต | Bearer (token) |
โทเค็น Bearer จะตรงกับ Hive คีย์การรับรองความถูกต้องใน App Center > การจัดการโครงการ > เลือกบริษัทเกม > รายละเอียดเกม > ข้อมูลพื้นฐาน ใน Hive Console.
พารามิเตอร์คำขอ¶
ฟิลด์ | ประเภท | จำเป็น | คำอธิบาย |
---|---|---|---|
api | String | O | ตัวระบุ API (`product` ค่าคงที่) |
market_id | String | O | Hive รหัสตลาด (การชำระเงิน PG: `15` ค่าคงที่) |
appid | String | O | Hive รหัสแอป |
hive_country | String | O | รหัสประเทศ (ISO 3166-1 สองตัวอักษร) |
game_language | String | O | ภาษา (ISO 639-1 สองตัวอักษร) |
vid | String | O | Hive ข้อมูลบัญชี (Player ID) |
vid_type | String | O | ประเภทบัญชี (สำหรับเกมใหม่, v4) |
market_pid_type | String | O | ประเภทผลิตภัณฑ์ (ใช้ซ้ำได้: ใช้ซ้ำได้) |
องค์ประกอบการตอบกลับ¶
ฟิลด์ | ประเภท | จำเป็น | คำอธิบาย |
---|---|---|---|
result | จำนวนเต็ม | O | รหัสตอบกลับ (0 คือสำเร็จ, อื่นๆ คือข้อผิดพลาด) |
result_msg | สตริง | O | ข้อความตอบกลับ |
product_list | วัตถุ | O | รายการข้อมูลผลิตภัณฑ์ |
product_list > market_pid | สตริง | O | PID ของผลิตภัณฑ์ |
product_list > price | จำนวนเต็ม | O | ราคาผลิตภัณฑ์ (ค่าตัวเลข) |
product_list > currency | สตริง | O | สกุลเงินของราคาผลิตภัณฑ์ |
product_list > display_price | สตริง | O | ราคาผลิตภัณฑ์ (รวมสัญลักษณ์สกุลเงิน) |
product_list > title | สตริง | O | ชื่อผลิตภัณฑ์ |
product_list > description | สตริง | O | คำอธิบายผลิตภัณฑ์ |
product_list > product_type | สตริง | O | ประเภทผลิตภัณฑ์ (ใช้แล้วหมดไป) |
update_date | สตริง | O | วันที่และเวลาที่อัปเดตล่าสุดสำหรับข้อมูล PID ของผลิตภัณฑ์ |
ตัวอย่างคำขอ¶
curl -L -v \
-d '{"api": "product","market_id": 15,"appid": "com.com2us.hivesdk.windows.microsoftstore.global.normal","hive_country": "KR","game_language": "ko","vid": "100000000000","vid_type": "v4","market_pid_type": "consumable"}' \
-H "Content-Type: text/html" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNjAyMDU2NzI2LCJqdGkiOiIxODczMTExMzIwIn0.3soFiHTPlObCoqR5xX9ZeOQTSvnHrHDHWmopP3QfWtY" \
https://sandbox-store.withhive.com/external/api/product
ตัวอย่างการตอบกลับ¶
{
"result": 0,
"result_msg": "success",
"product_list": [
{
"market_pid": "com.com2us.hivesdk.windows.microsoftstore.global.normal.item01",
"price": 1200,
"currency": "KRW",
"display_price": "₩1,200",
"title": "크리스탈 한 줌",
"description": "크리스탈 한 줌",
"product_type": "consumable"
}, {
"market_pid": "com.com2us.hivesdk.windows.microsoftstore.global.normal.item02",
"price": 2500,
"currency": "KRW",
"display_price": "₩2,500",
"title": "크리스탈 묶음",
"description": "크리스탈 묶음",
"product_type": "consumable"
}, {
"market_pid": "com.com2us.hivesdk.windows.microsoftstore.global.normal.item03",
"price": 3900,
"currency": "KRW",
"display_price": "₩3,900",
"title": "크리스탈 더미",
"description": "크리스탈 더미",
"product_type": "consumable"
}
],
"update_date": "2022-10-28 16:11:23"
}
การขอคำสั่งซื้อสินค้า¶
ทำการขอสั่งซื้อผลิตภัณฑ์โดยใช้ข้อมูล PID
(Product ID) ที่เลือกจากรายการผลิตภัณฑ์
URL การร้องขอ¶
สภาพแวดล้อม | URL |
---|---|
Production URL | https://store.withhive.com/external/api/order |
Sandbox URL | https://sandbox-store.withhive.com/external/api/order |
HTTP Method | POST |
Content-Type | text/html; charset=utf-8 |
Data Type | JSON |
Authentication | Bearer (token) |
โทเค็น Bearer จะตรงกับ Hive คีย์การตรวจสอบสิทธิ์ใน App Center > การจัดการโครงการ > เลือกบริษัทเกม > รายละเอียดเกม > ข้อมูลพื้นฐาน ใน Hive Console.
พารามิเตอร์คำขอ¶
ฟิลด์ | ประเภท | จำเป็น | คำอธิบาย |
---|---|---|---|
market_id | string | O | Hive รหัสตลาด |
appid | string | O | Hive Appid |
hive_country | string | O | รหัสประเทศ (ISO 3166-1 2 ตัวอักษร) |
game_language | string | O | ภาษา (ISO 639-1 สองตัวอักษร) |
vid | string | O | Hive ข้อมูลบัญชี (รหัสผู้เล่น) |
vid_type | string | O | ประเภทบัญชี (สำหรับเกมใหม่, v4) |
market_pid | string | O | รหัสผลิตภัณฑ์ |
server_id | string | O | รหัสเซิร์ฟเวอร์ |
os | string | O | Windows: W, MAC: M, Android: A |
quantity | integer | X | จำนวนที่ซื้อ (ค่าเริ่มต้นเป็น 1 หากไม่ได้ส่ง) |
iap_payload | string | X | ข้อมูลเมตาของการซื้อที่กำหนดโดยนักพัฒนาแอป ที่นี่ |
fixed_currency | String | X | สกุลเงินที่จะแสดงสำหรับวิธีการชำระเงิน (ISO 4217 รหัสสามตัวอักษร) * นี่ไม่ใช่ค่าที่จำเป็น หากพารามิเตอร์ fixed_currency ไม่รวมอยู่ในคำขอ วิธีการชำระเงินจะแสดงตาม hive_country อย่างไรก็ตาม หากพารามิเตอร์ fixed_currency รวมอยู่ด้วย วิธีการชำระเงินจะแสดงตามสกุลเงินที่ระบุ |
refund_idx | Integer | X | รายการ IDX การคืนเงินผู้ใช้ * จำเป็นเฉพาะเมื่อขอคืนเงินสำหรับผู้ใช้ที่ได้รับเงินคืน |
is_repayment | Integer | X | ธงการคืนเงินสำหรับผู้ใช้ที่ได้รับเงินคืน (0: การชำระเงินปกติ, 1: การคืนเงินสำหรับผู้ใช้ที่ได้รับเงินคืน) * จำเป็นเฉพาะเมื่อขอคืนเงินสำหรับผู้ใช้ที่ได้รับเงินคืน |
expiration_time | Integer | X | นี่คือเวลาหมดอายุสำหรับหน้าต่างการชำระเงิน ใช้ Unix TimeStamp ในรูปแบบมิลลิวินาที (เช่น 1745395211) หากเวลาปัจจุบันบนเซิร์ฟเวอร์เรียกเก็บเงินของ Hive (Unix TimeStamp ในมิลลิวินาที) เกินค่านี้ เซิร์ฟเวอร์จะส่งคืนหน้าคำแนะนำทางเลือกแทนหน้าต่าง HTML การชำระเงิน |
ตัวอย่างคำขอ¶
curl -L -v \
-d '{"market_id": 15,"appid": "com.com2us.hivesdk.windows.microsoftstore.global.normal","hive_country": "KR","game_language": "ko","vid": "100000000000","vid_type": "v4","market_pid": "com.com2us.hivesdk.windows.microsoftstore.global.normal.item01","server_id": "KR1","os": "A","quantity": 1,"iap_payload": "{\"character_id\":\"hivesdk01\"}", "expiration_time": 1745395211}' \
-H "Content-Type: text/html" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNjAyMDU2NzI2LCJqdGkiOiIxODczMTExMzIwIn0.3soFiHTPlObCoqR5xX9ZeOQTSvnHrHDHWmopP3QfWtY" \
https://sandbox-store.withhive.com/external/api/order
ตัวอย่างการตอบกลับ¶
เมื่อคำขอการสั่งซื้อผลิตภัณฑ์ได้รับการประมวลผลอย่างสำเร็จ มันจะส่งคืนหน้าต่างป๊อปอัปเพื่อเลือกวิธีการชำระเงิน ด้านล่างนี้คือหน้า HTML ที่ประกอบขึ้นเป็นหน้าต่างป๊อปอัป
การสอบถามรายละเอียดการชำระเงิน¶
เมื่อการชำระเงินเสร็จสมบูรณ์ หน่วยงานการชำระเงิน (PG) จะส่งผลการชำระเงินไปยังเซิร์ฟเวอร์ Hive IAP v4 โดยตรง วิธีนี้ช่วยชดเชยความไม่เสถียรของเครือข่ายและป้องกันการดัดแปลงข้อมูลการชำระเงิน ในระหว่างการ การเตรียมงาน จะมีการตรวจสอบความถูกต้องโดยการเปรียบเทียบข้อมูลการชำระเงินที่ลงทะเบียนกับข้อมูลของหน่วยงานการชำระเงิน (PG) เมื่อยืนยันความสมบูรณ์ของข้อมูลการชำระเงินได้แล้ว มาตรการความปลอดภัยเพิ่มเติมจะถูกจัดเตรียมและข้อมูลการชำระเงินจะถูกเก็บรักษา ข้อมูลการชำระเงินที่เก็บรักษาสามารถเรียกคืนได้ผ่าน API การสอบถามประวัติการชำระเงินที่เสร็จสมบูรณ์
ลูกค้าขอข้อมูลจากเซิร์ฟเวอร์เกมในช่วงเวลาที่ต้องการข้อมูลการชำระเงินของผู้ใช้ และเซิร์ฟเวอร์เกมจะดึงข้อมูลการชำระเงินผ่านเซิร์ฟเวอร์ Hive IAP v4 หากมีบันทึกการชำระเงินของผู้ใช้ การตรวจสอบข้อมูลการชำระเงินจะดำเนินการโดยใช้ purchase_bypass_info
。
URL ที่ร้องขอ¶
URL การผลิต | https://hiveiap.qpyou.cn/api_v4/purchases/unconsumed |
URL แซนด์บ็อกซ์ | https://sandbox-hiveiap.qpyou.cn/api_v4/purchases/unconsumed |
วิธีการ HTTP | POST |
ประเภทเนื้อหา | application/json |
รูปแบบข้อมูล | JSON |
การอนุญาต | Bearer (token) |
---|
โทเค็น Bearer จะตรงกับ Hive คีย์การตรวจสอบสิทธิ์ใน App Center > การจัดการโครงการ > เลือกบริษัทเกม > รายละเอียดเกม > ข้อมูลพื้นฐาน ใน Hive Console.
พารามิเตอร์การร้องขอ¶
ชื่อ | ประเภท | จำเป็น (จำเป็น: M, ไม่จำเป็น: O) | คำอธิบาย |
appid | String | M | ID ที่ลงทะเบียนและออกจาก Hive คอนโซล > App Center |
market_id | Number | M | หมายเลขตลาดที่ไม่ซ้ำกัน (ใช้ค่าคงที่ `15`) |
server_id | String | M | รหัสการระบุเซิร์ฟเวอร์เกมที่การชำระเงินเกิดขึ้น |
user_id_type | String | M | ประเภทผู้ใช้ HIVE uid : โมดูลบุคคล (v0) vid : การตรวจสอบสิทธิ์ v1 (v1) player_id : การตรวจสอบสิทธิ์ v4 (v4) |
user_id | Number | M | รหัสผู้ใช้ HIVE ส่งตามประเภท user_id uid : โมดูลบุคคล (v0) vid : การตรวจสอบสิทธิ์ v1 (v1) player_id : การตรวจสอบสิทธิ์ v4 (v4) |
องค์ประกอบการตอบกลับ¶
ชื่อ | ประเภท | จำเป็น (จำเป็น: M, ไม่จำเป็น: O) | คำอธิบาย |
result | หมายเลข | M | รหัสการตอบกลับ (0: สำเร็จ) |
result_msg | ข้อความ | M | ข้อความผลลัพธ์ตามรหัสการตอบกลับ |
unconsumed_lists | อาเรย์วัตถุ | M | |
┕ market_pid | ข้อความ | M | รหัสประจำผลิตภัณฑ์ |
┕ order_id | ข้อความ | M | หมายเลขคำสั่งซื้อ |
┕ server_id | ข้อความ | M | รหัสที่แยกความแตกต่างของเซิร์ฟเวอร์เกมที่ผู้ใช้ซื้อจาก |
┕ vid | ข้อความ | M | PlayerID ของผู้ใช้, VID สำหรับการตรวจสอบสิทธิ์ v1 |
┕ uid | ข้อความ | O | uid ของผู้ใช้ |
┕ amount | ข้อความ | M | จำนวนเงินที่ชำระ |
┕ currency | ข้อความ | M | สกุลเงินที่ใช้ในการชำระเงิน |
┕ quantity | หมายเลข | M | จำนวนที่ซื้อ |
┕ started_datetime | วันที่และเวลา | M | เวลาที่เริ่มชำระเงิน (Y-m-d H:i:s) |
┕ paid_datetime | วันที่และเวลา | M | เวลาที่ชำระเงินเสร็จสมบูรณ์ (Y-m-d H:i:s) |
┕ started_datetime_ms | หมายเลข | M | เวลาที่เริ่มชำระเงิน (Unix TimeStamp Milliseconds) |
┕ paid_datetime_ms | หมายเลข | M | เวลาที่ชำระเงินเสร็จสมบูรณ์ (Unix TimeStamp Milliseconds) |
┕ hiveiap_receipt | ข้อความ | M | การเข้ารหัสข้อมูลการชำระเงิน HASH |
┕ purchase_bypass_info | ข้อความ | M | ข้อมูลที่จำเป็นสำหรับคำขอการตรวจสอบใบเสร็จ |
┕ iap_payload | ข้อความ | O | ข้อมูลเพิ่มเติมที่ได้รับจากลูกค้าเพื่อนำส่งไปยังเซิร์ฟเวอร์เกม (ในรูปแบบ JSON String) (จะส่งคืน null หากไม่ได้รับข้อมูล) |
ตัวอย่างคำขอ¶
curl -L -v
-d '{"appid" : "com.com2us.hivesdk.windows.microsoftstore.global.normal","market_id" : 15,"server_id" : "kr","user_id_type": "player_id", "user_id": 30000056996}' \
-H "Content-Type: text/html" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNjAyMDU2NzI2LCJqdGkiOiIxODczMTExMzIwIn0.3soFiHTPlObCoqR5xX9ZeOQTSvnHrHDHWmopP3QfWtY" \
https://sandbox-hiveiap.qpyou.cn/api_v4/purchases/unconsumed
ตัวอย่างการตอบกลับ¶
{
"result": 0,
"result_msg": "SUCCESS",
"unconsumed_lists": [
{
"market_pid": "com.com2us.hivesdk.windows.microsoftstore.global.normal.item01",
"order_id": "h2164792542890731850",
"server_id": "kr",
"vid": "30000056996",
"uid": "13079",
"amount": "1200",
"currency": "KRW",
"quantity": 1,
"started_datetime": "2022-03-22 14:03:49",
"paid_datetime": "2022-03-22 14:04:39",
"market_id": "15",
"hiveiap_receipt": "2YnGzfTCGycoMjcSyYyNXBjANwmFyB6m\/c0bYazQ8VQ=",
"purchase_bypass_info": "eyJtYXJrZXRfcGlkIjoiY29tLmNvbTJ1cy5oaXZlc2R...",
"started_datetime_ms": 1647925429000,
"paid_datetime_ms": 1647925479000,
"iap_payload": null
}
]
}
การตรวจสอบข้อมูลการชำระเงิน¶
API การตรวจสอบผลการชำระเงินอิงจาก การตรวจสอบใบเสร็จ IAP v4.
การตรวจสอบผลการชำระเงินใช้ purchase_bypass_info
ที่ได้รับมาก่อนหน้านี้ purchase_bypass_info
ประกอบด้วยข้อมูลต่างๆ ที่ได้รับผ่าน SDK ก่อนที่จะดำเนินการชำระเงินและถูกส่งไปยัง Hive Analytics หากคุณต้องการส่ง บันทึกการขาย พร้อมกับคำขอการตรวจสอบใบเสร็จ ให้ใช้ game_info
ข้อมูล game_info
ที่ได้รับทำหน้าที่เป็นตัวกลางในการส่งบันทึกไปยังเซิร์ฟเวอร์วิเคราะห์จาก Hive IAP
URL ขอ¶
URL การผลิต | https://hiveiap-verify.qpyou.cn/api_v4/verify |
URL แซนด์บ็อกซ์ | https://sandbox-hiveiap-verify.qpyou.cn/api_v4/verify |
วิธีการ HTTP | POST |
ประเภทเนื้อหา | text/html |
รูปแบบข้อมูล | JSON |
การอนุญาต | Bearer (token) |
---|
โทเค็น Bearer จะตรงกับ Hive คีย์การตรวจสอบสิทธิ์ใน App Center > การจัดการโครงการ > เลือกบริษัทเกม > รายละเอียดเกม > ข้อมูลพื้นฐาน ใน Hive Console.
พารามิเตอร์การร้องขอ¶
ชื่อ | ประเภท | จำเป็น (จำเป็น: M, ไม่จำเป็น: O) | คำอธิบาย |
purchase_bypass_info | String | M | ข้อมูลสำหรับการแทนที่ใบเสร็จและการส่งข้อมูลวิเคราะห์ |
game_info | Object Array | O | หากมีบันทึกที่จะส่งไปยังเกม เช่น บันทึกเกมหรือบันทึกการขาย ให้เพิ่มค่าดังกล่าวไปยังเกมเพื่อการส่งข้อมูล และ Hive IAP จะทำหน้าที่เป็นตัวแทนในการส่งไปยังเซิร์ฟเวอร์วิเคราะห์ ในขั้นตอนการตรวจสอบใบเสร็จ จะไม่สามารถทราบได้ว่ารายการได้ถูกส่งแล้ว (itemsendok) ดังนั้นส่วนนี้ต้องดำเนินการแยกต่างหากและจัดเตรียมเป็นข้อมูลเพิ่มเติม |
⠀⠀server_uid | bigint | O | user_id ที่ออกโดยเซิร์ฟเวอร์เกม หากไม่มี ให้ใช้ 0 |
⠀⠀giftee_uid | bigint | O | null: การชำระเงินเพื่อการใช้งานส่วนตัว 0: ผู้รับมีอยู่แต่ไม่สามารถตรวจสอบ UID ได้; บัญชีแขก Derby Days ไม่มีบัญชีแขกฮับ ดังนั้นจึงใช้ที่นี่ |
⠀⠀level | int | O | ระดับในเกมของผู้ใช้ ไม่จำเป็นหากไม่มีระดับ หากไม่มี ให้ใช้ 0. |
⠀⠀character_id | bigint | O | ตัวระบุตัวละครที่ไม่ซ้ำกันภายในเซิร์ฟเวอร์ (PK?). หากไม่มีแนวคิดตัวละคร ให้ใช้ "0" |
⠀⠀character_type_id | int | O | ตัวระบุตัวละครประเภท สำหรับเกมที่ไม่มีแนวคิดตัวละคร ให้ป้อน "0" |
⠀⠀character_level | int | O | ตัวระบุตัวละครประเภท สำหรับเกมที่ไม่มีแนวคิดตัวละคร ให้ป้อน "0" |
⠀⠀is_emulator | int | O | หากเข้าถึงผ่านอีมูเลเตอร์สำหรับ PC เช่น BlueStacks ให้ป้อน "1"; มิฉะนั้นให้ป้อน "0" |
องค์ประกอบการตอบกลับ¶
ชื่อ | ประเภท | จำเป็น (จำเป็น: M, ไม่จำเป็น: O) | คำอธิบาย |
result | หมายเลข | M | รหัสการตอบกลับ (ดูที่รหัสการตอบกลับ) |
result_msg | สตริง | M | ข้อความผลลัพธ์ตามรหัสการตอบกลับ |
hiveiap_transaction_id | สตริง | M | รหัสธุรกรรมที่สร้างขึ้นสำหรับใบเสร็จที่ตรวจสอบแล้วแต่ละใบ ค่านี้ควรเก็บไว้ในเซิร์ฟเวอร์เกมเพื่อทำการตรวจสอบใบเสร็จซ้ำ |
hiveiap_market_id | สตริง | O | หมายเลขเฉพาะของตลาด (การชำระเงิน PG: กำหนดที่ 15) |
hiveiap_market_pid | สตริง | O | PID ของผลิตภัณฑ์การชำระเงิน |
hiveiap_market_transaction_id | สตริง | O | หมายเลขคำสั่งซื้อเฉพาะสำหรับคำสั่งซื้อ |
hiveiap_receipt | สตริง | O | ค่าของวัตถุใบเสร็จตลาด (การชำระเงิน PG: กำหนดที่ null) |
hiveiap_purchase_test | สตริง | O | สถานะการชำระเงินทดสอบ (Y: การชำระเงินทดสอบ / N: การชำระเงินปกติ) |
รหัสการตอบกลับ¶
รหัส | ข้อความ | หมายเหตุ |
0 | สำเร็จ, ใบเสร็จซ้ำ | การตรวจสอบสำเร็จ |
1000001 | ไม่มีพารามิเตอร์ที่ร้องขอ | เมื่อไม่มีพารามิเตอร์ที่ส่งมา |
1000003 | ข้อผิดพลาดการเชื่อมต่อฐานข้อมูล | เมื่อการเชื่อมต่อฐานข้อมูลล้มเหลว |
1000005 | ข้อผิดพลาดของเซิร์ฟเวอร์ภายใน | ข้อผิดพลาดของเซิร์ฟเวอร์ภายใน |
1000006 | ข้อมูลพารามิเตอร์ที่จำเป็นขาดหายไป | เมื่อค่าพารามิเตอร์ที่จำเป็นขาดหายไป |
1000503 | ไม่สามารถตรวจสอบใบเสร็จได้ | ไม่สามารถตรวจสอบใบเสร็จได้หรือเป็นใบเสร็จที่ถูกแฮ็ก (เช่น การแฮ็กการปลอมแปลง) |
1000507 | ไม่สามารถบันทึกข้อมูลการซื้อได้ | ไม่สามารถบันทึกประวัติการซื้อได้ |
1000524 | ไม่สามารถตรวจสอบใบเสร็จได้ (คำสั่งไม่อยู่) | การตรวจสอบใบเสร็จล้มเหลว (คำสั่งที่ไม่มีอยู่) |
1000525 | ไม่สามารถตรวจสอบใบเสร็จได้ (พารามิเตอร์ผิด) | การตรวจสอบใบเสร็จล้มเหลว (ข้อผิดพลาดพารามิเตอร์) |
ตัวอย่างคำขอ¶
curl -L -v \
-d '{"purchase_bypass_info":"eyJtYXJrZXRfaWQiOiIxNSIsIm9yZGVyX2lkIjoiSDMxNjQ3OTI1NDI4OTA3MzE4NTAiLCJtYXJrZXRfcGlkIjoiY29tLmNvbTJ1cy5oaXZlc2RrLndpbmRvd3MubWljcm9zb2Z0c3RvcmUuZ2xvYmFsLm5vcm1hbC5pdGVtMDEiLCJ2aWQiOiIzMDAwMDA1Njk5NiIsInVpZCI6IjEzMDc5Iiwic2VydmVyX2lkIjoia3IiLCJhcHBpZCI6ImNvbS5jb20ydXMuaGl2ZXNkay53aW5kb3dzLm1pY3Jvc29mdHN0b3JlLmdsb2JhbC5ub3JtYWwiLCJhbW91bnQiOiIxMjAwIiwic3RhcnRlZF9kYXRldGltZSI6bnVsbCwicGFpZF9kYXRldGltZSI6bnVsbCwiY3VycmVuY3kiOiJLUlciLCJoaXZlaWFwX3JlY2VpcHQiOiIyWW5HemZUQ0d5Y29NamNTeVl5TlhCakFOd21GeUI2bVwvYzBiWWF6UThWUT0ifQ=="}' \
-H "Content-Type: text/html" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNjAyMDU2NzI2LCJqdGkiOiIxODczMTExMzIwIn0.3soFiHTPlObCoqR5xX9ZeOQTSvnHrHDHWmopP3QfWtY" \
https://sandbox-hiveiap-verify.qpyou.cn/api_v4/verify
ตัวอย่างการตอบกลับ¶
{
"result": 0,
"result_msg": "success",
"hiveiap_transaction_id": "HS_13",
"hiveiap_market_id": 15,
"hiveiap_market_pid": "com.com2us.hivesdk.windows.microsoftstore.global.normal.item01",
"hiveiap_market_transaction_id": "h2164792542890731850",
"hiveiap_receipt": null,
"hiveiap_purchase_test": "N"
}
การประมวลผลผลลัพธ์การชำระเงิน¶
API การประมวลผลผลลัพธ์การชำระเงิน อิงจาก การส่งผลลัพธ์การชำระเงิน IAP v4 API การประมวลผลผลลัพธ์การชำระเงินจะทำให้กระบวนการชำระเงินเสร็จสมบูรณ์ตั้งแต่การซื้อสินค้าไปจนถึงการชำระเงินเสร็จสิ้น หากกระบวนการชำระเงินยังไม่เสร็จสมบูรณ์ ผู้ใช้จะไม่สามารถซื้อผลิตภัณฑ์เดียวกันได้ เมื่อพยายามซื้อและเข้าสู่หน้าชำระเงิน จะมีข้อความแสดงว่า 'คุณเป็นเจ้าของผลิตภัณฑ์นี้แล้ว' และการชำระเงินจะไม่ดำเนินการต่อ
เมื่อพยายามซื้อและชำระเงินโดยการเปิดหน้าต่างการชำระเงินหลายหน้าต่าง ผลิตภัณฑ์ใด ๆ ที่การชำระเงินยังไม่ได้ดำเนินการจะถูกยกเลิกโดยอัตโนมัติ หลังจากดำเนินการตามขั้นตอนการชำระเงินทั้งหมด เช่น การตรวจสอบขีดจำกัดการซื้อและการจัดส่งสินค้าโดยเซิร์ฟเวอร์เกม ผลลัพธ์การชำระเงินจะถูกส่งไปยังเซิร์ฟเวอร์ Hive IAP v4 เพื่อแจ้งว่าการชำระเงินเสร็จสมบูรณ์ หากคุณต้องการขอยกเลิกการชำระเงิน คุณยังสามารถขอยกเลิกผ่าน API การประมวลผลผลลัพธ์การจัดส่งได้
URL ที่ขอ¶
URL การผลิต | https://hiveiap.qpyou.cn/api_v4/item_result |
URL แซนด์บ็อกซ์ | https://sandbox-hiveiap.qpyou.cn/api_v4/item_result |
วิธีการ HTTP | POST |
ประเภทเนื้อหา | text/html |
รูปแบบข้อมูล | JSON |
การอนุญาต | Bearer (token) |
---|
โทเค็น Bearer จะตรงกับคีย์การตรวจสอบสิทธิ์ Hive ใน App Center > Project Management > Select Game Company Game > Game Details > Basic Information ใน Hive Console.
พารามิเตอร์การร้องขอ¶
ชื่อ | ประเภท | จำเป็น (จำเป็น: M, ไม่จำเป็น: O) | คำอธิบาย |
hiveiap_transaction_id | String | M | hiveiap_transaction_id ของผลการตรวจสอบใบเสร็จ |
result_status | Number | M | สถานะความสำเร็จในการจัดส่งสินค้า 0: การจัดส่งล้มเหลว 1: การจัดส่งสำเร็จ 2: คำขอคืนเงินการยกเลิกการชำระเงิน (เฉพาะ PG) |
result_status_message | String | O | เหตุผลในการล้มเหลวในการจัดส่งหรือคำขอยกเลิกการชำระเงิน |
user_id_type | String | M | Hive ประเภทผู้ใช้ v0: โมดูลบุคคล (uid) v1: การตรวจสอบสิทธิ์ v1 (vid) v4: การตรวจสอบสิทธิ์ v4 (player_id) |
user_id | Number | M | รหัสผู้ใช้ หาก user_id_type เป็น v0 ให้ส่ง uid; หาก v1 ให้ส่ง vid; หาก v4 ให้ส่ง player_id |
asset | Object Array | O | ข้อมูลของรายการที่จัดส่ง ให้ระบุค่าเฉพาะเมื่อการจัดส่งสำเร็จ และตอบกลับด้วยอาร์เรย์ว่าง ([]) เมื่อการจัดส่งล้มเหลว |
asset_id | String | O | รหัสรายการ |
asset_name | String | O | ชื่อรายการ |
⠀⠀quantity | Number | O | จำนวนรายการที่จัดส่ง |
องค์ประกอบการตอบกลับ¶
ชื่อ | ประเภท | จำเป็น (จำเป็น: M, ไม่จำเป็น: O) | คำอธิบาย |
result | หมายเลข | M | รหัสการตอบกลับ (0: สำเร็จ) |
result_msg | สตริง | M | ข้อความผลลัพธ์ตามรหัสการตอบกลับ |
ตัวอย่างคำขอ¶
curl -L -v
-d '{"hiveiap_transaction_id" : "HS_13","result_status": 1,"user_id_type": "vid","user_id": 30000056996,"asset": [ {"asset_id":"item_id","asset_name":"item_name","quantity":1}
,{"asset_id":"item_id","asset_name":"item_name","quantity":1}]}' \
-H "Content-Type: text/html" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNjAyMDU2NzI2LCJqdGkiOiIxODczMTExMzIwIn0.3soFiHTPlObCoqR5xX9ZeOQTSvnHrHDHWmopP3QfWtY" \
https://sandbox-hiveiap.qpyou.cn/api_v4/item_result
ตัวอย่างการตอบกลับ¶
บริการแจ้งผลการชำระเงิน¶
บริการแจ้งผลการชำระเงินจะส่งผลลัพธ์ไปยังเซิร์ฟเวอร์เกมทันทีเมื่อการชำระเงินเสร็จสมบูรณ์หรือถูกยกเลิก API นี้จะส่งค่าของ purchase_bypass_info
ในลักษณะเดียวกับการ สอบถามประวัติการชำระเงินที่เสร็จสมบูรณ์ ซึ่งอนุญาตให้เกมใช้ค่านี้เพื่อยืนยันใบเสร็จและมอบผลิตภัณฑ์ให้กับผู้ใช้ การยืนยันใบเสร็จและการมอบผลิตภัณฑ์ควรทำเฉพาะเมื่อ type
ใน ข้อมูลการส่งผลลัพธ์การชำระเงิน เป็นการชำระเงิน
Note
เพื่อใช้ API นี้ คุณต้องตั้งค่า บริษัท PG ใน Hive console ก่อน แนะนำให้ใช้ API นี้หรือ API การตรวจสอบประวัติการชำระเงินเพื่อการตรวจสอบใบเสร็จและการจัดส่งสินค้า
ข้อมูลพื้นฐานการส่งผลการชำระเงิน¶
HTTP Method | POST |
Content-Type | application/json |
Data Format | JSON |
ข้อมูลการส่งผลลัพธ์การชำระเงิน¶
ชื่อ | ประเภท | จำเป็น (จำเป็น: M, ไม่จำเป็น: O) | คำอธิบาย |
type | String | M | ประเภทการแจ้งเตือน (paid: การชำระเงินเสร็จสมบูรณ์, cancelled: การชำระเงินถูกยกเลิกหรือคืนเงิน) |
market_pid | String | M | รหัสผลิตภัณฑ์ที่ไม่ซ้ำกัน |
order_id | String | M | หมายเลขคำสั่งซื้อ |
server_id | String | M | รหัสที่แยกความแตกต่างของเซิร์ฟเวอร์เกมที่ผู้ใช้ทำการซื้อเข้าถึง |
vid | String | M | รหัสผู้เล่นของผู้ใช้ที่ทำการซื้อ, VID สำหรับการตรวจสอบสิทธิ์ v1 |
vid_type | String | O | ค่าประเภท vid ตามเวอร์ชัน SDK (ค่าเริ่มต้น v4) |
uid | String | O | UID ของผู้ใช้ที่ทำการซื้อ |
amount | String | M | จำนวนเงินที่ชำระ |
currency | String | M | สกุลเงินที่ใช้ในการชำระเงิน |
quantity | Number | M | จำนวนที่ซื้อ |
started_datetime | Datetime | M | เวลาที่เริ่มการชำระเงิน (Y-m-d H:i:s) |
paid_datetime | Datetime | M | เวลาที่การชำระเงินเสร็จสมบูรณ์ (Y-m-d H:i:s) |
cancelled_datetime | Datetime | O | เวลาที่การชำระเงินถูกยกเลิกหรือคืนเงิน (Y-m-d H:i:s) |
started_datetime_ms | Number | M | เวลาที่เริ่มการชำระเงิน (Unix TimeStamp Milliseconds) |
paid_datetime_ms | Number | M | เวลาที่การชำระเงินเสร็จสมบูรณ์ (Unix TimeStamp Milliseconds) |
cancelled_datetime_ms | Number | O | เวลาที่การชำระเงินถูกยกเลิกหรือคืนเงิน (Unix TimeStamp Milliseconds) |
cancelled_reason | String | O | เหตุผลในการยกเลิกหรือคืนเงินการชำระเงิน |
hiveiap_receipt | String | M | HASH ที่เข้ารหัสของข้อมูลการชำระเงิน |
purchase_bypass_info | String | M | ข้อมูลที่จำเป็นสำหรับคำขอการตรวจสอบใบเสร็จ |
iap_payload | String | O | ข้อมูลเพิ่มเติมที่ได้รับจากลูกค้าเพื่อนำส่งไปยังเซิร์ฟเวอร์เกม มันอยู่ในรูปแบบ JSON String และหากไม่มีข้อมูลใด ๆ ที่ได้รับ มันจะส่งคืนค่า null. |
ตัวอย่างการส่งผลการชำระเงิน (เมื่อชำระเงินเสร็จสิ้น)¶
{
"type": "paid",
"market_id": "15",
"order_id": "H2168993822440686730",
"market_pid": "com.com2us.hivesdk.windows.microsoftstore.global.normal.item01",
"vid": "20000011337",
"uid": "67200717",
"vid_type": "v4",
"server_id": "kr",
"appid": "com.com2us.hivesdk.windows.microsoftstore.global.normal",
"amount": "1200",
"started_datetime": "2023-07-21 20:17:06",
"paid_datetime": "2023-07-21 20:18:13",
"cancelled_datetime": null,
"cancelled_reason": null,
"currency": "KRW",
"quantity": 1,
"hiveiap_receipt": "tJpwQSIlNFiCSPokHSRYTvTLmtbDiSZnkYa7+IWaMwM=",
"started_datetime_ms": 1689938226000,
"paid_datetime_ms": 1689938293000,
"cancelled_datetime_ms": null,
"iap_payload": null,
"purchase_bypass_info": "eyJ0eXBlIjoicGFpZCIsIm1hcmtldF9pZCI6IjE1Iiwib3JkZXJfaWQiOi..."
}
ตัวอย่างการส่งผลลัพธ์การชำระเงิน (เมื่อการชำระเงินถูกยกเลิก)¶
{
"type": "cancelled",
"market_id": "15",
"order_id": "H2168993822440686730",
"market_pid": "com.com2us.hivesdk.windows.microsoftstore.global.normal.item01",
"vid": "20000011337",
"uid": "67200717",
"vid_type": "v4",
"server_id": "kr",
"appid": "com.com2us.hivesdk.windows.microsoftstore.global.normal",
"amount": "1200",
"started_datetime": "2023-07-21 20:17:06",
"paid_datetime": "2023-07-21 20:18:13",
"cancelled_datetime": "2023-07-21 20:21:44",
"cancelled_reason": "테스트 결제 취소",
"currency": "KRW",
"quantity": 1,
"hiveiap_receipt": "tJpwQSIlNFiCSPokHSRYTvTLmtbDiSZnkYa7+IWaMwM=",
"started_datetime_ms": 1689938226000,
"paid_datetime_ms": 1689938293000,
"cancelled_datetime_ms": 1689938504000,
"iap_payload": null,
"purchase_bypass_info": "eyJ0eXBlIjoiY2FuY2VsbGVkIiwibWFya2V0X2lkIjoiMT..."
}
การคืนเงินเป้าหมายการชำระเงินคืนของผู้ใช้ API สอบถามประวัติการคืนเงิน¶
API นี้ใช้เพื่อดึงประวัติการคืนเงินสำหรับผู้ใช้ที่ได้ขอคืนเงินและต้องการทำการชำระเงินคืน
หากคุณได้เปิดใช้งานฟีเจอร์การชำระเงินคืนสำหรับผู้ใช้ที่ได้รับเงินคืนในร้านค้าเว็บที่คุณพัฒนาขึ้นเอง คุณจำเป็นต้องพัฒนา UI ป๊อปอัปการแจ้งเตือนการชำระเงินคืนสำหรับผู้ใช้ที่ได้รับเงินคืนโดยใช้ค่าผลลัพธ์จาก API 'การคืนเงินเป้าหมายการชำระเงินคืนของผู้ใช้'
เมื่อใช้ API 'Refund user ee-payment target Refund History Inquiry' โปรดทราบถึงสิ่งต่อไปนี้
- ฟิลด์
is_refund
ในรายการการตอบกลับของ PlayerID Lookup API สามารถใช้ได้เฉพาะเมื่อมันเป็นจริงเท่านั้น - เมื่อขอการชำระเงินสำหรับกรณีการชำระเงินคืน พารามิเตอร์ json ในการขอจะต้องรวม
refund_idx(Integer)
และis_repayment(Integer)
เป็นฟิลด์ที่จำเป็น
URL การร้องขอ¶
สภาพแวดล้อม | URL |
---|---|
URL การผลิต | https://store.withhive.com/external/api/refund_info |
URL แซนด์บ็อกซ์ | https://sandbox-store.withhive.com/external/api/refund_info |
วิธีการ HTTP | POST |
ประเภทเนื้อหา | text/html; charset=utf-8 |
รูปแบบข้อมูล | JSON |
การอนุญาต | Bearer (token) |
โทเค็น Bearer จะตรงกับคีย์การตรวจสอบสิทธิ์ Hive ใน App Center > การจัดการโครงการ > เลือกบริษัทเกม > รายละเอียดเกม > ข้อมูลพื้นฐาน ใน Hive Console.
พารามิเตอร์การร้องขอ¶
ฟิลด์ | ประเภท | จำเป็น | คำอธิบาย |
---|---|---|---|
appid | String | O | Hive Appid |
vid_type | String | O | ประเภทบัญชี (สำหรับเกมใหม่ "v4") |
vid | String | O | ข้อมูลบัญชี Hive (Player ID) |
game_language | String | O | ภาษา (ISO 639-1 สองตัวอักษร) |
device | String | X | ความแตกต่างระหว่าง PC และ Mobile (pc, mobile) * หากไม่มีรายการอุปกรณ์ จะถูกตั้งค่าเป็น mobile ในการตอบกลับ |
องค์ประกอบการตอบกลับ¶
ฟิลด์ | ประเภท | จำเป็น | คำอธิบาย |
---|---|---|---|
result | จำนวนเต็ม | O | รหัสการตอบกลับ (0 หมายถึงสำเร็จ, อื่นใดหมายถึงข้อผิดพลาด) |
result_msg | สตริง | O | ข้อความการตอบกลับ |
guide_title | สตริง | O | ชื่อคู่มือ |
guide_content | สตริง | O | เนื้อหาคู่มือ |
customer_site | วัตถุ | O | ที่อยู่บริการลูกค้า |
customer_site > pc | สตริง | O | ที่อยู่บริการลูกค้าสำหรับ PC |
customer_site > mobile | สตริง | O | ที่อยู่บริการลูกค้าสำหรับมือถือ |
refund_list | อาเรย์ > วัตถุ | O | รายการการคืนเงิน |
refund_list > refund_idx | จำนวนเต็ม | X | รหัส ID การคืนเงิน |
refund_list > market_id | จำนวนเต็ม | X | รหัสตลาด Hive |
refund_list > market_pid | สตริง | X | รหัสผลิตภัณฑ์ PID |
refund_list > refund_time | สตริง | X | วันที่และเวลาการคืนเงิน |
refund_list > refund_time_ms | จำนวนเต็ม | X | วันที่และเวลาการคืนเงิน (Unix Timestamp Milliseconds) |
refund_list > quantity | จำนวนเต็ม | X | จำนวนผลิตภัณฑ์ที่ซื้อ |
ตัวอย่างคำขอ¶
curl -L -v \
-d '{"appid":"com.com2us.hivesdk.normal.freefull.apple.global.ios.universal","vid_type":"v4","vid":"20000015900","game_language":"ko","device":"pc"}' \
-H "Content-Type: text/html" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNjAyMDU2NzI2LCJqdGkiOiIxODczMTExMzIwIn0.3soFiHTPlObCoqR5xX9ZeOQTSvnHrHDHWmopP3QfWtY" \
https://sandbox-store.withhive.com/external/api/refund_info
ตัวอย่างการตอบกลับ¶
{
"result": 0,
"result_msg": "success",
"guide_title": "환불 상품 재결제 안내",
"guide_content": "고객님의 계정은 게임 서비스 약관 및 운영 정책 위반 행위(결제시스템 악용)가 확인되어,
게임 이용이 제한되었습니다.\n\n알 수없는 이유로 결제가 취소되었거나, 혹은 비정상적인 절차로 환불된 상품의 경우, 동일 상품 재결제 후 게임 이용이 가능합니다.\n\n 현재 접속한 단말OS의 마켓 상품만 재결제가 가능하오니, 다른 마켓은 해당 앱으로 접속하여 재결제 부탁드립니다.
스팀 환불 내역에 대한 재결제는 PC에서 진행하세요. 모든 마켓의 취소/환불 상품의 재결제가 완료되어야 게임 이용이 가능합니다.\n\n일부 마켓에서 한 상품을 여러 수량으로 한 번에 구매 후 환불한 경우,
동일한 수량으로 재결제 해야 합니다. 만약 환불한 수량과 재결제한 수량이 일치하지 않으면 해당 재결제 건은 자동 취소됩니다.
취소되는 시점은 마켓에 따라 상이하며 수일이 걸릴 수 있습니다.\n\n 재결제 도중 오류로 인하여 결제 실패한 경우, 현재 계정으로 다시 게임을 재실행해주세요. 디바이스를 변경하여 동일한 마켓계정이면서 다른 게임 계정으로 로그인하시면 결제가 정상적으로 완료되지 않을 수 있습니다.\n\n결제 불가상품을 비롯한 그밖의 문의사항은 고객센터로 접수 부탁드립니다.\n\n* 환불 시간은 UTC+9 기준입니다.",
"customer_site": {
"pc": "https://sandbox-customer.withhive.com/com2us/faq/game/539",
"mobile": "https://sandbox-customer-m.withhive.com/com2us/faq/game/539"
},
"refund_list": [
{
"refund_idx": 20850,
"market_id": 1,
"market_pid": "com.com2us.hivesdk.normal.freefull.apple.global.ios.universal.cs01",
"refund_time": "2023.02.02 15:47 (UTC+9)",
"refund_time_ms": 1675320475000,
"quantity": 1
}
]
}
ตัวอย่างของป๊อปอัปคู่มือการชำระเงินคืนสำหรับผู้ขอคืนเงิน¶
Warning
ผู้ใช้ต้องสร้างปุ่ม 'รีเฟรช' ที่อนุญาตให้พวกเขาอัปเดตรายการผลิตภัณฑ์สำหรับการชำระเงินใหม่หลังจากเสร็จสิ้นการชำระเงินสำหรับกรณีการชำระเงินใหม่。
หลังจากที่ทำการชำระเงินสำหรับกรณีการชำระเงินคืนเสร็จสิ้นแล้ว จะต้องเรียกใช้ API 'การสอบถามประวัติการคืนเงินเป้าหมายการชำระเงินคืนของผู้ใช้' เพื่อดำเนินการกับกระบวนการปล่อยการตรวจสอบสิทธิ์