简易 PG 支付¶
“简易 PG 支付”适用于以下场景:应用服务器查询 PG 支付方式,在商店网页中直接构建支付方式选择 UI,然后根据用户选择的方式调用 PG 公司的支付 WebView 窗口。
本页说明如何按顺序调用 payment/methods 和 payment/requests。
建议按以下顺序实现。
- 先查询支付方式,在商店网页中构建支付方式选择页面。
- 然后当用户点击 支付 时,打开所选 PG 公司的支付 WebView 窗口。
1. 概述¶
接入流程¶
简易 PG 支付会在商店网页中处理支付方式选择步骤。只有在用户选择支付方式后,才会打开 PG 公司的支付 WebView 窗口。
建议按以下顺序接入。
- 用户在商店网页中点击 购买 按钮。
- 应用服务器调用支付方式查询 API。
- 商店网页根据响应值构建并展示支付方式选择 UI。
- 用户在支付方式选择 UI 中选择支付方式后,点击 支付。
- 应用服务器调用支付请求 API。
- 商店网页根据响应结果打开所选 PG 公司的支付 WebView 窗口。
- 用户在 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。 |
响应值使用方法¶
请按如下方式使用响应值。
- 使用
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 控制台 > 应用中心 > 项目管理 > 游戏列表 - 选择游戏公司游戏 > 游戏详情 > 基本信息 中的 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 窗口中完成了支付,也不能在应用客户端立即发放商品。支付完成信息会从 PG 传递到 Hive IAP v4 服务器,因此需要由应用服务器进行后续确认。
请按以下顺序进行后续处理。
- 调用 查询支付完成记录 查询已保存的支付信息。
- 如需进一步验证支付是否已正常完成,请使用查询响应中的
purchase_bypass_info执行 IAP v4 收据验证。