Game > Gamebase > API v1.2 Guide

Updates

  • Changed IAP API.
  • Added storeCode as required parameter to call Get Simple Launching API.
  • Added storeCode information of the maintenance target for the response result of Check Maintenance API.
  • Added Validate TransferAccount API to verify TransferAccount that is published in advance and used for device transfer on a guest account.
  • Changed the date time of API response result from Epoch Time to ISO 8601 (ssXXX:mm:HH'T'dd-MM-yyyy). regDate and lastLoginDate for response result of Token Authentication, Get Member, and Get Members API.
  • Added the Exhaust Coupons API.
  • Added the Withdraw API.
  • Corrected the price data type of Purchase (IAP) from Long to Float.
  • Added information of users who are suspended from withdrawal to the result of Token Authentication and Get Member API Response, as the feature of suspension of withdrawal has been added.

Advance Notice

Gamebase Server API provides APIs as follows, in the RESTful format. Following information is required to use Server API.

Server Address

To call API, below address is needed, which is also available in the Gamebase Console.

https://api-gamebase.cloud.toast.com

image alt

AppId

App ID, as a project ID of NHN Cloud, can be found on the Project List page of the Console. image alt

SecretKey

Secret Key, as a control access of API, can be found in the Gambase Console. It must be set at the HTTP header to call Server API.

[Note]
When a secret key is exposed and a wrong call is made, click Create to create a new secret key and replace the old one.

image alt

TransactionId

AS part of managing API internally within a server that calls API, TransactionId is provided. By setting a transaction ID at the HTTP header from a calling server to call API, the Gamebase server delivers results with corresponding TransactionId set at the response HTTP Header and Response Body Header of results.

Common

HTTP Header

Following items should be set at the HTTP Header to call API.

Name Required Value
Content-Type mandatory application/json; charset=UTF-8
X-Secret-Key mandatory Refer to description of SecretKey
X-TCGB-Transaction-Id optional Refer to description of TransactionId

API Response

As a response to all API requests, HTTP 200 OK is delivered. Whether an API request is successful or not can be determined in reference of the Header of Response Body.

[Request]

Content-Type: application/json
X-TCGB-Transaction-Id: 88a1ae42-6b1d-48c8-894e-54e97aca07fq
X-Secret-Key: IgsaAP
GET https://api-gamebase.cloud.toast.com

[Response]

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-TCGB-Transaction-Id: 88a1ae42-6b1d-48c8-894e-54e97aca07fq
{
    "header": {
        "transactionId": "88a1ae42-6b1d-48c8-894e-54e97aca07fq",
        "isSuccessful": true,
        "resultCode": 0,
        "resultMessage": "Success."
    }
}
Key Type Description
transactionId String The value set at HTTP Header when API is requested.
If the value is not delivered, return value that is created within Gamebase.
isSuccessful boolean Whether it is successful or not.
resultCode int Result code
0 for success; return error codes, for failure
resultMessage String Result message



Authentication

Token Authentication

Authenticates an Access Token issued to a login user. If it is normal, return information of a corresponding user.

[Method, URI]

Method URI
GET /tcgb-gateway/v1.2/apps/{appId}/members/{userId}/tokens/{accessToken}?linkedIdP=false

[Request Header]

Check common requirements.

[Path Variable]

Name Type Value
appId String NHN Cloud project ID
userId String ID of a login user
accessToken String Access Token issued to a login user

[Request Parameter]

Name Type Required Value
linkedIdP boolean optional True or false (Default is false)
Whether IdP-related information, used when Access Token is issued, is included or not

[Response Body]

