发送消费信息

当应用用户申请退款时，该接口将用户消费信息传输至应用商店。

消费信息传输API使用Hive服务器和应用服务器之间的服务器到服务器通信。 Hive服务器向应用服务器发送消费信息请求，应用服务器向Hive服务器返回响应。

Info

消费信息传输支持Apple App Store和Google Play。由于每个商店都有不同的触发器和响应数据规范，因此请从下面的选项卡中选择要集成的商店。

Apple App StoreGoogle Play

Apple App Store¶

发送到商店的一些消费信息仅存在于应用服务器上。要将此数据发送到 Apple App Store，应用程序服务器必须将其提供给 Hive 服务器。

应用服务器 URL 是应用服务器打开的 API 端点，用于向 Hive 服务器提供数据。根据以下规范配置端点并将其注册为应用程序服务器 URL。每当用户请求退款时，Hive 服务器都会向此端点发送 POST 请求，并从应用服务器接收所需的数据。 Hive 服务器汇总这些数据并代表应用程序开发人员将消费信息传输到 Apple App Store。

整体流程如下。

App：根据下面的规范配置API端点并准备服务器URL
App：在Hive控制台的附加服务设置>消费信息传输中，启用Apple App Store并注册服务器URL 3、应用客户端：应用运行时，获得同意传输应用内商品消费信息
App用户：在App中申请退款 5、苹果：向Hive服务器发送消费信息请求（CONSUMPTION_REQUEST）
Hive 服务器：向应用程序注册的服务器 URL 发送 POST API 请求，并接收应用程序服务器响应中的消费信息 7、Hive服务器：向Apple App Store发送消费信息。 Apple 在成功时响应 HTTP 202

Warning

如果应用用户未在同意弹窗中同意传输信息，即使 Hive 服务器已从应用服务器接收到数据，也不会将其发送到商店。应用服务器无需发送用户同意状态（customerConsented），该状态由 Hive 服务器直接设置。

禁用防火墙规则¶

注册为服务器 URL 的 API 端点必须使用请求参数中的用户信息 (player_id) 和交易信息 (transaction_id) 检索消费信息，并返回符合以下规范的数据。

要允许 Hive 服务器向应用服务器 API 端点发送请求，请在应用服务器上禁用以下 IP 地址的防火墙入站规则。

Hive 服务器IP
15.165.223.210
3.34.158.195
43.202.20.33
13.209.91.38
3.34.235.15
15.165.134.120

配置API请求（Hive服务器到应用服务器）¶

以下是从Hive服务器发送到应用服务器的POST请求。

API信息	描述
方法	邮政
响应格式	JSON
内容类型	应用程序/json

请求正文¶

请求正文如下。

名称	类型	必填（M：必填，O：可选）	描述
gameindex	整数	M	App Center Game Index
appid	字符串	M	App Center 应用程序 ID
server_id	字符串	M	应用服务器ID
player_id	字符串	M	应用程序中的用户标识符（用于购买验证的用户标识值）。对应V1中的`user_seq`
transaction_id	字符串	M	Apple原始交易ID（`originalTransactionId`）
hiveiap_transaction_id	字符串	M	为每个成功验证的收据生成交易 ID。 Hive IAP v4 收据验证返回的 `hiveiap_transaction_id` 值

以下是请求正文示例。

{
        "gameindex": 539,
        "appid": "com.com2us.hivesdk.normal.freefull.apple.global.ios.universal",
        "server_id": "server_01",
        "player_id": "222333",
        "transaction_id": "2000000123456789",
        "hiveiap_transaction_id": "AP_13"
}

配置API响应（应用程序服务器到Hive服务器）¶

应用服务器将处理结果码（code）、结果消息（message）和消费信息（data）发送给Hive服务器。

响应正文¶

Hive 服务器根据 code 值确定成功。如果值为200，则请求成功，服务器使用data。对于任何其他代码，服务器不会传输该项目并记录 message 作为原因。需要 code。如果省略，则该请求将被视为错误并且不会传输该项目。

名称	类型	必填（M：必填，O：可选）	描述
code	整数	M	处理结果代码。只有200表示成功；所有其他代码均被视为错误
message	字符串	O	处理结果消息。描述错误的原因
data	对象	M	响应数据（成功时需要）
┕ delivery_status	字符串	M	消耗品交付状态。以下交货状态中的值之一
┕ refund_preference	字符串	O	退款优惠。以下退款偏好中的值之一
┕ consumption_percentage	整数	O	消耗百分比。 0-100000，以毫百分比表示 (100000 = 100%)
┕ sample_content_provided	整数	O	是否提供样品内容。 0 或 1

