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 | Hive 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
12345curl -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
1234567>> 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
12345< 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 > Hive 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 > Hive 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)
|
| ┕ 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
123456789{"cs_code": "20000013680","server": ["kr","cn","en","jp"]} - Response sample
1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556// ※ 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 > Hive 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
1234{"cs_code": "20000013680","coupon_code”: “ABCD"} - Response sample
1234567891011121314// 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
