跳轉至

簡易 PG 支付

'簡易 PG 支付'是在 App 伺服器查詢 PG 支付方式、直接在商店網頁中建構支付方式選擇 UI,並以使用者選擇的方式呼叫 PG 公司的支付 WebView 視窗時使用。

本頁說明依序呼叫 payment/methodspayment/requests 的方法。

建議的實作順序如下。

  1. 先查詢支付方式,並在商店網頁中建構支付方式選擇畫面。
  2. 接著當使用者按下 支付 時,開啟所選 PG 公司的支付 WebView 視窗。

1. 概要

串接流程

簡易 PG 支付會在商店網頁中處理支付方式選擇步驟。只有在使用者選擇支付方式之後,才會開啟 PG 公司的支付 WebView 視窗。

建議按照以下順序進行串接。

  1. 使用者在商店網頁中按下 購買 按鈕。
  2. App 伺服器呼叫支付方式查詢 API。
  3. 商店網頁根據回應值建構並顯示支付方式選擇 UI。
  4. 使用者在支付方式選擇 UI 中選擇支付方式並按下 支付
  5. App 伺服器呼叫支付請求 API。
  6. 商店網頁根據回應結果開啟所選 PG 公司的支付 WebView 視窗。
  7. 使用者在 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。

回應值使用

請按以下方式使用回應值。

  1. 使用 data.available_payment_methodsdisplay_nameicon_urlpriority 值,在商店網頁中建構支付方式選擇 UI。
  2. 顯示 requires_emailtrue 的支付方式時,請一併顯示 email_agree_text 文案並要求使用者輸入電子郵件。
  3. 當使用者選擇支付方式時,請將 data.agency_company_codedata.currencydata.available_payment_methods[].agencydata.available_payment_methods[].methoddata.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 取得的值。

需要注意以下事項。

  1. 此 API 不會再次顯示支付方式選擇畫面。
  2. 此 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
email String O 當所選支付方式的 requires_email 值為 true 時,傳遞從使用者取得的電子郵件地址。
sandbox Boolean O 以 Sandbox URL 測試時使用 true。在正式環境中,請不要傳遞此值,或依環境使用適當的值。

回應資訊

支付請求 API 不是最終確認支付是否成功的 API。當請求被正常處理時,請使用回傳結果開啟所選 PG 公司的支付 WebView 視窗。

回應值使用

請按以下方式使用回應值。

  1. 使用回應結果,在商店網頁中開啟所選 PG 公司的支付 WebView 視窗。
  2. 請不要只憑此回應就判定支付已完成。此步驟是開啟支付視窗的步驟。
  3. 若要確認實際支付結果,請參考查詢支付完成記錄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 伺服器必須進行後續確認。

請依照以下順序進行後續處理。

  1. 呼叫查詢支付完成記錄以查詢已儲存的支付資訊。
  2. 若需要進一步驗證支付是否已正常完成,請使用查詢回應中的 purchase_bypass_info 進行IAP v4 收據驗證