{
    "header": {
        "transactionId": "String",
        "resultCode": 0,
        "resultMessage": "String",
        "isSuccessful": true
    },
    "linkedIdP": {
        "idPCode": "String",
        "idPId": "String"
    },
    "member": {
        "userId": "String",
        "valid": "Y",
        "appId": "String",
        "regDate": "2019-08-27T17:41:05+09:00",
        "lastLoginDate": "2019-08-27T17:41:05+09:00",
        "authList": [
            {
                "userId": "String",
                "authSystem": "String",
                "idPCode": "String",
                "authKey": "String",
                "regDate": "2019-08-27T17:41:05+09:00"
            },
            {
                "userId": "String",
                "authSystem": "String",
                "idPCode": "String",
                "authKey": "String",
                "regDate": "2019-08-27T17:41:05+09:00"
            }
        ],
        "temporaryWithdrawal": {
            "gracePeriodDate": "2020-04-18T09:12:01+09:00"
        }
    }
}
Key Type Description
linkedIdP Object Login user's IdP information
linkedIdP.idPCode String IdP information
e.g. Guest, PAYCO, and Facebook
linkedIdP.idPId String IdP ID
member.userId String User ID
member.lastLoginDate String Last login time ISO 8601
Not available for first-time login user
member.appId String appId
member.valid String Value of a successful login user is "Y"
(For description of other values, refer to member API.))
member.regDate long Time when a user created an account
authList Array[Object] Information related to user-authenticated IdP.
authList[].authSystem String Authentication system internally used within Gamebase
User authentication system to be provided.
authList[].idPCode String User-authenticated IdP information
e.g. Guest, PAYCO, and Facebook
authList[].authKey String User separator issued at authSystem
temporaryWithdrawal Object Information regarding pending withdrawal
Only "T" value provides valid
temporaryWithdrawal.gracePeriodDate String Expiration time for pending withdrawal ISO 8601

[Error Code]

Error Code



Launching

Get Simple Launching

In the console, you can view the launching information provided when starting up a client app, such as the server address, install URL, current maintenance status, maintenance time, and messages. To check only if the current maintenance setting is enabled, use [Check Maintenance] API.

[Method, URI]

Method URI
GET /tcgb-launching/v1.2/apps/{appId}/launching/simple

[Request Header]

Check Common Factors

[Path Variable]

Name Type Value
appId String NHN Cloud Project ID

[Request Parameter]

Name Type Required Value
osCode OsCode true OS code
AOS, IOS, WEB, WINDOWS
storeCode Enum true Store Code
- GG: Google
- ONESTORE
- AS: AppStore
clientVersion String true Client version

[Response Body]

OK
{
    "header": {
        "resultCode": 0,
        "resultMessage": "String",
        "isSuccessful": true
    },
    "launchingData": {
        "status": {
            "code": 200,
            "message": "String"
        },
        "app": {
            "storeCode": "String",
            "accessInfo": {
                "serverAddress": "String",
                "csInfo": "String"
            },
            "relatedUrls": {
                "termsUrl": "String",
                "csUrl": "String",
                "punishRuleUrl": "String",
                "personalInfoCollectionUrl": "String"
            },
            "install": {
                "url": "String"
            }
        }
    }
}
Maintenance
{
    "header": {
        "resultCode": 0,
        "resultMessage": "String",
        "isSuccessful": true
    },
    "launchingData": {
        "status": {
            "code": 303,
            "message": "String"
        },
        "app": {
            "storeCode": "String",
            "accessInfo": {
                "serverAddress": "String",
                "csInfo": "String"
            },
            "relatedUrls": {
                "termsUrl": "String",
                "csUrl": "String",
                "punishRuleUrl": "String",
                "personalInfoCollectionUrl": "String"
            },
            "install": {
                "url": "String"
            }
        },
        "maintenance": {
            "typeCode": "String",
            "beginDate": "2018-05-23T10:44:00+09:00",
            "endDate": "2022-01-01T10:44:00+09:00",
            "url": null,
            "reason": "String",
            "message": "String"
        }
    }
}
Key Type Description
status Object Information which shows the current client status
status.code int Client status code

OK: 200
Update recommended: 201, Update required: 300
Service terminated: 302
Maintenance in progress: 303
status.message String Client status message
app Object App information
app.storeCode String App Store code
'GG', 'AS', etc.
app.accessInfo Object Information set on the console app screen
app.accessInfo.serverAddress String Server address
The server address set on the client side has a higher priority.
When no client server address is set, the server address set on the app screen is delivered.
app.accessInfo.csInfo String Customer Center information
app.relatedUrls Object In-app URL to be used within the app
app.relatedUrls.termsUrl String Terms and Conditions
app.relatedUrls.csUrl String Customer Center
app.relatedUrls.punishRuleUrl String Ban Rules
app.relatedUrls.personalInfoCollectionUrl String Privacy Information Agreement
app.install Object App Installation information
app.install.url String Install URL
maintenance Object Maintenance Information
maintenance.typeCode String Maintenance type code
Overall maintenance : 'SYSTEM', Maintenance per App: 'APP'
maintenance.beginDate Date Maintenance start date ISO 8601
maintenance.endDate Date Maintenance end date ISO 8601
maintenance.url String Maintenance URL
maintenance.reason String Maintenance reason
maintenance.message String Default maintenance reason message



