Skip to content

Web coupon exchange

Server URL

Common URL https://coupon.withhive.com
Sandbox URL https://sandbox-coupon.withhive.com

Coupon server IP

Description Make sure to unapply the inbound firewall rules of the IPs below from the game server.
Common IP 13.124.83.83, 52.78.11.220, 3.34.204.168,
3.35.59.227, 43.202.201.239, 43.200.188.52
Sandbox IP 43.155.155.10

Coupon use API

Basics

Decsriprion Process using issued coupons and sending items
Reference guide Identifier Policy
URL /tp/coupon/api
Method POST Response Format JSON
HTTP Header Content-type application/json Percentage of calls
Authorization Bearer Token (AppCenter Token)

Request parameters

Field Name Type Required (Mandatory: M, Option: O) Description
game_index Integer M AppCenter Game Index
coupon String M Coupon number
cs_code String M In-game user's CS code
server_id String M Game server ID for the delivering items (e.g., KR)
language String O Response message's lanuage code (default: English)
(Refer to Language Code in the reference guide)
Used in exposing the message on the game screen as it is
additionalinfo String O Additional information fot sending to game server
(Delivered in JSON String formatted)

Response elements

Field Name Type Required (Mandatory: M, Option: O) Description
code Integer Y Redponse Code (100: Success)
message String Y Result message according to the response code
  • Call Sample
curl -L -v
 -d '{"game_index":539,"coupon":"HIVESDKTEST","cs_code":"123456789","server_id":"KR","additionalinfo":"{"user_level":50,"chanel":1,"sub_sever":"1"}"}'
 -H "Content-Type: text/html"
 -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNjAzNzc4OTU2LCJqdGkiOiIxODczMTExMzIwIn0.OxWo4R6UdI0BLP1ckt8RlMFrPAb5H7TNedmLFV1Cawc"
 https://sandbox-coupon.withhive.com/tp/coupon/api
  • Request Sample
