การชำระเงิน Web PG

API การชำระเงิน PG บนเว็บเป็น API ที่ใช้เมื่อคุณต้องการนำการชำระเงิน PG ไปใช้ในเว็บไซต์ แม้ว่าจะไม่ใช้ Hive SDK billing เมื่อพัฒนาแอป Windows API การชำระเงิน PG บนเว็บจะแตกต่างจาก API ที่นำการชำระเงิน PG ไปใช้ในแอป

การดึงรายการสินค้า¶

กำลังดึงข้อมูลผลิตภัณฑ์ ใช้ในการแสดงรายการผลิตภัณฑ์ในแอป

URL ที่ร้องขอ¶

โทเค็น Bearer จะตรงกับ Hive คีย์การตรวจสอบสิทธิ์ที่พบใน App Center > Project Management > Select Game Company > Game Details > Basic Information ของคอนโซล Hive

พารามิเตอร์การร้องขอ¶

องค์ประกอบการตอบกลับ¶

ตัวอย่างคำขอ¶

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 ของผลิตภัณฑ์ที่เลือกจากรายการผลิตภัณฑ์

การชำระเงินแบบกำหนดจำนวนเงิน¶

การชำระเงินแบบกำหนดจำนวนเงินเป็นฟีเจอร์ที่ช่วยให้คุณสามารถขอชำระเงินด้วยจำนวนเงินที่ระบุโดยเซิร์ฟเวอร์เกม (custom_price) แทนที่จะเป็นจำนวนเงินที่ตั้งค่าไว้ใน PID ของผลิตภัณฑ์

หากคุณต้องการใช้คูปอง คะแนน ส่วนลดกิจกรรม ฯลฯ กับผลิตภัณฑ์ในเกมของคุณ เซิร์ฟเวอร์เกมจะต้องคำนวณจำนวนเงินชำระเงินสุดท้ายหลังจากใช้ส่วนลดทั้งหมดแล้ว และเรียก API ด้วยจำนวนเงินนั้นเป็นค่า custom_price หากไม่ได้ระบุค่า custom_price การชำระเงินจะดำเนินการด้วยจำนวนเงินที่ตั้งค่าไว้ใน PID ของผลิตภัณฑ์

URL การร้องขอ¶

โทเค็น Bearer จะตรงกับ Hive คีย์การตรวจสอบสิทธิ์ที่พบใน App Center > Project Management > Select Game Company > Game Details > Basic Information ในคอนโซล Hive

พารามิเตอร์การร้องขอ¶

ในการทำให้ปุ่ม 'ปิดหน้าต่างป๊อปอัปการชำระเงิน PG เสร็จสมบูรณ์' ทำงานได้ คุณต้องเพิ่มสคริปต์ต่อไปนี้ไปยังหน้าที่เรียกการชำระเงิน PG

window.addEventListener('message', function(event) {
    const data = event.data;

    if (data?.type === 'REFRESH_PARENT') {
        if (typeof data.url === 'string' && data.url.trim() !== '') {
            window.location.href = data.url;
        } else {
            window.location.reload();
        }
    }
});

ตัวอย่างคำขอ¶

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) จะส่งผลการชำระเงินไปยังเซิร์ฟเวอร์ IAP v4 ของ Hive โดยตรง วิธีนี้ช่วยชดเชยความไม่เสถียรของเครือข่ายและป้องกันการดัดแปลงข้อมูลการชำระเงิน ในระหว่าง การเตรียมงาน จะมีการตรวจสอบข้ามโดยการเปรียบเทียบข้อมูลการชำระเงินที่ลงทะเบียนกับข้อมูลจากหน่วยงานการชำระเงิน (PG) เมื่อยืนยันความสมบูรณ์ของข้อมูลการชำระเงินแล้ว จะมีการรักษามาตรการความปลอดภัยเพิ่มเติม และข้อมูลการชำระเงินจะถูกเก็บรักษา ข้อมูลการชำระเงินที่เก็บรักษาสามารถสอบถามได้ผ่าน API การสอบถามประวัติการชำระเงินที่เสร็จสมบูรณ์