Member

Get Member

Retrieve detailed information of a single member.

[Method, URI]

Method URI
GET /tcgb-member/v1.2/apps/{appId}/members/{userId}

[Request Header]

Check common requirements.

[Path Variable]

Name Type Value
appId String NHN Cloud project ID
userId String User ID to retrieve

[Request Parameter]

Name Type Required Value
includeMemberInfo boolean optional true or false (default value true) Including detailed information of user device, OS, etc.

[Response Body]

{
    "header": {
        "transactionId": "String",
        "resultCode": 0,
        "resultMessage": "SUCCESS",
        "isSuccessful": true
    },
    "member": {
        "userId": "String",
        "valid": "Y",
        "appId": "String",
        "regDate": "2019-08-27T17:41:05+09:00",
        "lastLoginDate": "2019-08-27T17:41:05+09:00",
        "authList": [
            {
                "userId": "String",
                "authSystem": "String",
                "idPCode": "String",
                "authKey": "String",
                "regDate": "2019-08-27T17:41:05+09:00"
            }
        ]
    },
    "temporaryWithdrawal": {
        "gracePeriodDate": "2020-04-18T09:12:01+09:00"
    },
    "memberInfo": {
        "deviceCountryCode": "String",
        "usimCountryCode": "String",
        "language": "String",
        "osCode": "String",
        "telecom": "String",
        "storeCode": "String",
        "network": "String",
        "deviceModel": "String",
        "osVersion": "String",
        "sdkVersion": "String",
        "clientVersion": "String"
    }
}
Key Type Description
member Object Basic information of a retrieved user
member.userId String User ID
member.valid Enum Y: Normal user
D: Withdrawn user
B: Banned user
M: Missing account
member.appId String appId
member.regDate String Time when a user created an account
member.lastLoginDate String Last login time
Not available for a first-time login user
member.authList Array[Object] Information related to user-authenticated IdP
member.authList[].userId String User ID
member.authList[].authSystem String Authentication system used internally within Gamebase
User authentication system to be provided
member.authList[].idPCode String User-authenticated IdP information
e.g. Guest, PAYCO, and Facebook
member.authList[].authKey String User separator issued at authSystem
member.authList[].regDate String Mapping time between IdP information with user account
temporaryWithdrawal Object Information regarding pending withdrawal
Only "T" value provides valid
temporaryWithdrawal.gracePeriodDate String Expiration time for pending withdrawal ISO 8601
memberInfo Object Additional user information
memberInfo.deviceCountryCode String Country code of user device
memberInfo.usmCountryCode String Country code of user USIM
memberInfo.language String User language
memberInfo.osCode String OS type of user device
memberInfo.telecom String Telecommunication provider
memberInfo.storeCode String Store code
memberInfo.network String Network environment
e.g. 3G and WiFi
memberInfo.deviceModel String Model name of user device
memberInfo.osVersion String OS version of user device
memberInfo.sdkVersion String SDK version
memberInfo.clientVersion String Client version

[Error Code]

Error Code


Get Members

Retrieves brief information about multiple members.

[Method, URI]

Method URI
POST /tcgb-member/v1.2/apps/{appId}/members

[Request Header]

Check common requirements.

[Path Variable]

Name Type Value
appId String NHN Cloud project ID

[Request Body]

Name Type Required Value
userIdList Array[String] mandatory User ID to retrieve
["userId", "userId", "userId",...]

[Response Body]

{
    "header": {
        "transactionId": "String",
        "resultCode": 0,
        "resultMessage": "SUCCESS",
        "isSuccessful": true
    },
    "memberList": [
        {
            "userId": "String",
            "valid": "Y",
            "appId": "String",
            "regDate": "2019-08-27T17:41:05+09:00"
        }
    ]
}
Key Type Description
memberList Array [Object] Basic information of retrieved users
memberList[].userId String User ID
memberList[].valid Enum Y: Normal user
D: Withdrawn user
B: Banned user
M: Missing account
memberList[].appId String appId
memberList[].regDate String Time when a user created an account

[Error Code]

Error Code


Get IdP Information

Retrieve IdP information mapped with user ID.

[Method, URI]

Method Type URI
POST String /tcgb-member/v1.2/apps/{appId}/auth/authKeys

[Request Header]

Check common requirements.

[Path Variable]

Name Type Value
appId String NHN Cloud project ID

[Request Body]

Name Type Required Value
userIdList Array[String] mandatory User ID to retrieve
["userId", "userId", "userId",...]

