Gloebit Developer Logo

Blog

Sandbox

Main Site

Gloebit Service Interface Details

Welcome to the developer page providing all the information you need to integrate Gloebit services into your application. It combines reference information about the services and endpoint specifications for the services. It is meant to be read from the beginning onward. However, given the page's size, feel free to use the References and Endpoints menus to jump around.

Gloebit's Services

Gloebit offers four backend services: Identity, Character, Inventory, and Digital Currency. You can incorporate any of them into your design, or any combination, or all of them. Each can work independently or with other services (for example, character-based inventories).

All backend services are dependent upon the Gloebit Authorization service. Your application must first use the authorization service to get your user's approval for account access. Via this service, Gloebit will authorize the user, ask permission for your application's access, and provide your application an access token for the user's account. Your application then uses the token with the backend services.

Endpoints

All of the Gloebit services are web services, meaning their functionality is accessed via HTTP requests to web resources. This page uses the term "endpoint" to refer to a web resource, including its URL, its HTTP request format, and the functionality it provides. The Endpoints menu lists all of the web resources available in each of the services.

Authorization Service

Your application must use Gloebit's Authorization service before using any of the other Gloebit services. All other services' endpoints require an access token, and you use the Authorization service to acquire access tokens. Gloebit supports OAuth 2.0 (OAuth2) methods for delivering access tokens to your application. During the OAuth2 flow, we will prompt your user to log into the Gloebit system and grant your application access to the user's resources (identity, characters, inventory, etc.) requested by your application.

Access Tokens

An access token is a credential your application provides when accessing a Gloebit user's resources. Your application acquires an access token via the Authorization service and then includes it in requests to Gloebit's backend services. During the authorization process, Gloebit puts the following constraints on the access token:

  • The access token is tied to the application requesting it, exclusively.
  • It is valid only for the resources of the authorizing Gloebit user.
  • It is valid until the user revokes the application's access.
  • It grants access only to the resources in the token's scope.

User

The "user" associated with an access token is a Gloebit account. These users correspond to your application's users only if your application uses Gloebit IDs (from the Identity service) to identify or associate with its users. Otherwise, you should be aware that a user in your application could log into more than one Gloebit account or multiple users in your application could share a single Gloebit account (or many to many).

Scope

An access token's scope is a set of Gloebit-defined scopes that cover the user's resources available to applications. Your application will indicate the requested scope (set of Gloebit scopes) when initiating the Authorization service. Gloebit will inform the user of the requested scope during approval and then, after the user approves, return an access token with that scope. Here are the Gloebit resources and the Gloebit scopes for them:

Resource Scope
User's Gloebit identity. identity
Characters the user has created for your application. character
Inventories your application has created for the user and the user's characters. inventory
User's gloebit balance. balance
Ability to exchange the user's gloebits for your application's products or other items for purchase. transact

For example, if your application wants to access a user's identity and balance and let the user purchase products in your application, you would request an access token with identity, balance, and transact in its scope. (Specifically, the requested scope is a space-separated string specifying them: "identity balance transact".)

Revocation

Currently, Gloebit does not explicitly expire access tokens. They can effectively expire due to storage constraints or other structural causes. Additionally, users can revoke an application's access via their Gloebit dashboard and approved-applications pages.

If a token expires or is revoked, Gloebit will reject any request your application makes with the token. When a request is rejected, your application should check the included failure reason and determine if it needs to return to the authorization process to acquire a new token.

Security

Keeping access tokens secure is paramount. They grant access to your users' Gloebit accounts and information your application stores for your users. Your application's method for storing access tokens must prevent their being exposed to users or third parties.

OAuth 2.0 Authorization Framework

To get approvals from your users to let your application access their Gloebit accounts, we use the OAuth 2.0 (OAuth2) framework. OAuth2 supports securely authorizing your users and accessing their "resources". For a nice, succinct primer on OAuth2, visit Aaron Parecki's OAuth 2 Simplified page. For OAuth2 details, visit the OAuth 2.0 specification page.

Gloebit's OAuth2 implementation supports both confidential (web-server based) and public (browser-based or native-on-device) applications and the Authorization Code Grant and Implicit Grant methods for acquiring access tokens. If your application is web-server based (confidential), use the Authorization Code Grant method. If your application is browser-based or is a native app on devices (public), use the Implicit Grant.

Authorization Code Grant Method

This authorization method is for applications with a back-end server (i.e., web-based, or confidential in OAuth2 terms). It is the more secure method for acquiring access tokens and Gloebit strongly recommends using it if at all possible.

Gloebit Authorization Code Grant Flow Diagram

Your application first uses the Authorize endpoint with a response_type of "code". Gloebit authorizes your user and gets approval for your application to access the user's Gloebit resources, then returns an authorization code via a redirection to your application's redirect URI.

Next, Your application's server extracts the authorization code and posts it to the Exchange for Access Token endpoint for the access token. The security in this method comes from your server providing its OAuth secret during the second step and the access token being returned to your server in the body of the POST response.

For added security, your application should send a "state" parameter to the Authorize endpoint and check it against the returned "state" value (to help prevent CSRF attacks). Plus, you should provide callback URI prefixes in the Authorization fields of your applications configuration page, preferably HTTPS type. Gloebit checks redirect URIs (provided to the Authorize endpoint) against the application's prefixes.

Implicit Grant Method

This authorization method is for browser-based applications or applications that run natively on the device (both considered public in OAuth2 terms). Of the two methods that Gloebit supports for acquiring access tokens, it is the less secure because it delivers the access token via the redirect URI and it does not use a secret for your application. Gloebit sets some additional constraints when using this method.

Your application uses only the Authorize endpoint with a response_type of "token". Gloebit authorizes your user and gets approval for your application to access the user's Gloebit resources, then returns the access token via a redirection to your application's redirect URI. Your application extracts the access token from the URI's fragment.

Per the OAuth2 spec, Gloebit requires that you provide callback URI prefixes in the Authorization fields of your application's configuration page and Gloebit checks the authorization request's redirect URI against the prefixes. Additionally, we require your redirect URI use HTTPS instead of HTTP.

For added security, your application should send a "state" parameter to the Authorize endpoint and check it against the returned "state" value (to help prevent CSRF attacks).

Authorize (endpoint) Authorization Service

An application uses this endpoint to initiate the user authorization process. The endpoint will acquire and return either an authorization code (for an Authorization Code Grant request) or access token (for an Implicit Grant request). It is returned via an HTTP 302 (redirect) response to a "redirect URI" provided by the application.

The endpoint first verifies the provided redirect URI against the application's redirect prefixes (from the Gloebit Application Configuration page). Second, it prompts the user to log into Gloebit if not already logged on. Third, it presents the user with an authorization page for the application and requested scope, and asks the user to confirm the request. Fourth and last, it generates the requested grant and generates the redirect response.

