Sending consumption information

An API is provided to transmit user consumption information to the app store when an app user requests a refund.

The 'Consumption Information Transmission' API uses a Server-to-Server communication method between the Hive Server and the app server. When the Hive Server sends a consumption information transmission request to the app server, the app server returns the response value to the Hive Server.

Operation flow¶

The following summarizes the overall operation flow of the 'Consumption Information Transmission' API call and response.

1. App: Prepare the server URL by configuring the API endpoint
2. App: Select Enable Consumption Information Transmission in the Hive console, and register the server URL
3. App client: While the app is running, agree to transmit in-app product consumption information
4. App user: Request a refund in the app
5. Apple: Send a consumption information request (CONSUMPTION_REQUEST) to the Hive server
6. Hive server: Send a POST API request to the server URL registered by the app, and receive consumption information data as the response value from the app server
7. Hive server: Transmit consumption information to the app store (Apple responds with HTTP 202 on success)

Some of the consumption information to be transmitted to the app store exists only on the app server. In this case, for the Hive server to transmit the consumption information to the app store, the app server must first pass the data to the Hive server.

The app server URL is the API endpoint opened by the app server for the app server to pass data to the Hive server. After configuring the API endpoint and registering it as the app server URL, the Hive server sends a POST request to this API endpoint each time a user requests a refund, and receives the necessary data from the app server. The Hive server aggregates this data and completes the transmission of consumption information to the app store on behalf of the app.

API endpoint configuration (server URL)¶

When the app server receives a request at the API endpoint registered as the server URL, it must look up the consumption information using the user information (player_id) and transaction information (transaction_id) in the request parameters, and return data that matches the response protocol.

Disable firewall rules¶

To allow the Hive server to send requests to the app server's API endpoint, the app server must disable the firewall inbound rules for the IP addresses below.

After disabling the firewall rules, refer to the information below to configure the API endpoint.

API request (Hive server → app server) configuration¶

This is the POST request information sent from the Hive server to the app server.

Request body¶

The request body information is as follows.

The following is an example of the request body.

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

API response (app server → Hive server) configuration¶

The app server passes the processing result code (code), result message (message), and consumption information (data) to the Hive server.

Response body¶

The Hive server determines success based on the code value. If it is 200, the request is treated as successful and data is used; for any other code, the item is not transmitted and message is recorded as the reason. code is required, and if it is not sent, the item is treated as an error and not transmitted.

The following is an example of a successful response.

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

Response codes¶

Delivery status (delivery_status)¶

Indicates the delivery status of the consumable item, and must be one of the 5 values below (required).

Refund preference (refund_preference)¶

Passes the app's preferred refund handling direction to Apple (optional). If a value is sent, it must be one of the 3 values below.