ข้ามไปที่เนื้อหา

การชำระเงิน 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 (รหัสผลิตภัณฑ์) ที่เลือกจากรายการผลิตภัณฑ์

URL การร้องขอ

สภาพแวดล้อม URL
URL ผลิตภัณฑ์ https://store.withhive.com/external/api/order
URL แซนด์บ็อกซ์ https://sandbox-store.withhive.com/external/api/order
HTTP เมธอด POST
Content-Type text/html; charset=utf-8
รูปแบบข้อมูล JSON
การรับรองความถูกต้อง Bearer (token)

โทเค็น Bearer จะตรงกับ Hive คีย์การตรวจสอบสิทธิ์ใน App Center > การจัดการโครงการ > เลือกบริษัทเกม > รายละเอียดเกม > ข้อมูลพื้นฐาน ใน Hive คอนโซล.

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

ฟิลด์ ประเภท จำเป็น คำอธิบาย
market_id สตริง O Hive รหัสตลาด
appid สตริง O Hive Appid
hive_country สตริง O รหัสประเทศ (ISO 3166-1 สองตัว)
game_language สตริง O ภาษา (ISO 639-1 สองตัว)
vid สตริง O Hive ข้อมูลบัญชี (รหัสผู้เล่น)
vid_type สตริง O ประเภทบัญชี (สำหรับเกมใหม่, v4)
market_pid สตริง O ผลิตภัณฑ์ PID
server_id สตริง O รหัสเซิร์ฟเวอร์
os สตริง O Windows: W, MAC: M, Android: A
quantity จำนวนเต็ม X จำนวนที่ซื้อ (หากไม่ส่งจะใช้ค่าเริ่มต้น 1)
iap_payload สตริง X ข้อมูลเมตาการซื้อที่กำหนดโดยนักพัฒนาแอป ที่นี่

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

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 > Project Management > Select Game Company Game > Game Details > Basic Information ใน Hive Console.

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

    ชื่อ ประเภท จำเป็น (จำเป็น: M, ไม่จำเป็น: O) คำอธิบาย
    appid String M ID ที่ลงทะเบียนและออกจาก Hive console > App Center
    market_id Number M หมายเลขตลาดที่ไม่ซ้ำกัน (ใช้ค่าคงที่ `15`)
    server_id String M รหัสการระบุเซิร์ฟเวอร์เกมที่การชำระเงินเกิดขึ้น
    user_id_type String M ประเภทผู้ใช้ HIVE player_id : การตรวจสอบสิทธิ์ v4 (v4)
    user_id Number M รหัสผู้ใช้ HIVE ที่ส่งตามประเภท user_id 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 ของผู้ใช้
    ┕ 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) (จะส่งคืน 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 Method POST
    Content-Type 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 ประเภทผู้ใช้ v4: การตรวจสอบสิทธิ์ v4 (player_id)
    user_id Number M รหัสผู้ใช้ หาก user_id_type เป็น 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

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

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

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

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

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_type String O ค่า vid type ตามเวอร์ชัน 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 'คืนเงินผู้ใช้ ee-payment เป้าหมายการสอบถามประวัติการคืนเงิน' โปรดทราบถึงสิ่งต่อไปนี้

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

  • ฟิลด์ is_refund ในรายการการตอบกลับของ PlayerID Lookup API สามารถใช้ได้เฉพาะเมื่อมันเป็นจริงเท่านั้น

  • เมื่อขอการชำระเงินสำหรับกรณีการชำระเงินคืน พารามิเตอร์ json ในการขอจะต้องรวม refund_idx(Integer) และ is_repayment(Integer) เป็นฟิลด์ที่จำเป็น

URL การร้องขอ

สภาพแวดล้อม URL
Production URL https://store.withhive.com/external/api/refund_info
Sandbox URL https://sandbox-store.withhive.com/external/api/refund_info
HTTP Method POST
Content-Type text/html; charset=utf-8
Data Format JSON
Authorization Bearer (token)

โทเค็น Bearer ตรงกับคีย์การตรวจสอบสิทธิ์ Hive ใน App Center > Project Management > เลือกบริษัทเกม > รายละเอียดเกม > ข้อมูลพื้นฐาน ใน 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 ที่อยู่บริการลูกค้า Mobile
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 'การสอบถามประวัติการคืนเงินเป้าหมายของผู้ใช้คืนเงิน' เพื่อดำเนินการกับกระบวนการปล่อยการตรวจสอบสิทธิ