[Response Body]

{
    "header": {
        "transactionId": "String",
        "resultCode": 0,
        "resultMessage": "SUCCESS",
        "isSuccessful": true
    },
    "result": {
        "String": [
            {
                "authKey": "String",
                "idPCode": "gbid",
                "authSystem": "String"
            }
        ]
    }
}
Key Type Description
result Array [Object] Basic information of retrieved users
An object, with userId as key, and IdP information as value
authkey String User separator issued at authSystem
IdPCode String User-authenticated IdP information
e.g. Guest, PAYCO, and Facebook
authSystem String Authentication system used internally within Gamebase
Authentication system to be provided

[Error Code]

Error Code


Get UserId Information with Auth key

Retrieve a user ID mapped to user authentication key.

[Method, URI]

Method URI
POST /tcgb-member/v1.2/apps/{appId}/members/userIds/authKeys?authSystem={authSystem}

[Request Header]

Check common requirements.

[Path Variable]

Name Type Value
appId String NHN Cloud project ID

[Request Parameter]

Name Type Required Value
authSystem String mandatory Authentication system used internally within Gamebase
User authentication system to be provided
Currently provides gbid

[Request Body]

Name Type Required Value
authKeyList Array[String] mandatory authKey issued at authSystem
["authKey", "authKey", "authKey",...]

[Response Body]

{
    "header": {
        "transactionId": "String",
        "resultCode": 0,
        "resultMessage": "SUCCESS",
        "isSuccessful": true
    },
    "result": {
        "String": "String"
    }
}
Key Type Description
result Array [Object] Basic information of a retrieved user
An object with authKey as key, and useID as value.

[Error Code]

Error Code


Ban Histories

Looks up users' ban history.

[Method, URI]

Method URI
GET /tcgb-member/v1.2/apps/{appId}/members/bans

[Request Header]

Check Common Factors

[Path Variable]

Name Type Value
appId String NHN Cloud Project ID

[Request Parameter]

Name Type Required Value
begin String mandatory Ban history query start time (ISO 8601 standard time, UTF-8 encoding required)
E.g. yyyy-MM-dd'T'HH:mm:ss.SSSXXX
end String mandatory Ban history query end time (ISO 8601 standard time, UTF-8 encoding required)
If banned between the start and end time, the query result shows this.
page String optional Page to query about. Starting from 0
size String optional Number of data per page

[Response Body]

{
    "header": {
        "transactionId": "String",
        "resultCode": 0,
        "resultMessage": "SUCCESS",
        "isSuccessful": true
    },
    "pagingInfo": {
        "first": true,
        "last": true,
        "numberOfElements": 0,
        "page": 0,
        "size": 0,
        "totalElements": 0,
        "totalPages": 0
    },
    "result": [
        {
            "appId": "String",
            "banCaller": "CONSOLE",
            "banReason": "String",
            "banType": "TEMPORARY",
            "beginDate": 0,
            "endDate": 0,
            "flags": "String",
            "message": "String",
            "name": "String",
            "regUser": "String",
            "releaseCaller": "CONSOLE",
            "releaseDate": 0,
            "releaseReason": "String",
            "releaseUser": "String",
            "seq": 0,
            "templateCode": 0,
            "userId": "String"
        }
    ]
}
Key Type Description
pagingInfo Object Queried page information
pagingInfo.first boolean True if it is the first page
pagingInfo.last boolean True if it is the last page
pagingInfo.numberOfElements int Total number of data
pagingInfo.page int Page No.
pagingInfo.size int Number of data per page
pagingInfo.totalElements int Total number of data
pagingInfo.totalPages int Total number of pages
result Array[Object] Queried ban history details
result.appId String NHN Cloud Project ID of the queried ban
result.banCaller String Subject of calling ban
result.banReason String Reason of ban
result.banType String Type of ban TEMPORARY or PERMANENT
result.beginDate Long Start date of ban epoch time
result.endDate Long End date of ban epoch time
result.flags String Returns 'Leaderboard' when you have selected Delete Leaderboard upon Registering Ban in the console.
result.message String Ban message
result.name String Template name registered in the console
result.regUser String Banned user
result.releaseCaller String Subject of unban
result.releaseDate Long Date of unban epoch time
result.releaseReason String Reason of unban
result.releaseUser String Unbanned user
result.seq Long Sequence number of ban history
result.templateCode Long Code value of ban template registered in the console
result.userId String User ID

