Simple PG payment¶

Use simple PG payment when the app server looks up PG payment methods, the store web page directly builds the payment method selection UI, and then opens the PG provider's payment webview window with the method selected by the user.

This page explains how to call payment/methods and payment/requests in order.

The recommended implementation order is as follows.

1. First, look up the payment methods and build the payment method selection screen on the store web page.
2. Then, when the user clicks Pay, open the selected PG provider's payment webview window.

1. Overview¶

Integration flow¶

Simple PG payment handles the payment method selection step inside the store web page. Open the PG provider's payment webview window only after the user selects a payment method.

The following integration flow is recommended.

1. On the store web page, the user clicks the Buy button.
2. The app server calls the payment method lookup API.
3. The store web page builds and displays the payment method selection UI using the response values.
4. The user selects a payment method in the payment method selection UI and clicks Pay.
5. The app server calls the payment request API.
6. The store web page opens the selected PG provider's payment webview window using the response result.
7. The user completes the payment in the PG provider's payment webview window.

Prerequisites¶

Prepare the following values before integrating simple PG payment.

2. Retrieve payment methods¶

The payment method lookup API retrieves the list of PG payment methods currently available for a specific product. Call it first before building the payment method selection screen inside the store web page. This API alone does not start the payment.

Request information¶

Endpoint¶

The endpoints are as follows.

HTTP header¶

The HTTP headers are as follows.

The Bearer token included in the Authorization header is the Hive authentication key in Hive Console > App Center > Project Management > Game List - Select the app > Game Details > Basic Information.

Request body¶

In the following table, required fields are marked as M and optional fields are marked as O.

Response information¶

In the following table, required fields are marked as M and optional fields are marked as O.

Using the response values¶

Use the response values as follows.

1. Use the display_name, icon_url, and priority values in data.available_payment_methods to build the payment method selection UI inside the store web page.
2. When displaying a payment method whose requires_email is true, show the email_agree_text text as well and collect the user's email address.
3. When the user selects a payment method, pass data.agency_company_code, data.currency, data.available_payment_methods[].agency, data.available_payment_methods[].method, and data.available_payment_methods[].requires_email unchanged as input values for the next step.

Request example¶

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

Response example¶

{
  "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. Request payment¶

The payment request API opens the selected PG provider's payment webview window with the payment method that the user has already selected inside the store web page. You must reuse the values returned by the payment method lookup API.

Note the following.

1. This API does not show the payment method selection screen again.
2. This API itself does not finally confirm payment completion.

Request information¶

Endpoint¶

The endpoints are as follows.

HTTP header¶

The HTTP headers are as follows.

The Bearer token included in the Authorization header is the Hive authentication key in Hive Console > App Center > Project Management > Game List - Select the app > Game Details > Basic Information.

Request body¶

In the following table, required fields are marked as M and optional fields are marked as O.

Response information¶

The payment request API is not an API that finally confirms whether the payment succeeded. If the request is processed successfully, use the returned result to open the selected PG provider's payment webview window.

Using the response values¶

Use the response values as follows.

1. Use the response result to open the selected PG provider's payment webview window on the store web page.
2. Do not determine that the payment is complete based only on this response. This step is for opening the payment window.
3. To check the actual payment result, see Payment completion history inquiry and IAP v4 receipt verification.

Request example¶

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. Next steps¶

Do not grant the purchased item immediately in the app client just because the user completed the payment in the PG provider's payment webview window. Payment completion information is delivered from the PG provider to the Hive IAP v4 server, so the app server must perform follow-up verification.

Proceed with the follow-up processing in the following order.

1. Call Payment completion history inquiry to retrieve the stored payment information.
2. If additional validation is needed to confirm that the payment completed successfully, use purchase_bypass_info from the response to perform IAP v4 receipt verification.