>> POST /tp/coupon/api HTTP/2
> Host: sandbox-coupon.withhive.com 
> user-agent: curl/7.68.0 
> Content-Type: application/json
> Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNjAzNzc4OTU2LCJqdGkiOiIxODczMTExMzIwIn0.OxWo4R6UdI0BLP1ckt8RlMFrPAb5H7TNedmLFV1Cawc
> Accept: */*
> Content-Length: 163
  • Response Sample
< HTTP/2 200
 < server: nginx
 < date: Wed, 23 Mar 2022 09:49:29 GMT
 < content-type: application/json; charset=utf-8
 {"code":100,"message":"The Coupon Code has been redeemed."}

Response codes (API Server)

Code Description Message
100 Success The Coupon Code has been redeemed.
200 Requested parameter error No parameter, or invalid parameter name.
202 Exceeded the usage limit for the account The number of valid coupons has been exceeded.
203 The available count of group coupon exceeded The number of valid coupons has been exceeded!
204 Mismatched with game data and issued coupon Only available at the event coupon exchange of the corresponding game.
302 Not exist coupon The coupon code does not exist. Please check again.
303 Coupon in use The coupon has already been used.
304 Used coupon The coupon has already been used.
305 Exceeded the usage limit for the coupons
(Unique coupon expired the available count)
All issued coupons have been used.
306 Expired coupon The coupon has expired.
311 Discontinued coupon The coupon has been discontinued.
312 Before coupon period The coupon cannot be used yet. (Except test coupons)
400 Failed to send all items Failed to redeem the coupon.
Please contact our customer support if the issue persists.
401 Failed to send several items Failed to partially redeem the coupon.
Please contact our customer support.
500 DB communication error Failed to redeem the coupon.
Please contact our customer support if the issue persists.
501 Server communication failure Failed to redeem the coupon.
Please contact our customer support if the issue persists.

API agreements on verifying users and searching a game server list

Defines the protocols for validating users and retrieving a list of game servers. To do this, the game server first should disable the firewall inbound rule set against the coupon server IP to enable API communication between the game server and the coupon server.

Basics

Description Defined an API agreement on verifying users from a game server and searching a game server list that can use coupons
URL Hive Console > Billing > Coupon > Web Coupon Exchange Settings > Settings > Register Game Server API
Method POST Response Format JSON
HTTP Header Content-type application/json Percentage of calls

Request parameters (Coupon server to game server)

Field Name Type Required (Mandatory: M, Option: O) Description
cs_code String M A user's CS CODE
server Array O The game server list that enables Web coupon exchange option on the item management menu. Go to Hive Console > billing > Coupon > Web Coupon Exchange Settings > select your app, search, and click settings > the list of servers on Server Information who have valid API URLs and whose Server Exposures are "ON"

Response elements (Game server to coupon server)

Field Name Type Required (Madatory: M, Option: O) Description
code Integer M Response code (100: OK)
message String M Result message according to the response code
data Object M Response data (but returns on a success response only, no response to errors)
┕ default_lang String M Default setting language (exposed if there is no set language)
┕ extra_display Integer O Shows the additionalinfo value additionally after the server name that exposed on the coupon exchange server list
(※ Not exposed when the extra_display value is not provided)
(Shown and hyphen-separated the values only among the JSON values)
  • 0 : Shown the full additionalinfo value
    (e.g., ASIA – 50 – PLATINUM – USER – 0 – 0 )
  • 1 or higher : The number of exposed items among the additionalinfo value
(e.g., Exposed ASIA, the first value, if returns 1.)
┕ server_list Array M Sever list
┕ server_id String M The game server id that delivers items (e.g., KR)
┕ server_display_names Object M Multi-lingual server names that are exposed on the coupon exchange server list
(※ Required the default language and displayed language)
┕ ko ~ ar String O
  •    ko : Korean
  •    en : English
  •    ja : Japanese
  •    zh-hans : Chinese (Simplified)
  •    zh-hant : Chinese (Traditional)
  •    de : German
  •    fr : French
  •    ru : Russian
  •    es : Spanish
  •    pt : Portuguese
  •    id : Indonesian
  •    th : Thai
  •    vi : Vietnamese
  •    it : Italian
  •    tr : Turkish
  •    ar : Arabic
┕ additionalinfo Object O The additional value that is sent to a game server for which delivering items request
  • Request sample

{
    "cs_code": "20000013680",
    "server": [
      "kr",
      "cn",
      "en",
      "jp"
    ]
  }
* Response sample

// ※ The "additionalinfo" value below is a sample. You can send a required value to a game server additionally.
// ※ "server_display_name" is a server name displayed to users, and "server_id" is exposed when making a request to a game server.
{
    "code": 100,
    "message": "Success",
    "data": {
  "default_lang": "en",
  "extra_display": 0,
      "server_list": [
        {
          "server_id": "KR",
          "server_display_names": {
            "ko": "한국서버",
            "en": "Korea Server",
            "ja": "韓国サーバー",
            "zh-hans": "韓國服務器",
            "zh-hant": "韩国服务器",
            "de": "Koreanischer Server",
            "fr": "Serveur coréen",
            "ru": "Корейский сервер",
            "es": "servidor coreano",
            "pt": "servidor coreano",
            "id": "server korea",
            "th": "เซิฟเวอร์เกาหลี",
            "vi": "Máy chủ hàn quốc",
            "it": "Server coreano",
            "tr": "Kore sunucusu",
            "ar": "الخادم الكوري"
          },
          "additionalinfo": {
            "region": "ASIA",
            "user_detail": {
              "level": 50,
              "tier": "PLATINUM",
              "nickname": "USER",
              "gold": "0",
              "gem": "0"
            }
          }
        },
        ......
      ]
    }
  }
  // When an error occurs because of a wrong parameter
  {
    "code": 200,
  "message": "No parameter, or invalid parameter name."
  }
  // Invalid user data (CS_CODE)
  {
    "code": 201,
  "message": "No data, or invalid cs_code."
  }
  • Example Screen
    • Expose the string sent from the game server to the server selection UI as it is

API Agreements on Verifying Creator Coupon

Basics

Description Defined an API agreement on verifying creator coupon from a game server or a creator server
URL Hive Console > Billing > Coupon > Web Coupon Exchange Settings > Settings > Register Creator API
Method POST Response Format JSON
HTTP Header Content-type application/json

Request parameters (Coupon Server to Creator(Game) Server)

Field Name Type Required (Mandatory: M, Option: O) Description
cs_code String M A user's CS CODE
coupon_code String M the coupon number
additionalinfo Object O the additional information that is sent to a creator server or a game server.

Response elements (Creator(Game) Server to Coupon Server)

Field Name Type Required (Madatory: M, Option: O) Description
code Integer M Response code (100: OK)
message String M Result message according to the response code
  • Request sample
{
  "cs_code": "20000013680",
  "coupon_code”: “ABCD"
}
  • Response sample
// Success
{
    "code":100, "message": "Success"
}
// invoking an error becase of invalid parameters
{
    "code":200, "message": "No parameter, or invalid parameter name."
}
// when the coupon received from a creator is invalid
{
    "code":201, "message": "No data, or invalid creator."
}
  • (PC Screen) when the coupon is not available