跳转至

简易 PG 支付

“简易 PG 支付”适用于以下场景:应用服务器查询 PG 支付方式,在商店网页中直接构建支付方式选择 UI,然后根据用户选择的方式调用 PG 公司的支付 WebView 窗口。

本页说明如何按顺序调用 payment/methodspayment/requests

建议按以下顺序实现。

  1. 先查询支付方式,在商店网页中构建支付方式选择页面。
  2. 然后当用户点击 支付 时,打开所选 PG 公司的支付 WebView 窗口。

1. 概述

接入流程

简易 PG 支付会在商店网页中处理支付方式选择步骤。只有在用户选择支付方式后,才会打开 PG 公司的支付 WebView 窗口。

建议按以下顺序接入。

  1. 用户在商店网页中点击 购买 按钮。
  2. 应用服务器调用支付方式查询 API。
  3. 商店网页根据响应值构建并展示支付方式选择 UI。
  4. 用户在支付方式选择 UI 中选择支付方式后,点击 支付
  5. 应用服务器调用支付请求 API。
  6. 商店网页根据响应结果打开所选 PG 公司的支付 WebView 窗口。
  7. 用户在 PG 公司支付 WebView 窗口中完成支付。

准备事项

在接入简易 PG 支付前,请先准备以下值。

项目 说明
Hive 认证密钥 放入 Authorization 请求头中的 Bearer 令牌。使用 Hive 控制台 > 应用中心 > 项目管理 > 游戏列表 - 选择游戏公司游戏 > 游戏详情 > 基本信息 中的值。
app_id 发起支付的应用 App ID。使用 Hive 控制台 > 应用中心 > 项目管理 > 游戏列表 - 选择游戏公司游戏 > 游戏详情 > 基本信息 中的值。
server_id 发起支付的应用服务器标识值。使用 Hive 控制台 > 应用中心 > 项目管理 > 游戏列表 - 选择游戏公司游戏 > 游戏详情 > 应用服务器 中的值。
market_pid 要支付的商品 ID。使用在 Hive 控制台 > 计费 > 商品管理 > 商品注册 中注册的值。该值以各商店控制台在注册商品前准备好的 Product ID 为基础进行设置。
player_id 发起支付的当前用户 Player ID。使用应用服务器从登录会话或游戏用户信息中确认的值。
market_id 简易 PG 支付使用的市场唯一 ID。固定使用 15

2. 支付方式查询

支付方式查询 API 用于查询指定商品当前可用的 PG 支付方式列表。请先调用该 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 控制台 > 应用中心 > 项目管理 > 游戏列表 - 选择游戏公司游戏 > 游戏详情 > 基本信息 中的 Hive 认证密钥。

请求体

下表中,必填记为 M,可选记为 O。

名称 类型 必填 说明
language String M 用于展示支付方式的游戏语言值。从应用客户端传递当前使用中的语言,格式为 ISO 639-1 Alpha-2。
country String M 用于查询支付方式的目标国家代码。按发起支付的用户所在国家,传递 ISO 3166-1 两位代码。
app_id String M 发起支付的应用 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 控制台 > 应用中心 > 项目管理 > 游戏列表 - 选择游戏公司游戏 > 游戏详情 > 基本信息 中的 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 窗口中完成了支付,也不能在应用客户端立即发放商品。支付完成信息会从 PG 传递到 Hive IAP v4 服务器,因此需要由应用服务器进行后续确认。

请按以下顺序进行后续处理。

  1. 调用 查询支付完成记录 查询已保存的支付信息。
  2. 如需进一步验证支付是否已正常完成,请使用查询响应中的 purchase_bypass_info 执行 IAP v4 收据验证