ลูกค้าขอข้อมูลจากเซิร์ฟเวอร์เกมในขณะที่ต้องการข้อมูลการชำระเงินของผู้ใช้ และเซิร์ฟเวอร์เกมจะดึงข้อมูลการชำระเงินผ่านเซิร์ฟเวอร์ Hive IAP v4 หากมีประวัติการชำระเงินสำหรับผู้ใช้ การตรวจสอบข้อมูลการชำระเงินจะดำเนินการโดยใช้ purchase_bypass_info。

URL การร้องขอ¶

URL การผลิต	https://hiveiap.qpyou.cn/api_v4/purchases/unconsumed
URL Sandbox	https://sandbox-hiveiap.qpyou.cn/api_v4/purchases/unconsumed
HTTP Method	POST
Content-Type	application/json
รูปแบบข้อมูล	JSON
การอนุญาต	Bearer (token)

โทเค็น Bearer จะตรงกับ Hive รหัสผ่านการตรวจสอบสิทธิ์ที่พบใน App Center > Project Management > Select Game Company Game > Game Details > Basic Information บนคอนโซล Hive

พารามิเตอร์การร้องขอ¶

ชื่อ	ประเภท	จำเป็น (จำเป็น: M, ไม่จำเป็น: O)	คำอธิบาย
appid	String	M	ID ที่ลงทะเบียนและออกจาก Hive คอนโซล > App Center
market_id	Number	M	หมายเลขตลาดที่ไม่ซ้ำกัน (ใช้ค่าคงที่ `15`)
server_id	String	M	รหัสเพื่อแยกแยะเซิร์ฟเวอร์เกมที่การชำระเงินเกิดขึ้น
user_id_type	String	M	ประเภทผู้ใช้ Hive (ใช้ค่าคงที่ `player_id`)
user_id	Number	M	รหัสผู้ใช้ Hive (`player_id`)

องค์ประกอบการตอบกลับ¶

ชื่อ	ประเภท	จำเป็น (จำเป็น: M, ไม่จำเป็น: O)	คำอธิบาย
result	หมายเลข	M	รหัสการตอบกลับ (0: สำเร็จ)
result_msg	สตริง	M	ข้อความผลลัพธ์ตามรหัสการตอบกลับ
unconsumed_lists	อาร์เรย์วัตถุ	M
┕ market_pid	สตริง	M	รหัสประจำตัวผลิตภัณฑ์ที่ไม่ซ้ำกัน
┕ order_id	สตริง	M	หมายเลขคำสั่งซื้อ
┕ server_id	สตริง	M	รหัสที่แยกความแตกต่างของเซิร์ฟเวอร์เกมที่ผู้ใช้ซื้อเข้าถึง
┕ vid	สตริง	M	PlayerID ของผู้ใช้ที่ทำการซื้อ
┕ 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) (คืนค่า null หากไม่มีข้อมูลที่ได้รับ)
┕ price_type	สตริง	O	ประเภทราคา (none: ไม่ได้ใช้, custom_price: การชำระเงินจำนวนที่กำหนดเอง)
┕ gameserver_price_verify_key	สตริง	O	คีย์การตรวจสอบจำนวนเงินการชำระเงินของเซิร์ฟเวอร์เกม

ตัวอย่างคำขอ¶

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,
            "price_type": "none",
            "gameserver_price_verify_key": null
        }
    ]
}

การตรวจสอบข้อมูลการชำระเงิน¶

API การตรวจสอบผลการชำระเงินอิงจาก การตรวจสอบใบเสร็จ IAP v4.