HTTP Info
Redirect (or GET)
oauth2/authorize

Parameters Authorize (endpoint)

All Authorize parameters are supplied as query arguments appended to the URL.

Query Arguments

Required
client_id Application's OAuth Key.
scope Space-delimited string of requested access scopes.
Scopes: user character inventory balance transact.
redirect_uri Application's URI for Gloebit to deliver response to.
response_type Application's requested grant type for OAuth2 authorization.
"code" - Authorization Code Grant type.
"token" - Implicit Grant type.
Optional
state Application-provided string used to maintain state between this request and the callback from Gloebit and to prevent cross-site request forgeries.
access_type Possible values: "online", "offline"
Default value: "online"
Note: Gloebit does not currently support "offline".
approval_prompt Possible values: "force", "auto"
Default value: "force"
"force" - Always present user with an authorization request page.
"auto" - Conditionally request user's authorization.
See Authorization "force"/"auto" reference.
user Application's name for user.
Used solely for logging purposes.
r Application's OAuth Key Alias.
Obsolete - Gloebit generates trackback via client_id.
return-to Application's URI for trackback links.
Overrides URI provided in Default Return-To URI field on application's Gloebit configuration page.

Result Authorize (endpoint)

Upon success, the authorize endpoint sends a 302 (redirect) response for the redirect URI and appends the results to the URI (either as query arguments for the "code" response type or in the fragment for "token" response type.)

If your authorize request used the "code" response type, the query arguments will containing the following:

code Authorization code to exchange for an access token.
state If your authorize request included a "state" argument, the same value will be returned here. If your request did not include a "state" argument, there will not be a "state" argument in the redirect response.

If your authorize request used the "token" response type, the fragment portion of the URI will contain the following:

token Access token for requested user and scope.
token_type Currently not delivered. Access token is always "bearer" type.
state If your authorize request included a "state" argument, the same value will be returned here. If your request did not include a "state" argument, there will not be a "state" argument in the redirect response.

Authorization failures can result in two different outcomes. The outcome is determined by the type of failure.

If the user rejects authorization or Gloebit detects an invalid redirect URI in the request, the authorize endpoint will take the user to a Gloebit page with information about the request failure. This page includes a trackback link to the requesting application.

In all other cases, the authorize endpoint sends a 302 (redirect) response for the redirect URI and appends query arguments containing error information for your application:

error Error code string (defined in OAuth 2.0 specification).
error_description A more detailed explanation of the failure reason. May not always be included.
state If your authorize request included a "state" argument, the same value will be returned here. If your request did not include a "state" argument, there will not be a "state" argument in the redirect response.

Notes Authorize (endpoint)

  • Preferred HTTP method is to redirect the user's browser to the authorize URI.

Prompting User for Approval

Gloebit does two things during a call to the Authorize endpoint. First, it logs the user in to Gloebit, if necessary. Second, it prompts the user to approve your application's access to the user's resources. By default, the approval step always occurs, meaning your user will always see a Gloebit page asking for approval when your application uses the endpoint.

The endpoint's approval_prompt parameter allows your application to have Gloebit conditionally prompt the user. It has two possible values, "force" and "auto":

Authorize - approval_prompt: "force"

Using "force" with approval_prompt causes Gloebit to always prompt the user for access approval. It also causes Gloebit to always generate a new access token (for the combination of application, user, and scope) and discard an existing access token.

It is the default value for the parameter.

Authorize - approval_prompt: "auto"

Using "auto" with approval_prompt causes Gloebit to prompt the user for access approval only if we do not have an existing access token (for the combination of application, user, and scope). If an access token matching the endpoint request's parameters exists, Gloebit will return that access token and might not prompt the user. If no matching access token exists, Gloebit will prompt the user and generate a new access token.

Note: Currently Gloebit does not have a setting for users to always require approval, but we may add one. In the future, with such a setting, a user can choose to force seeing the approval page for your application. However, if you use "auto", Gloebit might still create a new access token only if necessary.

Exchange for Access Token (endpoint) Authorization Service

An application uses this endpoint to exchange an authorization code (received via the Authorize endpoint) for the access token to use with all Gloebit services. It is used only with the Authorization Code Grant type of authorization request. This endpoint supports only the POST access method and all parameters must be sent in the body of the request.

HTTP Info
POST
oauth2/access-token

Parameters Exchange for Access Token (endpoint)

All parameters are passed in the HTTP request body in "application/x-www-form-urlencoded" format.

Form (JSON) Arguments

Required
client_id Application's OAuth Key.
client_secret Application's OAuth Secret.
code Authorization Code received via the Authorize request.
grant_type Possible values: "authorization_code".
Any other value will result in an error.
scope Should match the scope provided by the application in the Authorize request.
redirect_uri URI matching the one provided by the application in the Authorize request.
Optional
access_type Possible values: "online", "offline"
Default value: "online"
Note: Gloebit does not currently support "offline".

Result Exchange for Access Token (endpoint)

Upon success, the endpoint will return an HTTP 200 code along with a JSON object:

access_token The access token necessary for your application to access the user's resources within the requested scope(s). You include this token as a "Bearer" token in the headers of requests to non-authorize endpoints. Currently, Gloebit does not expire access tokens. However, users may cancel authorizations at any time.
refresh_token A token that the application can use to attempt to refresh an access token that has expired. (Because Gloebit does not expire access tokens, currently, the refresh token is unnecessary.) It will not refresh an access token that the user has revoked, and instead you must go through the authorization process again.

Verify Access Token (endpoint) Authorization Service

An application may use this endpoint to check the validity of an access token. The service provides this endpoint as a convenience and debug aid. No Gloebit service requires using it.

HTTP Info
GET
no-op

Access Token Verify Access Token (endpoint)

Endpoint requires an access token be sent in the HTTP header:

Authorization: Bearer <access_token>

Endpoint has no scope requirements for access token.


Result Verify Access Token (endpoint)

The endpoint always returns an HTTP 200 code along with a JSON object:

success Possible values: "true", "false".
"true" - Access token is valid.
"false" - Access token is not valid.
reason Short description of why access token is not valid.

Identity Service

Your application can use Gloebit's Identity service to let Gloebit manage your user accounts. Using this service saves you the trouble of building a login/authentication system. Your users would login via Gloebit to be authenticated, where they can either provide Gloebit login credentials (email + password) or authenticate via Facebook, Google+, Twitter, or LinkedIn.

With this service, after using the Authorization service you would use the Get User ID endpoint to retrieve your user's Gloebit ID. Your application can then use the ID to track the user.

User IDs

Gloebit user IDs are UUIDs. The service provides them as a string in their canonical form:

XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

where each "X" represents a hexadecimal number. The lengths of the sequences are 8, 4, 4, 4, and 12. Thus, each user ID is 36 characters total.

Get User ID (endpoint) Identity Service

