簡易 PG 支付¶
'簡易 PG 支付'是在 App 伺服器查詢 PG 支付方式、直接在商店網頁中建構支付方式選擇 UI,並以使用者選擇的方式呼叫 PG 公司的支付 WebView 視窗時使用。
本頁說明依序呼叫 payment/methods 和 payment/requests 的方法。
建議的實作順序如下。
- 先查詢支付方式,並在商店網頁中建構支付方式選擇畫面。
- 接著當使用者按下 支付 時,開啟所選 PG 公司的支付 WebView 視窗。
1. 概要¶
串接流程¶
簡易 PG 支付會在商店網頁中處理支付方式選擇步驟。只有在使用者選擇支付方式之後,才會開啟 PG 公司的支付 WebView 視窗。
建議按照以下順序進行串接。
- 使用者在商店網頁中按下 購買 按鈕。
- App 伺服器呼叫支付方式查詢 API。
- 商店網頁根據回應值建構並顯示支付方式選擇 UI。
- 使用者在支付方式選擇 UI 中選擇支付方式並按下 支付。
- App 伺服器呼叫支付請求 API。
- 商店網頁根據回應結果開啟所選 PG 公司的支付 WebView 視窗。
- 使用者在 PG 公司的支付 WebView 視窗中完成支付。
事前準備¶
在串接簡易 PG 支付之前,請先準備以下值。
| 項目 | 說明 |
|---|---|
| Hive 驗證金鑰 | 放入 Authorization 標頭的 Bearer 權杖。使用 Hive Console > App Center > 專案管理 > 遊戲列表 - 選擇遊戲公司遊戲 > 遊戲詳細資訊 > 基本資訊 中的值。 |
app_id | 要進行支付之 App 的 App ID。使用 Hive Console > App Center > 專案管理 > 遊戲列表 - 選擇遊戲公司遊戲 > 遊戲詳細資訊 > 基本資訊 中的值。 |
server_id | 要進行支付之 App 伺服器的識別值。使用 Hive Console > App Center > 專案管理 > 遊戲列表 - 選擇遊戲公司遊戲 > 遊戲詳細資訊 > App 伺服器 中的值。 |
market_pid | 要支付的商品 ID。使用在 Hive Console > Billing > 商品管理 > 商品註冊 中登錄的值。此值需以各商店主控台在商品註冊前準備好的 Product ID 為基準進行設定。 |
player_id | 執行支付的目前使用者 Player ID。使用 App 伺服器從登入工作階段或遊戲使用者資訊中確認的值。 |
market_id | 簡易 PG 支付使用的市場唯一 ID。固定使用 15。 |
2. 查詢支付方式¶
支付方式查詢 API 是用來查詢特定商品目前可用 PG 支付方式清單的 API。請先呼叫此 API,再於商店網頁中建構支付方式選擇畫面。僅呼叫此 API 不會開始支付。
請求資訊¶
端點¶
呼叫端點如下。
| 項目 | 說明 |
|---|---|
| 正式環境 URL | https://hiveiap.qpyou.cn/payment/methods |
| Sandbox URL | https://sandbox-hiveiap.qpyou.cn/payment/methods |
| HTTP Method | POST |
| Data Format | JSON |
HTTP 標頭¶
HTTP 標頭如下。
| 項目 | 說明 |
|---|---|
| Content-Type | application/json;charset=utf-8 |
| Authorization | Bearer |
放入 Authorization 標頭的 Bearer 權杖,是 Hive Console > App Center > 專案管理 > 遊戲列表 - 選擇遊戲公司遊戲 > 遊戲詳細資訊 > 基本資訊 中的 Hive 驗證金鑰。
請求本文¶
下表中,必填標示為 M,選填標示為 O。
| 名稱 | 類型 | 是否必填 | 說明 |
|---|---|---|---|
| language | String | M | 用於顯示支付方式的遊戲語言值。將 App 用戶端目前使用中的語言以 ISO 639-1 Alpha-2 格式傳遞。 |
| country | String | M | 查詢支付方式的目標國家代碼。將要進行支付的使用者所屬國家以 ISO 3166-1 2 碼代碼傳遞。 |
| app_id | String | M | 要進行支付之 App 的 App ID。傳遞在事前準備中確認的值。 |
| market_pid | String | M | 要支付的商品 ID。傳遞在事前準備中確認的值。 |
| market_id | Integer | O | 市場唯一 ID。固定使用 15。 |
| fixed_currency | String | O | 若只想顯示特定幣別,請輸入 ISO 4217 貨幣代碼。若不固定幣別,請在下一步使用回應中的 data.currency 值。 |
回應資訊¶
下表中,必填標示為 M,選填標示為 O。
| 名稱 | 類型 | 是否必填 | 說明 |
|---|---|---|---|
| result | String | M | API 結果字串。若回應成功,請在下一步使用 data 中的支付方式資訊。 |
| code | Integer | M | API 結果代碼。用於區分成功與否及失敗原因。 |
| message | String | M | API 結果訊息。失敗時可用來確認原因。 |
| data | Object | M | 查詢成功時傳遞的支付方式資訊集合。 |
| data.agency_company_code | Integer | M | PG 支付代行公司代碼。使用者選擇支付方式後,將此值傳遞至支付請求 API 的 agency_company_code。 |
| data.country | String | M | 套用於查詢結果的國家代碼。支付請求 API 也要使用相同的國家代碼。 |
| data.currency | String | M | 套用於查詢結果的支付幣別。將此值傳遞至支付請求 API 的 currency。 |
| data.email_agree_text | Array | O | 選擇需要輸入電子郵件的支付方式時,要向使用者顯示的同意文案清單。 |
| data.email_agree_text[].agree_id | Integer | O | 同意文案 ID。用於區分同意項目。 |
| data.email_agree_text[].title | String | O | 顯示給使用者的同意標題。 |
| data.email_agree_text[].description | String | O | 顯示給使用者的同意詳細文案。 |
| data.available_payment_methods | Array | M | 目前商品可使用的支付方式清單。支付畫面只顯示此清單,並在下一步使用使用者所選項目的子欄位。 |
| data.available_payment_methods[].agency | String | M | 所選支付方式的 PG 公司代碼。將此值傳遞至支付請求 API 的 agency。 |
| data.available_payment_methods[].agency_id | Integer | M | PG 公司識別值。用於區分支付方式或確認內部日誌。 |
| data.available_payment_methods[].method | String | M | 所選支付方式代碼。將此值傳遞至支付請求 API 的 method。 |
| data.available_payment_methods[].method_id | Integer | M | 支付方式識別值。用於區分支付方式。 |
| data.available_payment_methods[].requires_email | Boolean | M | 若為 true,則在呼叫支付請求之前,必須先取得使用者電子郵件並傳遞至 email 欄位。 |
| data.available_payment_methods[].priority | Integer | M | 支付方式顯示優先順序值。用於排序支付畫面。 |
| data.available_payment_methods[].display_name | String | M | 在支付畫面中向使用者顯示的支付方式名稱。 |
| data.available_payment_methods[].icon_url | String | O | 在支付畫面中一併顯示的支付方式圖示 URL。 |
回應值使用¶
請按以下方式使用回應值。
- 使用
data.available_payment_methods的display_name、icon_url、priority值,在商店網頁中建構支付方式選擇 UI。 - 顯示
requires_email為true的支付方式時,請一併顯示email_agree_text文案並要求使用者輸入電子郵件。 - 當使用者選擇支付方式時,請將
data.agency_company_code、data.currency、data.available_payment_methods[].agency、data.available_payment_methods[].method、data.available_payment_methods[].requires_email值原樣傳遞為下一步的輸入值。
請求範例¶
curl -L -v \
-d '{
"language": "ko",
"country": "KR",
"app_id": "com.com2us.hivesdk.normal.freefull.google.global.android.common",
"market_pid": "com.com2us.hivesdk.normal.freefull.google.global.android.common.item01",
"market_id": 15,
"fixed_currency": "KRW"
}' \
-H "Content-Type: application/json;charset=utf-8" \
-H "Authorization: Bearer {Bearer 토큰}" \
https://sandbox-hiveiap.qpyou.cn/payment/methods
回應範例¶
{
"result": "success",
"code": 0,
"message": "success",
"data": {
"agency_company_code": 1,
"country": "KR",
"currency": "KRW",
"email_agree_text": [
{
"agree_id": 1,
"title": "(필수) 개인정보 수집∙이용 동의",
"description": "Com2uS은(는) “결제 대행 업체 전송”을 위해 이메일주소를 수집합니다.<br>
내용을 자세히 읽으신 후 동의 여부를 결정해 주시기 바랍니다.<br><br>
- 수집∙이용 목적 : <span class=\"point_color\">결제 대행 업체 전송</span><br>
- 수집 항목 : 이메일주소<br>
- 보유∙이용 기간 : <span class=\"point_color\">결제 대행 업체 전송 목적으로만 수집하며 별도로 저장·보유하지 않습니다.</span><br><br>
※ 개인정보 수집∙이용에 대한 동의를 거부할 권리가 있습니다.<br>
단, 동의를 거부할 경우 해당 결제 대행 업체를 통한 결제가 제한됩니다."
},
{
"agree_id": 2,
"title": "(필수) 개인정보 제3자 제공 동의",
"description": "Com2uS은(는) 다음과 같이 이메일주소를 제3자에게 제공하고 있습니다.<br>
내용을 자세히 읽으신 후 동의 여부를 결정해 주시기 바랍니다.<br><br>
- 제공받는 자 : <strong>결제 대행 업체 (PayPal, Terminal3)</strong><br>
- 이용 목적 : <span class=\"point_color\">부정/의심 거래 방지 및 고객 지원</span><br>
- 제공 항목 : 이메일주소<br>
- 보유∙이용 기간 : <span class=\"point_color\">가맹점과의 계약 종료 후 최대 5년</span><br><br>
※ 개인정보 제3자 제공에 대한 동의를 거부할 권리가 있습니다.<br>
단, 동의를 거부할 경우 해당 결제 대행 업체를 통한 결제가 제한됩니다."
}
],
"available_payment_methods": [
{
"agency": "html5_inicis",
"agency_id": 9,
"method": "card",
"method_id": 1,
"requires_email": false,
"priority": 1,
"display_name": "Credit Card",
"icon_url": "https://hive-fn.qpyou.cn/hiveiap/hivestore/test/img/pg_icon/credit_card.png?ver=2.4.32"
},
{
"agency": "html5_inicis",
"agency_id": 9,
"method": "naverpay",
"method_id": 17,
"requires_email": true,
"priority": 10,
"display_name": "NAVER Pay",
"icon_url": "https://hive-fn.qpyou.cn/hiveiap/hivestore/test/img/pg_icon/5169459511710849342.png?ver=2.4.32"
}
]
}
}
3. 呼叫支付¶
支付請求 API 是在商店網頁中,使用使用者已選擇的支付方式來開啟對應 PG 公司支付 WebView 視窗的 API。必須重複使用從支付方式查詢 API 取得的值。
需要注意以下事項。
- 此 API 不會再次顯示支付方式選擇畫面。
- 此 API 本身不會確認支付完成。
請求資訊¶
端點¶
呼叫端點如下。
| 項目 | 說明 |
|---|---|
| 正式環境 URL | https://hiveiap.qpyou.cn/payment/requests |
| Sandbox URL | https://sandbox-hiveiap.qpyou.cn/payment/requests |
| HTTP Method | POST |
| Data Format | JSON |
HTTP 標頭¶
HTTP 標頭如下。
| 項目 | 說明 |
|---|---|
| Content-Type | application/json;charset=utf-8 |
| Authorization | Bearer |
放入 Authorization 標頭的 Bearer 權杖,是 Hive Console > App Center > 專案管理 > 遊戲列表 - 選擇遊戲公司遊戲 > 遊戲詳細資訊 > 基本資訊 中的 Hive 驗證金鑰。
請求本文¶
下表中,必填標示為 M,選填標示為 O。
| 名稱 | 類型 | 是否必填 | 說明 |
|---|---|---|---|
| language | String | M | 原樣傳遞支付方式查詢 API 使用的遊戲語言值。 |
| country | String | M | 原樣傳遞支付方式查詢 API 使用的國家代碼。 |
| currency | String | M | 傳遞支付方式查詢 API 回應中的 data.currency 值。 |
| app_id | String | M | 傳遞與支付方式查詢 API 所使用 App ID 相同的值。 |
| server_id | String | M | 傳遞在事前準備中確認的伺服器 ID。 |
| market_id | Integer | M | 市場唯一 ID。與支付方式查詢 API 相同,固定使用 15。 |
| market_pid | String | M | 傳遞與支付方式查詢 API 所使用商品 ID 相同的值。 |
| quantity | Integer | M | 本次支付請求要購買的數量。傳遞使用者在遊戲中選擇的數量。 |
| agency_company_code | Integer | M | 傳遞支付方式查詢 API 回應中的 data.agency_company_code 值。 |
| method | String | M | 傳遞使用者所選支付方式的 data.available_payment_methods[].method 值。 |
| agency | String | M | 傳遞使用者所選支付方式的 data.available_payment_methods[].agency 值。 |
| player_id | String | M | 傳遞在事前準備中確認的目前使用者 Player ID。 |
| vid_type | String | M | SDK 版本值。固定使用 v4。 |
| String | O | 當所選支付方式的 requires_email 值為 true 時,傳遞從使用者取得的電子郵件地址。 | |
| sandbox | Boolean | O | 以 Sandbox URL 測試時使用 true。在正式環境中,請不要傳遞此值,或依環境使用適當的值。 |
回應資訊¶
支付請求 API 不是最終確認支付是否成功的 API。當請求被正常處理時,請使用回傳結果開啟所選 PG 公司的支付 WebView 視窗。
回應值使用¶
請按以下方式使用回應值。
- 使用回應結果,在商店網頁中開啟所選 PG 公司的支付 WebView 視窗。
- 請不要只憑此回應就判定支付已完成。此步驟是開啟支付視窗的步驟。
- 若要確認實際支付結果,請參考查詢支付完成記錄與IAP v4 收據驗證。
請求範例¶
curl -L -v \
-d '{
"language": "ko",
"country": "KR",
"currency": "KRW",
"app_id": "com.com2us.hivesdk.windows.microsoftstore.global.normal",
"server_id": "global",
"market_id": 15,
"market_pid": "com.com2us.hivesdk.windows.microsoftstore.global.normal.item01",
"quantity": 1,
"agency_company_code": 1,
"method": "kakaopay",
"agency": "html5_inicis",
"player_id": "123456789",
"vid_type": "v4",
"email": "bobong@com2us.com",
"sandbox": true
}' \
-H "Content-Type: application/json;charset=utf-8" \
-H "Authorization: Bearer {Bearer 토큰}" \
https://sandbox-hiveiap.qpyou.cn/payment/requests
4. 後續步驟¶
即使使用者已在 PG 公司的支付 WebView 視窗中完成支付,也不能讓 App 用戶端立即進行發放處理。支付完成資訊會由 PG 傳送至 Hive IAP v4 伺服器,因此 App 伺服器必須進行後續確認。
請依照以下順序進行後續處理。
- 呼叫查詢支付完成記錄以查詢已儲存的支付資訊。
- 若需要進一步驗證支付是否已正常完成,請使用查詢回應中的
purchase_bypass_info進行IAP v4 收據驗證。