响应代码¶

值	描述
200	成功
400	请求值无效
500	服务器错误

交货状态 (`delivery_status`)¶

表示消耗性物品的交付状态。此字段为必填项，必须指定以下五个值之一。

值	意义
DELIVERED	消耗品已交付且工作正常
UNDELIVERED_QUALITY_ISSUE	由于质量问题，该商品未交付
UNDELIVERED_WRONG_ITEM	交付了不同或不正确的物品
UNDELIVERED_SERVER_OUTAGE	由于服务器中断，该物品未送达
UNDELIVERED_OTHER	由于其他原因该物品未送达

退款优惠 (`refund_preference`)¶

将应用程序的首选退款结果发送给 Apple。如果发送此可选字段，则它必须包含以下三个值之一。

值	意义
GRANT_FULL	更愿意全额退款
DECLINE	宁愿拒绝退款
GRANT_PRORATED	倾向于部分或按比例退款，主要用于订阅

Warning

如果以下任何值无效，则该商品将被排除并且不会传输到商店。

delivery_status 为必填项，并且必须包含上述五个值之一。
如果发送，refund_preference 必须包含上述三个值之一。
如果发送，consumption_percentage 必须是 0 到 100000 之间的整数。

Note

Hive服务器根据Apple的规则自动调整以下值。

如果 delivery_status 不是 DELIVERED，则 consumption_percentage 发送为 0。
如果refund_preference是GRANT_PRORATED（订阅），则省略consumption_percentage。

以下是成功请求的响应正文示例。

{
        "code": 200,
        "message": "OK",
        "data": {
                "delivery_status": "DELIVERED",
                "refund_preference": "GRANT_FULL",
                "consumption_percentage": 100000,
                "sample_content_provided": 0
        }
}

Google Play¶

发送到商店的一些消费信息仅存在于应用服务器上。要将此数据发送到 Google Play，应用程序服务器必须将其提供给 Hive 服务器。

应用服务器 URL 是应用服务器打开的 API 端点，用于向 Hive 服务器提供数据。根据以下规范配置端点并将其注册为应用程序服务器 URL。每当发生退款审核通知时，Hive 服务器都会向此端点发送 POST 请求，并从应用服务器接收所需的数据。 Hive 服务器会汇总这些数据，并代表应用开发者将退款审核信息发送给 Google。

整体流程如下。

App：根据下面的规范配置API端点并准备服务器URL
App：在Hive控制台的附加服务设置>消费信息传输中，启用Google Play并注册服务器URL
应用程序用户：直接向信用卡发卡机构等金融机构申请交易退款（退款）
Google：向Hive服务器发送退款审核通知（pendingRefundReviewNotification）
Hive 服务器：向应用程序注册的服务器 URL 发送 POST API 请求，并接收响应中的数据
Hive 服务器：使用 orders:reviewrefund 向 Google 发送退款审核信息。如果成功，Google 将返回一个空的 HTTP 200 正文

Note

Google Play 退款审核不需要应用内同意流程。当用户直接向金融机构请求退款（退款）时，Google 会将退款审核通知发送到 Hive 服务器进行处理。

禁用防火墙规则¶

注册为服务器 URL 的 API 端点必须使用请求参数中的用户信息 (player_id) 和交易信息 (order_id) 检索消费信息，并返回符合以下规范的数据。

要允许 Hive 服务器向应用服务器 API 端点发送请求，请在应用服务器上禁用以下 IP 地址的防火墙入站规则。

Hive 服务器IP
15.165.223.210
3.34.158.195
43.202.20.33
13.209.91.38
3.34.235.15
15.165.134.120

配置API请求（Hive服务器到应用服务器）¶

以下是从Hive服务器发送到应用服务器的POST请求。

API信息	描述
方法	邮政
响应格式	JSON
内容类型	应用程序/json

请求正文如下。

名称	类型	必填（M：必填，O：可选）	描述
gameindex	整数	M	App Center Game Index
appid	字符串	M	App Center 应用程序 ID
server_id	字符串	M	应用服务器ID
player_id	字符串	M	应用程序中的用户标识符（用于购买验证的用户标识值）。对应V1中的`user_seq`
order_id	字符串	M	Google 订单 ID (`orderId`)
hiveiap_transaction_id	字符串	M	Hive IAP v4 收据验证返回的 `hiveiap_transaction_id` 值