An application uses this endpoint to retrieve the Gloebit user ID (uuid) for the user associated with an access token.

HTTP Info
GET
user

Access Token Get User ID (endpoint)

Endpoint requires an access token be sent in the HTTP header:

Authorization: Bearer <access_token>
Required scope for access token: user

Result Get User ID (endpoint)

The endpoint always returns an HTTP 200 code along with a JSON object:

success Possible values: "true", "false".
"true" - Response contains valid user ID and name.
"false" - Request failed. Values for "id" and "name", if included, are not valid.
id Gloebit UUID for the user account associated with the access token.
name User's display name in the Gloebit system.
Will be an empty string if user has not entered a display name for the Gloebit account.
reason Short description of why request failed.

Character Service

Your application can use Gloebit's character service to create and manage characters (or personas or entities or ...) for your users. Each user can have multiple characters in the system. The service allows for storing, retrieving, and editing character details.

The service supports combining with the other Gloebit services. The Inventory service has character-specific endpoints for products. The Digital Currency service allows product purchases to be directed to a character's inventory. Endpoints supporting characters require a character ID. Use the Get List of Characters to get IDs for all of a user's characters.

Character IDs

Gloebit character IDs are UUIDs. The service provides them as a string in their canonical form:

XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

where each "X" represents a hexadecimal number. The lengths of the sequences are 8, 4, 4, 4, and 12. Thus, each character ID is 36 characters total.

Create Character (endpoint) Character Service

An application uses this endpoint to create a character of the given name for the user account associated with the access token. The character name must be unique among all character names created for the application. The endpoint returns the Gloebit ID for the character.

HTTP Info
POST
create-character

Access Token Create Character (endpoint)

Endpoint requires an access token be sent in the HTTP header:

Authorization: Bearer <access_token>
Required scope for access token: character

Parameters Create Character (endpoint)

All parameters are passed in the HTTP request body, either as a JSON dictionary or in "application/x-www-form-urlencoded" format.

Form (JSON) Arguments

Required
name Name of new character. (Must be unique for application.)
Optional
<additional parameters> (except 'id') Any additional parameters in the JSON dictionary are stored with created character.

Result Create Character (endpoint)

The endpoint always returns an HTTP 200 code along with a JSON object:

success Possible values: "true", "false".
"true" - Character creation succeeded.
"false" - Request failed.
character Dictionary of new character information (if request succeeded):
  id: Gloebit UUID for new character.
  name: Name of new character.
  <...>: Additional parameters, if any.
reason Short description of why request failed.

Notes Create Character (endpoint)

  • If character name is not unique among character names created for the application, the request will fail with success "false" and a reason indicating the non-uniqueness. Eventually, we would like to return a list of alternative name suggestions in this case.
  • This endpoint requires that the application get the character name. We welcome suggestions for the look-and-feel of an endpoint flow that would involve Gloebit handling character name entry for your application.

Get List of Characters (endpoint) Character Service

An application uses this endpoint to get a list of the existing characters for the user account associated with the access token.

HTTP Info
GET
get-characters

Access Token Get List of Characters (endpoint)

Endpoint requires an access token be sent in the HTTP header:

Authorization: Bearer <access_token>
Required scope for access token: character

Result Get List of Characters (endpoint)

The endpoint always returns an HTTP 200 code along with a JSON object:

success Possible values: "true", "false".
"true" - Response contains a valid character list.
"false" - Request failed. Character list, if included, is not valid.
characters Array of character information. Each character's information is a dictionary:
  id: Gloebit UUID for character.
  name: Character's name.
  <...>: Additional parameters, if any.
reason Short description of why request failed.

Update Character (endpoint) Character Service

An application uses this endpoint to replace all of the information stored for the provided character ID. It requires configuring the application to allow editing characters on its Gloebit Application Configuration page. The character name, if changing, must be unique among all character names created for the application. Changing character names requires configuring the application to allow editing character names on its Gloebit Application Configuration page.

HTTP Info
POST
update_character

Access Token Update Character (endpoint)

Endpoint requires an access token be sent in the HTTP header:

Authorization: Bearer <access_token>
Required scope for access token: character

Parameters Update Character (endpoint)

All parameters are passed in the HTTP request body, either as a JSON dictionary or in "application/x-www-form-urlencoded" format.

Form (JSON) Arguments

Required
id Gloebit UUID for character.
name Character name.
Optional
<additional parameters> (except 'id' and 'name') Any additional parameters in the JSON dictionary are stored with the updated character.

Result Update Character (endpoint)

The endpoint always returns an HTTP 200 code along with a JSON object:

success Possible values: "true", "false".
"true" - Character update succeeded.
"false" - Request failed.
character Dictionary of character information (if request succeeded):
  id: Gloebit UUID for character.
  name: New name of character.
  <...>: Additional parameters, if any.
reason Short description of why request failed.

Notes Update Character (endpoint)

  • This endpoint entirely replaces the information stored for the character. If you want to preserve additional information stored with the character, you must include it in the JSON object.
  • Use the Get List of Characters endpoint to retrieve all of the information stored for a character.
  • The character ID is verified against the user and application associated with the access token. The update request will fail if either does not match.

Delete Character (endpoint) Character Service

An application uses this endpoint to delete the character associated with the provided character ID.

HTTP Info
POST
delete-character

Access Token Delete Character (endpoint)

Endpoint requires an access token be sent in the HTTP header:

Authorization: Bearer <access_token>
Required scope for access token: character

Parameters Delete Character (endpoint)

All parameters are passed in the HTTP request body, either as a JSON dictionary or in "application/x-www-form-urlencoded" format.

Form (JSON) Arguments

Required
id Gloebit UUID for character.

Result Delete Character (endpoint)

The endpoint always returns an HTTP 200 code along with a JSON object:

success Possible values: "true", "false".
"true" - Character deletion succeeded.
"false" - Request failed.
reason Short description of why request failed.

Notes Delete Character (endpoint)

  • The character ID is verified against the user and application associated with the access token. The delete request will fail if either does not match.

Inventory Service

Your application can use Gloebit's Inventory service to create and manage users' inventories and entitlements. The service supports storing products and items in user and character inventories for your application. Products are defined in the Gloebit system whereas items are defined on-the-fly by your application. Generally, using products provides a basic inventory system and using items provides more advanced inventory possibilities.

The first group of Inventory endpoints below are for products. The second group of Inventory endpoints are for items. Note that all inventory endpoints apply to a single application's inventories and there is no inventory sharing between applications in the Gloebit service.

Products

Products in the Inventory service are just names. In a user's or character's inventory, each product can have a count/quantity associated with it, and nothing more. Thus, products provide a basic inventory service akin to storing entitlements. (See the items section if you require storing more information.)

Products are defined per-application, on the application's configuration page. The third group of fields on the page show your application's existing products and let you add new products. (Follow the link for explanations on the product fields on the configuration page.)