การตรวจสอบผลการชำระเงินใช้ purchase_bypass_info ที่ได้รับมาก่อนหน้านี้ purchase_bypass_info ประกอบด้วยข้อมูลต่าง ๆ ที่ได้รับผ่าน SDK ก่อนที่จะดำเนินการชำระเงินและถูกส่งไปยัง Hive Analytics หากคุณต้องการส่ง บันทึกการขาย พร้อมกับคำขอการตรวจสอบใบเสร็จ โปรดใช้ game_info ข้อมูล game_info ที่ได้รับทำหน้าที่เป็นตัวกลางในการส่งบันทึกไปยังเซิร์ฟเวอร์วิเคราะห์จาก Hive IAP.

URL การร้องขอ¶

Production URL	https://hiveiap-verify.qpyou.cn/api_v4/verify
Sandbox URL	https://sandbox-hiveiap-verify.qpyou.cn/api_v4/verify
HTTP Method	POST
Content-Type	text/html
Data Format	JSON
Authorization	Bearer (token)

โทเค็น Bearer จะตรงกับ Hive คีย์การรับรองความถูกต้องที่พบใน App Center > Project Management > Select Game Company > Game Details > Basic Information ในคอนโซล Hive

พารามิเตอร์คำขอ¶

ชื่อ	ประเภท	จำเป็น (จำเป็น: M, ไม่จำเป็น: O)	คำอธิบาย
purchase_bypass_info	String	M	ข้อมูลสำหรับการแทนที่ใบเสร็จและการส่งข้อมูลวิเคราะห์
game_info	Object Array	O	เมื่อมีบันทึกที่จะส่งไปยังเกม เช่น บันทึกเกมหรือบันทึกรายได้ ให้เพิ่มค่าตัวนี้ไปยังเกมเพื่อส่งไป และ Hive IAP จะทำหน้าที่แทนเซิร์ฟเวอร์วิเคราะห์สำหรับการส่ง ในขั้นตอนการตรวจสอบใบเสร็จ จะไม่สามารถทราบได้ว่ารายการได้ถูกส่งแล้ว (itemsendok) ดังนั้นส่วนนี้ต้องดำเนินการแยกต่างหากและจัดเตรียมเป็นข้อมูลเพิ่มเติม
⠀⠀server_uid	bigint	O	รหัสผู้ใช้ที่ออกโดยเซิร์ฟเวอร์เกม หากไม่มี ให้ใช้ 0
⠀⠀giftee_uid	bigint	O	null: การชำระเงินเพื่อการใช้งานส่วนตัว 0: ผู้ที่ได้รับของขวัญมีอยู่ แต่ไม่สามารถตรวจสอบ UID ได้
⠀⠀level	int	O	ระดับในเกมของผู้ใช้ ไม่จำเป็นหากไม่มีระดับ หากไม่มี ให้ใช้ 0
⠀⠀character_id	bigint	O	ค่ารหัสตัวละครที่ไม่ซ้ำกันภายในเซิร์ฟเวอร์ หากไม่มีแนวคิดของตัวละคร ให้ใช้ "0"
⠀⠀character_type_id	int	O	ค่ารหัสประเภทตัวละคร ให้ป้อน "0" สำหรับเกมที่ไม่มีแนวคิดของตัวละคร
⠀⠀character_level	int	O	ค่ารหัสประเภทตัวละคร ให้ป้อน "0" สำหรับเกมที่ไม่มีแนวคิดของตัวละคร
⠀⠀is_emulator	int	O	ให้ป้อน "1" เมื่อเข้าถึงผ่านโปรแกรมจำลอง PC เช่น BlueStacks มิฉะนั้นให้ป้อน "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: การชำระเงินปกติ)
hiveiap_iap_payload	ข้อความ	O	ข้อมูลเพิ่มเติมที่ได้รับจากลูกค้าเพื่อนำส่งไปยังเซิร์ฟเวอร์เกม อยู่ในรูปแบบ JSON String และหากไม่มีข้อมูลได้รับ จะส่งคืน `null`
hiveiap_account_uuid_compare	หมายเลข	O	บ่งชี้ว่าข้อมูลบัญชีที่ให้ไว้กับ API การตรวจสอบใบเสร็จตรงกับข้อมูลบัญชี Hive ที่เข้าสู่ระบบในขณะตรวจสอบหรือไม่ อาจมีบัญชี Hive หลายบัญชีที่มีบัญชีตลาดเดียวกัน (1: ตรงกัน, 2: ไม่ตรงกัน, 9: ไม่รองรับ)
hiveiap_price	ข้อความ	O	จำนวนเงินการชำระเงิน เมื่อใช้การชำระเงินแบบกำหนดจำนวนเงิน PG เพื่อป้องกันการละเมิด คุณ**ต้อง**ตรวจสอบว่าจำนวนเงินการชำระเงินแบบกำหนดเองและจำนวนเงินในคำสั่งซื้อจริงเหมือนกันบนเซิร์ฟเวอร์เกมโดยใช้คีย์การตรวจสอบ (`gameserver_price_verify_key`)
hiveiap_currency	ข้อความ	O	สกุลเงินการชำระเงิน เมื่อใช้การชำระเงินแบบกำหนดจำนวนเงิน PG เพื่อป้องกันการละเมิด คุณ**ต้อง**ตรวจสอบว่าสกุลเงินการชำระเงินของจำนวนเงินการชำระเงินแบบกำหนดเองและสกุลเงินการชำระเงินของจำนวนเงินในคำสั่งซื้อจริงเหมือนกันบนเซิร์ฟเวอร์เกมโดยใช้คีย์การตรวจสอบ (`gameserver_price_verify_key`)
gameserver_price_verify_key	ข้อความ	O	คีย์การตรวจสอบจำนวนเงินการชำระเงินของเซิร์ฟเวอร์เกม เมื่อใช้การชำระเงินแบบกำหนดจำนวนเงิน PG เพื่อป้องกันการละเมิด คุณต้องใช้คีย์นี้เพื่อเปรียบเทียบและตรวจสอบข้อมูลจำนวนเงินและสกุลเงินบนเซิร์ฟเวอร์เกม