[Error Code]

Error Code


Ban Release Histories.

Queries the user's unban history.

[Method, URI]

Method URI
GET /tcgb-member/v1.2/apps/{appId}/members/bans/release

[Request Header]

Check Common Factors

[Path Variable]

Name Type Value
appId String NHN Cloud Project ID

[Request Parameter]

Name Type Required Value
begin String mandatory Unban history query start time (ISO 8601 standard time, UTF-8 encoding required)
E.g. yyyy-MM-dd'T'HH:mm:ss.SSSXXX
end String mandatory Unban history query end time (ISO 8601 standard time, UTF-8 encoding required)
If unbanned between the start and end time, the query result shows this.
page String optional Page to query about. Starting from 0
size String optional Number of data per page

[Response Body]

{
    "header": {
        "transactionId": "String",
        "resultCode": 0,
        "resultMessage": "SUCCESS",
        "isSuccessful": true
    },
    "pagingInfo": {
        "first": true,
        "last": true,
        "numberOfElements": 0,
        "page": 0,
        "size": 0,
        "totalElements": 0,
        "totalPages": 0
    },
    "result": [
        {
            "appId": "String",
            "banCaller": "CONSOLE",
            "banReason": "String",
            "banType": "TEMPORARY",
            "beginDate": 0,
            "endDate": 0,
            "flags": "String",
            "message": "String",
            "name": "String",
            "regUser": "String",
            "releaseCaller": "CONSOLE",
            "releaseDate": 0,
            "releaseReason": "String",
            "releaseUser": "String",
            "seq": 0,
            "templateCode": 0,
            "userId": "String"
        }
    ]
}
Key Type Description
pagingInfo Object Queried page information
pagingInfo.first boolean True if it is the first page
pagingInfo.last boolean True if it is the last page
pagingInfo.numberOfElements int Total number of data
pagingInfo.page int Page No.
pagingInfo.size int Number of data per page
pagingInfo.totalElements int Total number of data
pagingInfo.totalPages int Total number of pages
result Array[Object] Queried ban information
result.appId String NHN Cloud Project ID of the queried ban
result.banCaller String Subject of calling ban
result.banReason String Reason of ban
result.banType String Type of ban TEMPORARY or PERMANENT
result.beginDate String Start date of ban epoch time
result.endDate String End date of ban epoch time
result.flags String Returns 'Leaderboard' when you have selected Delete Leaderboard upon Registering Ban in the console.
result.message String Ban message
result.name String Template name registered in the console
result.regUser String Banned user
result.releaseCaller String Subject of unban
result.releaseDate String Date of unban epoch time
result.releaseReason String Reason of unban
result.releaseUser String Unbanned user
result.seq Long Sequence number of ban history
result.templateCode Long Code value of ban template registered in the console
result.userId String User ID

[Error Code]

Error code


Validate TransferAccount

Validates the ID and password issued for transferring the guest account. For valid TransferAccount, return issued userID information.

[Method, URI]

Method URI
POST /tcgb-gateway/v1.1.2/apps/{appId}/members/transfer-account

[Request Header]

Check Common Factors

[Path Variable]

Name Type Value
appId String NHN Cloud Project ID

[Request Parameter]

None

[Request Body]

{
    "account": {
        "id": "198704206255",
        "password": "Zw548q7zE"
    }
}
Key Type Description
account.id String ID to be validated
account.password String Password to be validated

[Response Body]

{
    "header": {
        "transactionId": "String",
        "resultCode": 0,
        "resultMessage": "SUCCESS",
        "isSuccessful": true
    },
    "member": {
        "userId": "String",
        "valid": "Y",
        "appId": "String",
        "regDate": "2019-08-27T17:41:05+09:00",
        "lastLoginDate": "2019-08-27T17:41:05+09:00"
    }
}
Key Type Description
member Object Basic information of the queried user
member.userId String User ID
member.valid Enum Y: Normal user
D: Withdrawn user
B: Banned user
M: Lost account
member.appId String App ID
member.regDate String The time when the user created the account
member.lastLoginDate String The last login time
The user who logged in for the first time has no value

[Error Code]

Error code


Withdraw

Withdraws (Deletes) a user account.

[Note] If the account is withdrawn using the Withdraw Server API instead of the withdraw API of SDK, it needs to delete the cached data including tokens by calling the logout API of SDK after the withdrawal.

[Method, URI]

Method URI
DELETE /tcgb-gateway/v1.3/apps/{appId}/members/{userId}?regUser={regUser}