Product Names

Gloebit references products by their names, meaning the endpoints require the name of the product to act upon. Thus, within an application all product names need to be unique. Because the Inventory service partitions by application, different applications can have the same product names and the products will be distinct (and not shareable between the applications).

If you change a product's name, the change will not propagate to your users' inventories. They will contain products by the original name with the same quantity as before the name change. The old-name products will show up in inventory products lists but only the consume operation will work for them.

Grant and Set

The service has endpoints for granting a number of products to an inventory and setting the number of products in an inventory. Granting is synonymous with incrementing the inventory quantity. Setting simply forces the quantity to a value. You can configure whether a product can be grant or set via these endpoints on the configuration page. If disallowed, then the product can only be purchased and consumed. (Purchasing is done via the Transact endpoint in the Digital Currency service.)

Per-Inventory Limits

You can set an upper limit for the number of a product in an inventory (user or character). The service will reject any request that would cause the quantity to go above a product's limit.

Availability

You can mark products as unavailable. The effects of making a product unavailable is limited to the transaction service. It will reject purchases for unavailable products. Existing inventories are not affected by a product's availability and your application can still consume and grant an unavailable product and set its quantity.

User and Character Inventories

The service supports inventories for users and their characters, meaning you can keep an inventory for one of your users and inventories for each of the user's characters at the same time. Gloebit separates the inventories, but your application can share among them via the proper endpoints.

Get User Products (endpoint) Inventory Service

An application uses this endpoint to retrieve a list of the products in the user account associated with the access token. The quantity of each is also returned. Only those products with a quantity greater than zero are included.

HTTP Info
GET
get-user-products

Access Token Get User Products (endpoint)

Endpoint requires an access token be sent in the HTTP header:

Authorization: Bearer <access_token>
Required scope for access token: inventory

Result Get User Products (endpoint)

The endpoint always returns an HTTP 200 code along with a JSON object:

success Possible values: "true", "false".
"true" - Response contains a valid product list.
"false" - Request failed. Product list, if included, is not valid.
products Dictionary of product information.
Keys are the product names.
Values are the product counts.
reason Short description of why request failed.

Grant User Product (endpoint) Inventory Service

An application uses this endpoint to increase the quantity of a product in the application's inventory of the user account associated with the access token. The endpoint checks that the product is enabled, can be granted, and, if it has a per-inventory limit, that the resulting quantity is at most the limit. Product settings are available on the application's Gloebit Application Configuration page.

HTTP Info
POST
grant-user-product/<product_name>/<count>
grant-user-product

Access Token Grant User Product (endpoint)

Endpoint requires an access token be sent in the HTTP header:

Authorization: Bearer <access_token>
Required scope for access token: inventory

Parameters Grant User Product (endpoint)

Parameters may be passed via the endpoint URI (first path) or passed in the HTTP request body (second path) either as a JSON dictionary or in "application/x-www-form-urlencoded" format.

Form (JSON) Arguments

Required
product_name Name of product matching product entry on application's configuration page.
count Quantity of product to grant user.

Result Grant User Product (endpoint)

The endpoint always returns an HTTP 200 code along with a JSON object:

success Possible values: "true", "false".
"true" - Response contains a valid product list.
"false" - Request failed. Product list, if included, is not valid.
product-count Updated product quantity in user's inventory for the application.
reason Short description of why request failed.

Consume User Product (endpoint) Inventory Service

An application uses this endpoint to decrease the quantity of a product in the application's inventory of the user account associated with the access token. The endpoint checks that the product is enabled and that the resulting quantity is at least 0. See the application's Gloebit Application Configuration page to enable or disable products.

HTTP Info
POST
consume-user-product/<product_name>/<count>
consume-user-product

Access Token Consume User Product (endpoint)

Endpoint requires an access token be sent in the HTTP header:

Authorization: Bearer <access_token>
Required scope for access token: inventory

Parameters Consume User Product (endpoint)

Parameters may be passed via the endpoint URI (first path) or passed in the HTTP request body (second path) either as a JSON dictionary or in "application/x-www-form-urlencoded" format.

Form (JSON) Arguments

Required
product_name Name of product matching product entry on application's configuration page.
count Quantity of user's product to consume.

Result Consume User Product (endpoint)

The endpoint always returns an HTTP 200 code along with a JSON object:

success Possible values: "true", "false".
"true" - Response contains a valid product list.
"false" - Request failed. Product list, if included, is not valid.
product-count Updated product quantity in user's inventory for the application.
reason Short description of why request failed.

Set User Product Count (endpoint) Inventory Service

An application uses this endpoint to set the quantity of a product in the application's inventory of the user account associated with the access token. The endpoint checks that the product is enabled, can be granted, and, if it has a per-inventory limit, that the requested quantity is at most the limit. Product settings are available on the application's Gloebit Application Configuration page.

HTTP Info
POST
set-user-product-count/<product_name>/<count>
set-user-product-count

Access Token Set User Product Count (endpoint)

Endpoint requires an access token be sent in the HTTP header:

Authorization: Bearer <access_token>
Required scope for access token: inventory

Parameters Set User Product Count (endpoint)

Parameters may be passed via the endpoint URI (first path) or passed in the HTTP request body (second path) either as a JSON dictionary or in "application/x-www-form-urlencoded" format.

Form (JSON) Arguments

Required
product_name Name of product matching product entry on application's configuration page.
count Quantity of product to set in user's application inventory.

Result Set User Product Count (endpoint)

The endpoint always returns an HTTP 200 code along with a JSON object:

success Possible values: "true", "false".
"true" - Response contains a valid product list.
"false" - Request failed. Product list, if included, is not valid.
product-count Updated product quantity in user's inventory for the application.
reason Short description of why request failed.

Get Character Products (endpoint) Inventory Service

An application uses this endpoint to retrieve a list of the products in the character's inventory. The quantity of each is also returned. Only those products with a quantity greater than zero are included.

HTTP Info
GET
get-character-products/<character_id>
get-character-products

Access Token Get Character Products (endpoint)

Endpoint requires an access token be sent in the HTTP header:

Authorization: Bearer <access_token>
Required scope for access token: inventory

Parameters Get Character Products (endpoint)

The endpoint requires a Gloebit character ID. It may be passed via the endpoint URI (first path) or passed in the HTTP request body (second path) either as a JSON dictionary or in "application/x-www-form-urlencoded" format.

Form (JSON) Arguments

Required
character_id Gloebit character ID.

Result Get Character Products (endpoint)

The endpoint always returns an HTTP 200 code along with a JSON object:

success Possible values: "true", "false".
"true" - Response contains a valid product list.
"false" - Request failed. Product list, if included, is not valid.
products Dictionary of product information.
Keys are the product names.
Values are the product counts.
reason Short description of why request failed.

Grant Character Product (endpoint) Inventory Service