รหัสการตอบกลับ¶

รหัส	ข้อความ	ความคิดเห็น
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",
    "hiveiap_iap_payload": null,
    "hiveiap_account_uuid_compare": 9,
    "hiveiap_price": "1200",
    "hiveiap_currency": "KRW",
    "gameserver_price_verify_key": null
}

การประมวลผลผลลัพธ์การชำระเงิน¶

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

พารามิเตอร์คำขอ¶

ชื่อ	ประเภท	จำเป็น (จำเป็น: 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 ประเภทผู้ใช้ (ใช้ค่าคงที่ `player_id`)
user_id	Number	M	Hive รหัสผู้ใช้ (`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": "player_id","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

ตัวอย่างการตอบกลับ¶

{
    "result": 0,
    "result_msg": "success"
}

บริการแจ้งผลการชำระเงิน¶

บริการแจ้งผลการชำระเงินจะส่งผลลัพธ์ไปยังเซิร์ฟเวอร์เกมทันทีเมื่อการชำระเงินเสร็จสิ้นหรือถูกยกเลิก API นี้จะส่งค่าของ purchase_bypass_info ในลักษณะเดียวกับ การตรวจสอบประวัติการชำระเงินที่เสร็จสมบูรณ์ ซึ่งอนุญาตให้เกมใช้ค่านี้เพื่อตรวจสอบใบเสร็จและมอบไอเท็มให้กับผู้ใช้ การตรวจสอบใบเสร็จและการมอบไอเท็มควรดำเนินการต่อเมื่อ type ใน ข้อมูลการส่งผลลัพธ์การชำระเงิน เป็น paid.

ข้อมูลพื้นฐานเกี่ยวกับการส่งผลลัพธ์การชำระเงิน¶

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	PlayerID ของผู้ใช้ที่ทำการซื้อ
vid_type	String	O	เวอร์ชัน SDK (ค่าเริ่มต้น v4)
uid	String	O	Hive UID สมาชิกของผู้ใช้ที่ทำการซื้อ
amount	String	M	จำนวนเงินที่ชำระ
currency	String	M	สกุลเงินที่ใช้ในการชำระเงิน
quantity	String	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.
price_type	String	O	ประเภทราคา (none: ไม่ได้ใช้, custom_price: การชำระเงินจำนวนที่กำหนดเอง)
gameserver_price_verify_key	String	O	คีย์การตรวจสอบจำนวนเงินการชำระเงินของเซิร์ฟเวอร์เกม

ตัวอย่างการส่งผลการชำระเงิน (เมื่อชำระเงินเสร็จสิ้น)¶

{
    "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...",
    "price_type": "none",
    "gameserver_price_verify_key": null
}

ตัวอย่างการส่งผลการชำระเงิน (ในกรณีที่การชำระเงินถูกยกเลิก)¶

{
    "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...",
    "price_type": "none",
    "gameserver_price_verify_key": null
}

API สอบถามประวัติการคืนเงินเป้าหมายการชำระเงินคืนของผู้ใช้¶

API นี้ใช้ในการดึงประวัติการคืนเงินสำหรับผู้ใช้ที่ได้ขอคืนเงินและต้องการทำการชำระเงินใหม่
หากคุณได้เปิดใช้งานฟีเจอร์การชำระเงินใหม่สำหรับผู้ใช้ที่คืนเงินในร้านค้าเว็บที่คุณพัฒนาขึ้นเอง คุณควร implement UI ป๊อปอัพการแจ้งเตือนการชำระเงินใหม่สำหรับผู้ใช้ที่คืนเงินโดยใช้ค่าตอบกลับจาก API 'การสอบถามประวัติการคืนเงินเป้าหมายสำหรับการชำระเงินใหม่ของผู้ใช้ที่คืนเงิน'

เมื่อใช้ API 'การสอบถามประวัติการคืนเงินเป้าหมายการชำระเงินคืนของผู้ใช้' โปรดทราบถึงเรื่องต่อไปนี้

• รายการตอบกลับ is_refund จาก PlayerID Lookup API สามารถใช้ได้เฉพาะเมื่อมันเป็นจริงเท่านั้น
• เมื่อขอการชำระเงินสำหรับกรณีการชำระเงินคืน พารามิเตอร์คำขอ json จะต้องรวม refund_idx(Integer) และ is_repayment(Integer) เป็นรายการที่จำเป็น
• หากเป็นกรณีการชำระเงินด้วยจำนวนเงินที่กำหนดเอง เมื่อทำการขอชำระเงิน จะต้องตั้งค่า price_type (ประเภทราคา) เป็น custom (ราคาที่กำหนดเอง)
• เมื่อทำการขอการชำระเงินคืน ฟิลด์ server_id และ gameserver_price_verify_key (จำเป็นเฉพาะสำหรับการชำระเงินด้วยจำนวนเงินที่กำหนดเอง) จะต้องตั้งค่าเป็น 'refund'

URL ที่ร้องขอ¶

โทเค็น Bearer จะตรงกับ Hive คีย์การตรวจสอบสิทธิ์ที่พบใน App Center > Project Management > Select Game Company > Game Details > Basic Information ของคอนโซล Hive

พารามิเตอร์คำขอ¶

องค์ประกอบการตอบกลับ¶

ตัวอย่างคำขอ¶

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,
      "price": "1200",
      "currency": "KRW",
      "display_price": "₩1,200"
    }
  ]
}

ตัวอย่างป๊อปอัพการแจ้งเตือนการคืนเงินการชำระเงินของผู้ใช้¶