[Request Header]

Checks common items

[Path Variable]

Name Type Value
appId String NHN Cloud project ID
userId String User ID who wants to withdraw their account

[Request Parameter]

Name Type Required Value
regUser String mandatory The system or user information of the entity that requested withdrawal
- The information can be viewed from Console > 'Withdrawal History' in the 'Member' page
- The withdrawal history can only be viewed by the withdrawn user

[Request Body]

None

[Response Body]

{
    "header": {
        "transactionId": "String",
        "resultCode": 0,
        "resultMessage": "SUCCESS",
        "isSuccessful": true
    }
}

[Error Code]

Error code



Maintenance

Check Maintenance Set

Check whether maintenance is currently set.

[Method, URI]

Method URI
GET /tcgb-launching/v1.2/apps/{appId}/maintenances/under-maintenance

[Request Header]

Check common requirements.

[Path Variable]

Name Type Value
appId String NHN Cloud project ID

[Request Parameter]

N/A

[Response Body]

{
    "header": {
        "transactionId": "String",
        "resultCode": 0,
        "resultMessage": "String",
        "isSuccessful": true
    },
    "appId": "",
    "underMaintenance": true,
    "maintenances": [
        {
            "typeCode": "APP",
            "beginDate": "2017-01-01T12:10:00+07:00",
            "endDate": "2017-02-01T12:17:00+07:00",
            "url": "http://url.info",
            "message": "maintenance message",
            "targetStores": [
                "GG",
                "AS",
                "ONESTROE"
            ]
        }
    ]
}
Key Type Description
underMaintenance Boolean Whether maintenance is currently set
maintenances Object Default maintenance information, if maintenance is set
maintenances.typeCode Enum APP: Maintenance set in a game
SYSTEM: Maintenance set by the Gamebase system
maintenances.beginDate String Start time of maintenance. ISO 8601
maintenances.endDate String End time of maintenance. ISO 8601
maintenances.url String Detailed maintenance URL
maintenances.message String Maintenance message
maintenances.targetStores Array[Enum] Storecode of a client for the maintenance setting of a particular client only
- GG: Google
- ONESTORE: ONE store
- AS: AppStore

[Error Code]

Error Code



Coupon

Check Validation And Consume Coupon

Validate published coupon code and change coupon status via console. For valid coupons, change to consume status and return item information to be paid as response result.

[Method, URI]

Method URI
POST /tcgb-gateway/v1.2/apps/{appId}/members/{userId}/coupons/{couponCode}?storeCode={storeCode}

[Request Header]

Check common issues

[Path Variable]

Name Type Value
appId String NHN Cloud project ID
userId String User ID to use coupons
couponCode String Coupon code

[Request Parameter]

Name Type Required Value
storeCode String optional If a coupon usable only at certain stores is issued from the console, the store code needs to be included
If it's usable at all stores, set the parameter to ALL or omit the parameter
- GG: Google
- ONESTORE: ONE store
- AS: AppStore

[Response Body]

{
    "header": {
        "resultCode": 0,
        "resultMessage": "SUCCESS",
        "isSuccessful": true
    },
    "result": {
        "title": "Coupon Title",
        "benefits": [
            {
                "itemId": "heart",
                "amount": 10
            },
            {
                "itemId": "diamond",
                "amount": 20
            }
        ]
    }
}
Key Type Description
result Object Coupon Information
result.title String Coupon name
result.benefits Array[Object] Information of item to be provided
result.benefits.itemId String Item ID
result.benefits.amount Integer Item count

[Error Code]

Error Code



Purchase(IAP)

Consume

If the store payment (Google Play Store, App Store, ONEStore, etc.) has been made successfully, it issues the purchased items to the user, records the purchase history in the server, and then informs the Gamebase of the payment consumption. You can consume payment only once per payment, and the payment is not consumed if the payment status is not normal.

[Note] Only the item payment with the product type CONSUMABLE at the time of registration will be consumed. Can consume once per payment, and IAP regards any payment without consumption as not issuing the purchased item.

Unconsumed payment history can be viewed through SDK and View Unconsumed Payment History API. Even if the unconsumed payment history exists through the API, the provisioning history within the game server becomes the priority if the game server has the history about the item provisioning. (If an API timeout occurs due to a network failure, etc., there might be cases where payment is completed in Gamebase whereas the item is not issued to the user due to API response failure in the game server.)

