간편 PG 결제¶

'간편 PG 결제'는 앱 서버가 PG 결제 수단을 조회하고, 상점 웹 페이지 안에서 결제 수단 선택 UI를 직접 구성한 뒤, 사용자가 선택한 수단으로 PG사 결제 웹뷰 창을 호출할 때 사용합니다.

이 페이지는 payment/methods와 payment/requests를 순서대로 호출하는 방법을 설명합니다.

권장하는 구현 순서는 아래와 같습니다.

1. 먼저 결제 수단을 조회해 상점 웹 페이지에 결제 수단 선택 화면을 구성하세요.
2. 그다음 사용자가 결제를 누르면 선택한 PG사의 결제 웹뷰 창을 여세요.

1. 개요¶

연동 흐름¶

간편 PG 결제는 상점 웹 페이지 안에서 결제 수단 선택 단계를 처리합니다. 사용자가 결제 수단을 선택한 뒤에만 PG사 결제 웹뷰 창을 엽니다.

아래 순서로 연동을 권장합니다.

1. 상점 웹 페이지에서 사용자가 구매 버튼을 누릅니다.
2. 앱 서버가 결제 수단 조회 API를 호출합니다.
3. 상점 웹 페이지가 응답값으로 결제 수단 선택 UI를 구성, 노출합니다.
4. 사용자가 결제 수단 선택 UI에서 결제 수단을 선택하고 결제를 누릅니다.
5. 앱 서버가 결제 호출 API를 호출합니다.
6. 상점 웹 페이지가 응답 결과로 선택한 PG사의 결제 웹뷰 창을 엽니다.
7. 사용자가 PG사 결제 웹뷰 창에서 결제를 마칩니다.

사전 준비¶

간편 PG 결제를 연동하기 전에 아래 값을 준비하세요.

2. 결제 수단 조회¶

결제 수단 조회 API는 특정 상품에서 현재 사용할 수 있는 PG 결제 수단 목록을 조회하는 API입니다. 상점 웹 페이지 안에 결제 수단 선택 화면을 구성하기 전에 먼저 호출하세요. 이 API만으로는 결제가 시작되지 않습니다.

요청 정보¶

엔드포인트¶

호출 엔드포인트는 아래와 같습니다.

HTTP 헤더¶

HTTP 헤더는 아래와 같습니다.

Authorization 헤더에 넣는 Bearer 토큰은 Hive 콘솔 > 앱센터 > 프로젝트 관리 > 게임목록 - 게임사 게임 선택 > 게임상세 > 기본정보에 있는 Hive 인증키입니다.

요청 바디¶

아래 표에서 필수는 M, 옵션은 O로 표기합니다.

응답 정보¶

아래 표에서 필수는 M, 옵션은 O로 표기합니다.

응답값 사용¶

응답값은 아래와 같이 사용하세요.

1. data.available_payment_methods의 display_name, icon_url, priority 값을 사용해 상점 웹 페이지 안에 결제 수단 선택 UI를 구성하세요.
2. requires_email이 true인 결제 수단을 노출할 때는 email_agree_text 문구를 함께 보여주고 사용자 이메일을 입력받으세요.
3. 사용자가 결제 수단을 선택하면 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사의 결제 웹뷰 창을 여는 API입니다. 결제 수단 조회 API에서 받은 값을 재사용해야 합니다.

주의할 점은 아래와 같습니다.

1. 이 API는 결제 수단 선택 화면을 다시 띄우지 않습니다.
2. 이 API 자체가 결제 완료를 확정하지는 않습니다.

요청 정보¶

엔드포인트¶

호출 엔드포인트는 아래와 같습니다.

HTTP 헤더¶

HTTP 헤더는 아래와 같습니다.

Authorization 헤더에 넣는 Bearer 토큰은 Hive 콘솔 > 앱센터 > 프로젝트 관리 > 게임목록 - 게임사 게임 선택 > 게임상세 > 기본정보에 있는 Hive 인증키입니다.

요청 바디¶

아래 표에서 필수는 M, 옵션은 O로 표기합니다.

응답 정보¶

결제 호출 API는 결제 성공 여부를 최종 확정하는 API가 아닙니다. 요청이 정상적으로 처리되면 반환 결과를 사용해 선택한 PG사의 결제 웹뷰 창을 여세요.

응답값 사용¶

응답값은 아래와 같이 사용하세요.

1. 응답 결과를 사용해 상점 웹 페이지에서 선택한 PG사의 결제 웹뷰 창을 여세요.
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사 결제 웹뷰 창에서 사용자가 결제를 마쳤다고 해서 앱 클라이언트에서 바로 지급 처리하면 안 됩니다. 결제 완료 정보는 PG에서 Hive IAP v4 서버로 전달되므로, 앱 서버에서 후속 확인을 해야 합니다.

아래 순서로 후속 처리를 진행하세요.

1. 결제 완료 내역 조회를 호출해 저장된 결제 정보를 조회하세요.
2. 결제가 정상적으로 완료되었는지 추가 검증이 필요하면 조회 응답의 purchase_bypass_info를 사용해 IAP v4 영수증 검증을 진행하세요.