An application uses this endpoint to increase the quantity of a product in the character's inventory. The endpoint checks that the product is enabled, can be granted, and, if it has a per-inventory limit, that the resulting quantity is at most the limit. Product settings are available on the application's Gloebit Application Configuration page.

HTTP Info
POST
grant-character-product/<character_id>/<product_name>/<count>
grant-character-product

Access Token Grant Character Product (endpoint)

Endpoint requires an access token be sent in the HTTP header:

Authorization: Bearer <access_token>
Required scope for access token: inventory

Parameters Grant Character Product (endpoint)

Parameters may be passed via the endpoint URI (first path) or passed in the HTTP request body (second path) either as a JSON dictionary or in "application/x-www-form-urlencoded" format.

Form (JSON) Arguments

Required
character_id Gloebit character ID.
product_name Name of product matching product entry on application's configuration page.
count Quantity of product to grant character.

Result Grant Character Product (endpoint)

The endpoint always returns an HTTP 200 code along with a JSON object:

success Possible values: "true", "false".
"true" - Response contains a valid product list.
"false" - Request failed. Product list, if included, is not valid.
product-count Updated product quantity in character's inventory for the application.
reason Short description of why request failed.

Consume Character Product (endpoint) Inventory Service

An application uses this endpoint to decrease the quantity of a product in the character's inventory. The endpoint checks that the product is enabled and that the resulting quantity is at least 0. See the application's Gloebit Application Configuration page to enable or disable products.

HTTP Info
POST
consume-character-product/<character_id>/<product_name>/<count>
consume-character-product

Access Token Consume Character Product (endpoint)

Endpoint requires an access token be sent in the HTTP header:

Authorization: Bearer <access_token>
Required scope for access token: inventory

Parameters Consume Character Product (endpoint)

Parameters may be passed via the endpoint URI (first path) or passed in the HTTP request body (second path) either as a JSON dictionary or in "application/x-www-form-urlencoded" format.

Form (JSON) Arguments

Required
character_id Gloebit character ID.
product_name Name of product matching product entry on application's configuration page.
count Quantity of character's product to consume.

Result Consume Character Product (endpoint)

The endpoint always returns an HTTP 200 code along with a JSON object:

success Possible values: "true", "false".
"true" - Response contains a valid product list.
"false" - Request failed. Product list, if included, is not valid.
product-count Updated product quantity in character's inventory for the application.
reason Short description of why request failed.

Set Character Product Count (endpoint) Inventory Service

An application uses this endpoint to set the quantity of a product in the character's inventory. The endpoint checks that the product is enabled, can be granted, and, if it has a per-inventory limit, that the requested quantity is at most the limit. Product settings are available on the application's Gloebit Application Configuration page.

HTTP Info
POST
set-character-product-count/<character_id>/<product_name>/<count>
set-character-product-count

Access Token Set Character Product Count (endpoint)

Endpoint requires an access token be sent in the HTTP header:

Authorization: Bearer <access_token>
Required scope for access token: inventory

Parameters Set Character Product Count (endpoint)

Parameters may be passed via the endpoint URI (first path) or passed in the HTTP request body (second path) either as a JSON dictionary or in "application/x-www-form-urlencoded" format.

Form (JSON) Arguments

Required
character_id Gloebit character ID.
product_name Name of product matching product entry on application's configuration page.
count Quantity of product to set in character's application inventory.

Result Set Character Product Count (endpoint)

The endpoint always returns an HTTP 200 code along with a JSON object:

success Possible values: "true", "false".
"true" - Response contains a valid product list.
"false" - Request failed. Product list, if included, is not valid.
product-count Updated product quantity in character's inventory for the application.
reason Short description of why request failed.

Purchase Product (endpoint) Inventory Service

See the Transact endpoint in the Digital Currency service for purchasing products. Specifically, use the endpoint's "Product Transaction" parameters to purchase a product.

When purchasing products, the Transact endpoint automatically adds the product into the user's or character's inventory. It also supports purchasing quantities greater than 1.

Items (Advanced Inventory)

Items in the Inventory systems are dictionaries. Your application defines what to put in each item's dictionary on-the-fly. The service stores all items in folders of the user's inventory. Your application can provide folder names to the endpoints or let them use the default folder.

What to store in the item dictionary is entirely up to your application. Use fields for the states of items, player characteristics, system variants, generalized game state information, or anything your application must track. Gloebit checks for maximum string lengths and maximum number of mappings, so let us know if you hit a limit and have a request for extending them.

As with products, items are store per-application. An item stored by one application cannot be retrieved or edited by another. Also, there are no character-specific items in inventories. Your application can use character-specific folders to separate items among a user's characters.

Folders