[Note] If it is not possible to manage all item issuance history inside the game, a safety measure for a duplicate issuance or non-issuance issue is required, for example, by setting the request timeout of API to 10 seconds or longer, and logging the history at least when an API timeout occurs.

[Method, URI]

Method URI
POST /tcgb-inapp/v1.2/apps/{appId}/consume

[Request Header]

Check common issues

[Path Variable]

Name Type Value
appId String NHN Cloud project ID

[Request Parameter]

N/A

[Request Body]

{
    "paymentSeq": "2019091931571201",
    "accessToken": "90fD1bs1guXwY6aZ7rseEKYW_6gMCISjDASgten4MD6O7XZD7VRjZcs8OTm8lOQVFTegoY4WK78P2WQCMm7cx"
}
Name Type Required Value
paymentSeq String mandatory Payment number
accessToken String mandatory Payment authentication token (not a login authentication token)

[Note] When client calls requestPurchase API, the purchaseToken for response is used as accessToken

[Response Body]

{
    "header": {
        "isSuccessful": true,
        "resultCode": 0,
        "resultMessage": "SUCCESS"
    },
    "result": {
        "price": 1500.0,
        "currency": "KRW",
        "productSeq": 12345
    }
}
Key Type Description
result Object Basic payment information
result.price Float Payment price
result.currency String Payment currency
result.productSeq Long Payment item number (original item number registered on console)

[Error Code]

Error Code


List Consumables

List non-consumed payment, which is not consumed even if paid up.

[Method, URI]

Method URI
POST /tcgb-inapp/v1.2/apps/{appId}/consumable

[Request Header]

공통 사항 확인

[Path Variable]

Name Type Value
appId String NHN Cloud project ID

[Request Parameter]

없음

[Request Body]

{
    "marketId": "GG",
    "userChannel": "GF",
    "userKey": "QXG774PMRZMWR3BR"
}
Name Type Required Value
marketId String mandatory Stroe code
GG: Google, AS: Apple, ONESTORE: One store
userChannel String mandatory User channel
Currently not realized, with the GF setting at all times
userKey String mandatory User ID

[Response Body]

{
    "header": {
        "isSuccessful": true,
        "resultCode": 0,
        "resultMessage": "success"
    },
    "result": [
        {
            "paymentSeq": "2016122110023124",
            "productSeq": 1000292,
            "currency": "KRW",
            "price": 1000.0,
            "accessToken": "oJgM1EfDRjnQY7yqhWCUVgAXsSxLWq698t8QyTzk3NeeSoytKxtKGjldTc1wkSktgzjsfkVTKE50DoGihsAvGQ"
        },
        {
            "paymentSeq": "2016122110023125",
            "productSeq": 1000292,
            "currency": "KRW",
            "price": 1000.0,
            "accessToken": "7_3zXyNJub0FNLed3m9XRAAXsSxLWq698t8QyTzk3NeeSoytKxtKGjldTc1wkSktgzjsfkVTKE50DoGihsAvGQ"
        }
    ]
}
Key Type Description
result Array[Object] Basic payment information
result[].paymentSeq String Payment number
result[].productSeq Long Payment item number (original item number registered on console)
result[].currency String Payment currency
result[].price Float Payment price
result[].accessToken String Payment authentication token

[Error Code]

Error Code


List Active Subscriptions

List payment of user's current subscriptions.

[Method, URI]

Method URI
POST /tcgb-inapp/v1.2/apps/{appId}/active-subscriptions

[Request Header]

Check common issues

[Path Variable]

Name Type Value
appId String NHN Cloud project ID

[Request Parameter]

N/A

[Request Body]

{
    "marketId": "GG",
    "packageName": "com.toast.gamebase",
    "userChannel": "GF",
    "userKey": "QXG774PMRZMWR3BR"
}
Name Type Required Value
marketId String mandatory Store code
GG : Google, AS : Apple, ONESTORE : One store
packageName String mandatory packageName of the app registered on console
userChannel String mandatory User channel
Currently not realized, with the GF setting at all times
userKey String mandatory User ID

[Response Body]