以下是请求正文示例。

{
        "gameindex": 539,
        "appid": "com.com2us.hivesdk.normal.freefull.google.global.android.universal",
        "server_id": "server_01",
        "player_id": "222333",
        "order_id": "GPA.3300-1234-5678-90123",
        "hiveiap_transaction_id": "GO_13"
}

配置API响应（应用程序服务器到Hive服务器）¶

应用服务器将处理结果码（code）、结果消息（message）和消费信息（data）发送给Hive服务器。

Hive 服务器根据 code 值确定成功。如果值为200，则请求成功，服务器使用data。对于任何其他代码，服务器不会传输该项目并记录 message 作为原因。需要 code。如果省略，则该请求将被视为错误并且不会传输该项目。

名称	类型	必填（M：必填，O：可选）	描述
code	整数	M	处理结果代码。只有200表示成功；所有其他代码均被视为错误
message	字符串	O	处理结果消息。描述错误的原因
data	对象	M	响应数据（成功时需要）
┕ refund_preference	字符串	M	退款优惠。以下退款偏好中的值之一
┕ sample_content_provided	整数	M	是否提供样本内容。 0 或 1
┕ consumption_percentage_milliunits	整数	M	消费百分比。 0-100000，以毫百分比表示 (100000 = 100%)
┕ consumption_usage_events	数组	O	消费事件列表（最多1000个）。参见下面的消费事件

响应代码¶

值	描述
200	成功
400	请求值无效
500	服务器错误

退款优惠 (`refund_preference`)¶

将应用的首选退款结果发送给 Google。此必填字段必须包含以下四个值之一。

值	意义
APPROVE	更愿意批准退款
DECLINE	宁愿拒绝退款
NEUTRAL	无偏好（中立）
REFUND_PREFERENCE_UNSPECIFIED	未指定偏好

消费事件（`consumption_usage_events`）¶

每个消费事件包含以下字段。所有字段都是可选的，但如果发送 location，则 location.region_code 是必需的。

名称	类型	必需的	描述
obfuscated_account_id	字符串	O	混淆的帐户标识符
obfuscated_profile_id	字符串	O	混淆的配置文件标识符
consumption_time	字符串	O	消耗时间（RFC 3339，例如`2026-07-20T00:00:00Z`）
ip_address	字符串	O	消费时的IP地址
consumption_item_description	字符串	O	消耗物品的描述
location	对象	O	消费地点信息
┕ region_code	字符串	M（包含 `location` 时）	区域代码（CLDR，例如 `KR`）
┕ administrative_area	字符串	O	行政区
┕ locality	字符串	O	城市
┕ sublocality	字符串	O	次地方性

Warning

如果以下任何值无效，则该项目将被排除并且不会传输给 Google。

refund_preference 是必需的，并且必须包含上述四个值之一。
sample_content_provided 为必填项，且必须为 0 或 1。
consumption_percentage_milliunits 为必填项，并且必须是 0 到 100000 之间的整数。
如果发送，consumption_usage_events 最多可包含 1000 个事件。如果事件包含 location，则需要 location.region_code。

以下是成功请求的响应正文示例。

{
        "code": 200,
        "message": "OK",
        "data": {
                "refund_preference": "APPROVE",
                "sample_content_provided": 0,
                "consumption_percentage_milliunits": 100000,
                "consumption_usage_events": [
                        {
                                "consumption_time": "2026-07-20T00:00:00Z",
                                "ip_address": "203.0.113.10",
                                "consumption_item_description": "Sample consumed item",
                                "location": {
                                        "region_code": "KR"
                                }
                        }
                ]
        }
}

发送消费信息

Apple App Store¶

禁用防火墙规则¶

配置API请求（Hive服务器到应用服务器）¶

请求正文¶

配置API响应（应用程序服务器到Hive服务器）¶

响应正文¶

响应代码¶

交货状态 (delivery_status)¶

退款优惠 (refund_preference)¶

Google Play¶

禁用防火墙规则¶

配置API请求（Hive服务器到应用服务器）¶

配置API响应（应用程序服务器到Hive服务器）¶

响应代码¶

退款优惠 (refund_preference)¶

消费事件（consumption_usage_events）¶

交货状态 (`delivery_status`)¶

退款优惠 (`refund_preference`)¶

退款优惠 (`refund_preference`)¶

消费事件（`consumption_usage_events`）¶