The Inventory service stores all inventory items in folders. A folder name is simply a string, at most 36 characters. The endpoints accept a folder-id parameter that your application can use to sort items as you see fit. The endpoints will use a default folder (UUID with all 0's) if your application excludes the folder-id parameter.

As with products and items, folders are application-specific. The same folder name for the same user from two different applications will create distinct folders.

New Item (endpoint) Inventory Service

An application uses this endpoint to create a new item and store it in the inventory of the user's account associated with the access token. If a folder identifier is provided, the item will be stored in it instead of the default folder.

HTTP Info
POST
new-inventory-item

Access Token New Item (endpoint)

Endpoint requires an access token be sent in the HTTP header:

Authorization: Bearer <access_token>
Required scope for access token: inventory

Parameters New Item (endpoint)

All parameters are passed in the HTTP request body, either as a JSON dictionary or in "application/x-www-form-urlencoded" format.

Form (JSON) Arguments

Required
type-id Application's identifier for the item.
Optional
folder-id Folder UUID (of application's choice) to store the item in.
Default folder is used if not provided.
params Dictionary of application's parameters for the item.

Result New Item (endpoint)

The endpoint always returns an HTTP 200 code along with a JSON object:

success Possible values: "true", "false".
"true" - Item successfully added, response contains a valid Gloebit item ID.
"false" - Request failed. Item ID, if included, is not valid.
item-id Gloebit UUID for the new item.
reason Short description of why request failed.

Get Items IDs (endpoint) Inventory Service

An application uses this endpoint to retrieve a list of the items stored in the requested folder.

HTTP Info
GET
get-inventory-item-ids/<folder_id>

Access Token Get Items IDs (endpoint)

Endpoint requires an access token be sent in the HTTP header:

Authorization: Bearer <access_token>
Required scope for access token: inventory

Parameters Get Items IDs (endpoint)

The only parameter, folder_id, is passed as part of the endpoint URL (and not as a query argument). If the folder identifier is left blank, the endpoint will return a list of all items and products in the user's inventory for the application.


Result Get Items IDs (endpoint)

The endpoint always returns an HTTP 200 code along with a JSON object:

success Possible values: "true", "false".
"true" - Item lookups successful, response contains a valid list of item information.
"false" - Request failed. Item ID, if included, is not valid.
item-ids A list of item-information lists containing three elements:   0: Application's identifier for the item (type-id).
  1: Gloebit UUID for the item.
  2: ID of folder the item is stored in.
reason Short description of why request failed.

Get Item (endpoint) Inventory Service

An application uses this endpoint to retrieve an item stored in the inventory of the user account associated with the access token.

HTTP Info
GET
get-inventory-item/<item_id>

Access Token Get Item (endpoint)

Endpoint requires an access token be sent in the HTTP header:

Authorization: Bearer <access_token>
Required scope for access token: inventory

Parameters Get Item (endpoint)

The only parameter, item_id, is passed as part of the endpoint URL (and not as a query argument). It is the Gloebit UUID for the item, not the application's identifier for the inventory item.


Result Get Item (endpoint)

The endpoint always return an HTTP 200 code along with a JSON object: - name: success desc: | Possible values: "true", "false".
"true" - Item lookup successful, response contains valid Gloebit item information.
"false" - Request failed. Item information, if included, is not valid. - name: item desc: | Dictionary of item's parameters set by the application.
It does not include the item's identifier or folder. (See Get Item IDs.) - name: reason desc: Short description of why request failed.

Update Item (endpoint) Inventory Service

An application uses this endpoint to update an item's folder or parameters (or both) in the inventory of the user account associated with the access token.

HTTP Info
PUT
update-inventory-item

Access Token Update Item (endpoint)

Endpoint requires an access token be sent in the HTTP header:

Authorization: Bearer <access_token>
Required scope for access token: inventory

Parameters Update Item (endpoint)

All parameters are passed in the HTTP request body, either as a JSON dictionary or in "application/x-www-form-urlencoded" format.

Form (JSON) Arguments

Required
item_id Gloebit UUID of item to update.
params Dictionary of new item parameters.
Endpoint folds these into the item's existing paramters.
Can be empty dictionary to effect no parameter changes.
Optional
folder_id New folder UUID (of application's choosing) to store item in.
If not provided, item stays in current folder.

Result Update Item (endpoint)

The endpoint always returns an HTTP 200 code along with a JSON object:

success Possible values: "true", "false".
"true" - Item update succeeded.
"false" - Request failed.
reason Short description of why request failed.

Notes Update Item (endpoint)

  • The application's identifier for the item cannot be changed (with this endpoint or any other).

Delete Item (endpoint) Inventory Service

An application uses this endpoing to delete an item entry from the inventory of the user associated with the access token.

HTTP Info
POST
delete-inventory-item/<delete-item>

Access Token Delete Item (endpoint)

Endpoint requires an access token be sent in the HTTP header:

Authorization: Bearer <access_token>
Required scope for access token: inventory

Parameters Delete Item (endpoint)

The only parameter, item_id, is passed as part of the endpoint URL (and not as a query argument). It is the Gloebit UUID for the item, not the application's identifier for the inventory item.


Result Delete Item (endpoint)

The endpoint always returns an HTTP 200 code along with a JSON object:

success Possible values: "true", "false".
"true" - Item deletion succeeded.
"false" - Request failed.
reason Short description of why request failed.

Purchase Item (endpoint) Inventory Service

The Transact endpoint in the Digital Currency service does not directly support purchasing items. However, your application can use the transaction flow callbacks to detect when a purchase has completed and then use the endpoints to create or update the item in the user's inventory.

Digital Currency Service

Your application can use Gloebit's Digital Currency service to handle in-app micro-transactions with gloebits as your digital currency. The service provides an endpoint to look up your user's gloebit balance and an endpoint to request a gloebit payment from your user's account to your account. Both endpoints allow your user to stay within your application. The service also provides an endpoint for redirecting your user to the Gloebit page for purchasing gloebits. The service's three endpoints allow your application to deal entirely in gloebits while Gloebit handles purchasing processes for you.

Engineering Considerations

When integrating this service into your application, you need to consider the following:

  • The Transact endpoint only initiates a gloebit payment request. While the endpoint can outright reject a request for various reasons (e.g., insufficient balance) its success indicates the request has been submitted to the final processing queue. Once on the queue the request is likely to succeed, yet it can still be rejected. Thus, your application cannot rely upon the success of this endpoint indicating the transaction has or will succeed, and the final result of the transaction is (typically) not determined until after the endpoint returns to your application.

    If your application depends upon knowing precisely if or when the transaction succeeds or fails, you want to use the Transact callback URLs. Gloebit accesses these URLs to indicate when the transaction finally succeeds or fails. The callbacks are useful for triggering delivery of items within your application or to our inventories. For product transactions, the callbacks also indicate when a product has been delivered to the user's inventory (or that it will not be).

  • If your application is not using products (in the Gloebit inventory service) and you need to manage asset delivery for transactions, then you should use the Transact callback URLs. They allow your system to ensure transactions are fully committed before delivering assets.

  • The Transact endpoint supports your application including a transaction ID. We strongly suggest you include this ID and, if possible, have it be a UUID. It is very useful in case any disputes occur.

    The Transact endpoint also supports a name for the user on your application. This field can be useful when a single user can have more than one character on an application. The user name is included in the user's transaction history log.

  • The Transact endpoint does not support user-to-user transactions. If you are interested in enabling them, please contact us.

  • If you are using a submit button for transactions, we suggest you make the button inactive upon submission. This will help avoid double posting while the new page is loading.

  • We provide the Balance endpoint so your application can retrieve a user's gloebit balance and display it for the user. Your application can also use the endpoint to check a user's balance before requesting a purchase. Some users may object to this feature's ability to expose gloebits balances. For this reason, Gloebit created a separate scope, "balance", for this endpoint. However, at this time, users are not able to block the endpoint without blocking the entire application access approval. Because Gloebit may yet add a user capability that would effectively block this endpoint, we recommend that your application not depend upon this endpoint being available for all users.

  • The Purchase gloebits endpoint is for redirecting your user to the Gloebit site. If you provide an OAuth Key alias in the URL, Gloebit will add trackback links to your application.

Business Considerations

  • The service is designed to let your applications use gloebits as their only currency. We suggest you price your products in gloebits and do not show an estimated USD cost. (In our experience, monetization decreases when a USD price is shown.)

  • The service includes full transaction histories and provides dispute resolution for all parties on the Gloebit website. Our transaction history includes the transaction ID your application provides. We strongly suggest your applications include transaction IDs to help with bookkeeping and resolving disputes.

  • Gloebit deposits the gloebits you earn from your application's transactions into your merchant Gloebit account. See this service's section on the Gloebit Services Overview page for more information on handling earned gloebits.

  • The service does not support user-to-user transactions at this time. Please contact us if your business is interested in this feature.

Balance (endpoint) Digital Currency Service

An application uses this endpoint to get the gloebit balance of the user account associate with the access token. The application can display the balance for the user and check for sufficient balance before requesting a purchase with the Transact endpoint.

HTTP Info
GET
balance

Access Token Balance (endpoint)

Endpoint requires an access token be sent in the HTTP header:

Authorization: Bearer <access_token>
Required scope for access token: balance

Result Balance (endpoint)

The endpoint always returns an HTTP 200 code along with a JSON object:

success Possible values: "true", "false".
"true" - Balance lookup successful, response contains a valid gloebit balance for the user.
"false" - Request failed. Gloebit balance, if included, is not valid.
balance Number of gloebits in user's Gloebit account.
reason Short description of why request failed.

Notes Balance (endpoint)

  • Only possible failure for endpoint is access token's scope not containing 'balance'.

Transact (endpoint) Digital Currency Service

An application uses this endpoint to initiate a transaction in the Gloebit system. It returns after it has determined whether the transaction can be enacted and, if it can be enacted, has queued the transaction for committing.

The endpoint supports transactions involving products defined on the application's configuration page and transactions involving generic assets handled by the application.

HTTP Info
POST
transact

Access Token Transact (endpoint)

Endpoint requires an access token be sent in the HTTP header:

Authorization: Bearer <access_token>
Required scope for access token: transact

Parameters Transact (endpoint)

All parameters are passed in the HTTP request body, either as a JSON dictionary or in "application/x-www-form-urlencoded" format.

Form (JSON) Arguments

Required
version 1
application-key Application's OAuth Key.
request-created Timestamp, as an integer, for when application created this request.
Endpoint does not have a timezone component.
Applications should select a common timezone when calculting time.
username-on-application Application's name for buyer, if any.
If application does not have usernames, set value to empty string.
Optional
transaction-id Application's UUID (or string at most 36 characters long) identifying the transaction.
If not provided, endpont will return the UUID Gloebit created for tracking the transaction.
Required for Product Transaction
product Name of product (from application's configuration page).
Optional for Product Transaction
product-quantity Number of products to purchase.
Defaults to 1 if not provided.
Must be a whole number (value will be truncated).
character-id Gloebit UUID for character to receive product(s).
Required for Generic Asset Transaction
asset-code Application's name for asset.
gloebit-balance-change Total number of gloebits to transfer.
Note: This is total amount to transfer, not per-asset amount.
asset-quantity Quantity of assets to indicate in user logs.
Does not affect balance transferred. Only used for documentation.
Optional Group of Callback Parameters
asset-enact-hold-url Callback URL to GET when transaction is enacted.
asset-consume-hold-url Callback URL to GET if/when transaction is consumed.
asset-cancel-hold-url Callback URL to GET if/when transaction is canceled.

Result Transact (endpoint)

The endpoint always returns an HTTP 200 code along with a JSON object:

success Possible values: "true", "false".
"true" - Transaction is successfully queued for final processing.
"false" - Transaction was rejected. The 'id', 'balance', and 'product-count' fields, if any, are invalid.
id Transaction ID passed in by application, if any; otherwise Gloebit UUID for transaction.
balance Resulting balance for user account associated with access token. Included only if access token scope includes 'balance'.
product-count Resulting product count in user or character inventory. Included only if request was for a Product Transaction and access token scope includes 'inventory'.
status Short description of status of transaction processing.
reason Short description of why transaction request was rejected.

Notes Transact (endpoint)

  • Success of request indicates user has sufficient funds for transaction and they are on hold.
  • Success of request also indicates transaction is queued for final processing and committing. The transaction might still be canceled.

Transact Callback Parameters

The Transact endpoint is not atomic. It returns either when it knows the transaction cannot be serviced or when Gloebit has queued the transaction request because it has a very good chance at succeeding. If your application is server-based and it needs precise information about the transaction's eventual success or failure or a means to later reject a transaction (e.g. because your purchasing system is also not atomic), then it can use the optional asset callback URL parameters.

Optional

These parameters are optional because they are generally not necessary for product transactions. Gloebit will deliver the product to the user's inventory only when the transaction finally succeeds. You can also omit the parameters if your application has a use case where knowing that the request will likely succeed is sufficient.

URLs

Each parameter is a URL that Gloebit will access at specific stages in processing the queued transaction request. Only URLs accessible from the Gloebit system will work. Browser and native apps cannot use these parameters.

Callbacks

Gloebit will access the URLs with GET requests and will not include any parameters. The URL should include any information your server requires, such as transaction IDs. We suggest using HTTPS URLs for the callbacks.

Each URL access will be blocking, meaning Gloebit waits for your server's response and your server should respond in a timely manner. Additionally, while processing a transaction, Gloebit might access a URL more than once. Your endpoints for these callbacks need to be idempotent and properly handle multiple calls for a transaction.

You can find further details about when each URL can be called in relation to the other URLs and the original Transact request in their descriptions below.

Responses

Your server needs to return a JSON array with 1 or 2 elements to each of the callbacks. The first element is a Boolean indicating whether your server wants to proceed with the transaction. The second element is a string providing status information from your server. Currently the values of the elements affect only Gloebit's "enact" processing.

Transact Parameter: asset-enact-hold-url

Gloebit accesses this URL after it has acquired all holds necessary to process the transaction and is ready to enact it. The transaction is almost guaranteed to succeed at this point, but Gloebit can still roll it back, particularly if your application needs Gloebit to cancel the transaction.

Your application's server can use the response to tell Gloebit to cancel the transaction and roll it back. Your server can also tell Gloebit its processing is pending, in which case Gloebit will access the URL again later. Here are the response options:

JSON Effect
[true] Gloebit enacts the transaction and proceeds to the consume/cancel step.
[false,'pending'] Gloebit retries the transaction processing. During the retry, it will access this URL again.
[false,<any other string>] Gloebit cancels the transaction. It will access the cancel URL for this transaction.

With respect to the Transact call and the other callbacks, Gloebit may access this URL before the Transact call has returned (in which case it will return "success: true"), it will access the this URL before accessing the Consume URL, it might not access this URL before accessing the Cancel URL, it might never access this URL in the Cancel URL case, and it might access this URL again after accessing the others. To be safe, your server should not depend on any particular interleaving.

Transact Parameter: asset-consume-hold-url

Gloebit accesses this URL after it has consumed the enacted holds and committed the transaction. At this point, the transaction is complete and can not be rolled back.

Gloebit currently ignores any response to this callback. Your server should send a JSON response of "[true]" to prevent future incompatibilities.

With respect to the Transact call and the other callbacks, Gloebit may access this URL before the Transact call has returned (in which case it will return "success: true"), it will access this URL only after receiving a True response to an enact callback, and this URL and the Cancel URL are mutually exclusive per transaction.

Transact Parameter: asset-cancel-hold-url

Gloebit accesses this URL after it has canceled the enacted holds and effectively canceled the transaction. In parallel with this access, Gloebit will be rolling back any enacted changes.

Gloebit currently ignores any response to this callback. Your server should send a JSON response of "[true]" to prevent future incompatibilities.

With respect to the Transact call and the other callbacks, Gloebit may access this URL before the Transact call has returned, it likely will not be called if the Transact call returns "success: false", it may access this URL before the Enact URL and possibly without ever accessing the Enact URL, it will access this URL if your response to the Enact URL cancels the transaction, and this URL and the Consume URL are mutually exclusive per transaction.

Delivery of Digital Goods/Entitlements

There are many ways to handle delivery of purchases, allowing the merchant/developer to decide what is best for their application.
If your application is using the Product Inventory Service:

  • See the Product Transact Parameters section which will automatically handle delivery of your product to the user or character as part of the transaction. This is the simplest way to utilize our services.
If your application is not using the Product Inventory Service, or if it is, but you would like to manage additional information internally, then it is best to understand the phases of the Transact request:
  • Prior to Transact request --- You are welcome to deliver digital goods prior to making the Transact request if you are willing to have some leakage or handle reversal of delivery on failure. We recommend you check a user's balance to ensure that the user has enough gloebits in his/her account for the purchase. There is no guarantee that the purchase will succeed, but if your application allows purchases during a live-action game, you may prefer some leakage over making a user wait until the transaction completes.
  • Upon successful response from Transact request --- Once the system enacts all transfers involved, it returns success. The transaction is not yet committed and can still be rolled back, but that is unlikely. This is a great time to deliver goods, and still very simple. Upon a Transact failure response, the action your application takes should be dependent on the message details. Some possibilities include retrying the Transact call, attempting to fix any problems on the application end, or asking the user to purchase enough gloebits to afford the purchase.
  • Upon Transact Callback of asset-enact-hold-url --- This is a similar state as when the Transact request returns success. The transfer has been made to all balances, but has not been committed and can still be rolled back. The transaction processor waits for a response from this url before committing the transaction. Using this callback is a great way to tie in delivery in a way where if delivery of the goods fails, then the gloebit transaction is rolled back. A return of true from this url should mean that you have delivered the goods, and false means you have failed permanently in an attempt to deliver and we should roll back the gloebit transaction. If we receive a response of false, after rolling back the transaction, we will call the asset-cancel-hold-url callback if one has been supplied.
  • Upon Transact Callback of asset-consume-hold-url --- If you are looking to be as conservative as possible with delivery of your digital goods, then you may decide to handle delivery upon receiving this callback; however, this creates the risk that a user is charged gloebits and your system fails to deliver the goods. We recommend that the best conservative method is to begin or queue delivery with the asset-enact-hold-url and complete or commit delivery with the asset-consume-hold-url. This callback means the transaction has been fully completed and committed. It can not be canceled or rolled back at this point and the gloebits have been delivered to the merchant/developer account controlling the application that requested the transaction.
  • Upon Transact Callback of asset-cancel-hold-url --- If at any point, you receive this callback, the transaction has failed and is being or has been rolled back. If you have not delivered your goods, don't. If you have begun delivery of your goods, then cancel processing of that delivery. Once you receive the asset-consume-hold-url callback, you can rest assured that you will not receive the asset-cancel-hold-url for this transaction.
Note:
  • While transactions cannot be rolled back once committed, that does not mean that delivery of gloebits cannot later be reversed. We have to deal with fraud and disputes just like any other payment service. We do our best to insulate our partners from fraud, however, there are situations where we will need to place a hold on or reclaim gloebits. For instance, if gloebits sent to you were fraudulently purchased, or if a user disputes the transaction where that user paid you those gloebits, then we may have to take action. For further details, please read the Merchant Terms of Service for Gloebit.

Purchase gloebits (endpoint) Digital Currency Service

An application uses this endpoint to let the user purchase gloebits on the Gloebit site.

HTTP Info
Redirect (or GET)
purchase

Parameters Purchase gloebits (endpoint)

All Purchase parameters are supplied as query arguments appended to the URL.

Query Arguments

Optional
r OAuth Key alias for the application.
Use to lookup trackback ID, text, imagery, and default Return-To URI.
return-to URI for trackback link to use instead of default Return-To URI.

Result Purchase gloebits (endpoint)

Endpoint does not return any values or perform a URI callback. If user clicks on a trackback link, the user's agent will return to the application via the Return-To URI.


Notes Purchase gloebits (endpoint)

  • Endpoint is the only means for users to purchase gloebits. Applications must redirect users with insufficient balance to the endpoint to buy gloebits. Trackback links on the Gloebit pages allow the user to return to the application within the user's agent.
  • Gloebit shows trackback links only if the r parameter is a valid OAuth Key alias. The return-to parameter is used only if the r parameter is a valid OAuth Key alias.
  • Related: Consumer Experience Flow.

Additional Resources

  • For information regarding how to get started with your merchant account and test in our sandbox, please see the Getting Started Guide. It's fast and free.
  • For information on how to configure the API Settings for your application, please see the Application Configuration Instructions.
  • For code level details regarding integration, please visit our API and Code Examples page.
  • For instructions on moving your application from sandbox to production when you are ready to release, please visit our Going Live page.
  • Gloebit uses OAuth2 in its Authorization service. If you are new to using OAuth2, here is a great, simple summary from Aaron Parecki.

Errors

Any access-token protected API call returns a JSON dictionary. One of the entries will be "success" which will be True or False. If "success" is False, there will be an entry called "reason", which will be set to one of the following:

  • "missing domain"
  • "unknown consumer"
  • "unknown user"
  • "unknown token"
  • "token has expired"
Example:
  • {"success":False, "reason":"unknown token"}

Failure can happen for many reasons including:

  • The fields of the dictionary posted for the Transact call are non proper.
  • The customer's Gloebit account is not authorized to spend gloebits
  • The application is not authorized as a merchant to receive gloebits.
  • The application does not have Transact authorization from the customer.
  • {"success":False, "status":"failed", "reason":"transaction already created"} - Race condition possible if transaction is submitted multiple times at nearly the identical time.
  • {"success":False, "status":"queuing-failed"} - The attempt to queue the transaction for processing failed.
  • Enacting the balance adjustments failed (likely customer does not have enough available gloebits)
  • If using the Product Inventory System & Product Transact Parameters, enacting of the product delivery failed.
  • If we could not enact balance transfers due to issues such as a user not having a sufficient balance not already enacted for other purchases, or your merchant/developer access token being invalid or not containing scope to cover transactions.

On the Roadmap

Some API features on the roadmap are

  • Application specific sub-currencies or soft currencies
  • Management and consumption of resources (brick, wood, mineral, etc) in application
  • User-to-user transactions

If these, or any other features are important to you, please contact us to help us prioritize or register as a potential future feature beta tester.