{
    "header": {
        "isSuccessful": true,
        "resultCode": 0,
        "resultMessage": "SUCCESS"
    },
    "result": [
        {
            "channel": "GF",
            "userId": "string",
            "paymentSeq": "2018102610330423",
            "appId": "com.toast.gamebase",
            "productId": "subs_p1w",
            "productType": "AUTO_RENEWABLE",
            "productSeq": 1002904,
            "currency": "KRW",
            "price": 1000.0,
            "paymentId": "GPA.3375-2193-1175-57698",
            "originalPaymentId": "GPA.3375-2193-1175-57698",
            "purchaseTimeMillis": 1540522998289,
            "expiryTimeMillis": 1541134994548
        }
    ]
}
Key Type Description
result Array[Object] Basic payment information
result[].channel String User channel
result[].userId String User ID
result[].paymentSeq String Payment number
result[].appId String Package name
result[].productId String Identifier of product (item) registered at store
result[].productType String Product (item) type
Subscription: AUTO_RENEWABLE
result[].productSeq Long Payment item number (original item number registered on console)
result[].currency String Payment currency
result[].price Float Payment price
result[].paymentId String Recently updated store payment number
result[].originalPaymentId String Initial store payment number
result[].purchaseTimeMillis Long Recent updated time
result[].expiryTimeMillis Long Subscription expiration time

[Error Code]

Error Code



Leaderboard

Gamebase provides Wrapping to server API of NHN Cloud Leaderboard. With Wrapping, NHN Cloud products become available at a user server on a consistent interface.

Wrapping API

API Method Wrapping URI Leaderboard URI
Retrieve User Count Registered at Factor GET /tcgb-leaderboard/v1.2/apps/{appId}/factors/{factor}/user-count /leaderboard/v2.0/appkeys/{appKey}/factors/{factor}/user-count
Retrieve Score/Rank of a Single User GET /tcgb-leaderboard/v1.2/apps/{appId}/factors/{factor}/users?userId={userId} /leaderboard/v2.0/appkeys/{appKey}/factors/{factor}/users?userId={userId}
Retrieve Scores/Ranks of Multiple Users POST /tcgb-leaderboard/v1.2/apps/{appId}/get-users /leaderboard/v2.0/appkeys/{appKey}/get-users
Retrieve Entire Scores/Ranks of Range GET /tcgb-leaderboard/v1.2/apps/{appId}/factors/{factor}/users?start={start}&size={size} /leaderboard/v2.0/appkeys/{appKey}/factors/{factor}/users?start={start}&size={size}
Register Score of a Single User POST /tcgb-leaderboard/v1.2/apps/{appId}/factors/{factor}/users/{userId}/score /leaderboard/v2.0/appkeys/{appKey}/factors/{factor}/users/{userId}/score
Register Score/ExtraData of a Single User POST /tcgb-leaderboard/v1.2/apps/{appId}/factors/{factor}/users/{userId}/score-with-extra /leaderboard/v2.0/appkeys/{appKey}/factors/{factor}/users/{userId}/score-with-extra
Register Scores of Multiple Users POST /tcgb-leaderboard/v1.2/apps/{appId}/scores /leaderboard/v2.0/appkeys/{appKey}/scores
Register Scores/ExtraData of Multiple Users POST /tcgb-leaderboard/v1.2/apps/{appId}/scores-with-extra /leaderboard/v2.0/appkeys/{appKey}/score-with-extra
Delete Leaderboard Information of a Single User DELETE /tcgb-leaderboard/v1.2/apps/{appId}/factors/{factor}/users /leaderboard/v2.0/appkeys/{appKey}/factors/{factor}/users

For more information of the API, click the following link.

Leaderboard Guide

Example of API Call
Content-Type: application/json
X-TCGB-Transaction-Id: 88a1ae42-6b1d-48c8-894e-54e97aca07fq
X-Secret-Key: IgsaAP

GET https://api-gamebase.cloud.toast.com/tcgb-leaderboard/v1.2/apps/{appId}/factors/{factor}/user-count



Others

Support

To inquire about causes of failure in API call, upload API Call URL (with HTTP body, if available) along with response results to Customer Center, and we'll respond ASAP.

Example of API Call
GET https://api-gamebase.cloud.toast.com/tcgb-launching/v1.2/apps/C3JmSctU/maintenances/under-maintenance
Result of Failed API Response
{
    "header": {
        "transactionId": "18a1ae42-6b1d-54c8-894e-54e97bca07fq",
        "resultCode": -4010002,
        "resultMessage": "Gamebase product appKey is invalid, appId:C3JmSctU",
        "traceError": {
            "trackingTime": 1489726350287,
            "throwPoint": "gateway",
            "uri": "/tcgb-launching/v1.2/apps/C3JmSctU/maintenances/under-maintenance"
        },
        "isSuccessful": false
    }
}
TOP