Connecting to the Lootdog in-game items marketplace

Short description Lootdog.io
Short description of interaction
Terms
Linking an account
Transferring items to the platform
Transferring items from the platform to the partner
Sales reports

Short description Lootdog.io

Lootdog is a trading platform (or simply "platform") that allows users to trade items from games with one another. A user can transfer their game items to the platform, sell them, and withdraw money or buy other items and use them in the game.

Short description of interaction

After integration with a partner, users can list items from the partner's inventory for sale on the platform and transfer them from the platform to a user's inventory.

A "Sell on LootDog.io" button will become available for the user. Pressing the button will remove the item from the partner's inventory and add it to the user's inventory in their account on the platform. If the user does not yet have a linked account on the platform, they will need to first log in (or register on the trading platform) and then link their partner account to their platform account. After linking accounts, a secret linking token (user secret) will be created that will be known to both the platform and gf.

Terms

Item - a particular instance of a game item that belongs to a particular user. If, for example, a user has a few T-34 tanks, then this counts as several items.

Product - a type of item. Users compete on price by selling items of one product type. In the previous example, T-34 is the product. Several instances of it (items) are in the user's inventory.

Partner ID -a secret identifier that is issued to the partner upon connection to the platform. It is used with the platform API.

Partner secret -a secret key that is issued to the partner upon connection to the platform. It is used with the platform API.

User secret - a secret key that is issued to the partner when a user links accounts. It is used to transfer items to the user's inventory on the platform.

PIN - a unique secret key that is generated for an item. It allows for an item to be activated (added) to the user's inventory.

Linking an account

A partner initiates account linking before an item is first transferred to the platform. A description of the steps:

  1. The partner creates a JWT token (created based on the partner secret) that contains the following fields:
    • url - String. Address where the user will be sent after linking the account.
    • nick - String. Name of the partner's account (so a user can see which account they are linking)
    • user_id - String. User identifier on the partner system
  2. Then the partner redirects the user's browser to an address of the type "https://lootdog.io/token?partner_id=<Partner_ID>&jwt=<Token>", with the token received during the previous step
  3. The user logs in to the platform (if necessary) and confirms the linked account
  4. After confirmation, the platform redirects the user's browser to the address "<url from first step>?jwt=<Token>" (if there are other parameters in the URL, "&" will be used).
    The token is signed with the partner secret and will contain the following parameters:
    • token - String. User secret
    • login - String. User's name on the platform
    • user_id - String. User's identifier on the platform
    • avatar - String. Address of the avatar image on the platform
  5. After this, the link will be complete and this user can use the API to transfer items. A user may unlink the account. In that case, the API methods will return 404.

Transferring items to the platform

The server API at the address "https://lootdog.io/api/partner" is used to transfer items.

To authorize access to the API, basic HTTP authorization (partner ID: partner secret) and a list of allowed IP addresses are used.

POST /api/partner/create_item

Transferring an item from the user's inventory on the partner to the user's inventory on the platform (the request is transmitted via JSON in the body)

  • token - String. User secret
  • items - Array of objects. List of items to be transferred, with the following parameters:
    • product_id - String. Product ID on the partner side (can be many items with one product identifier)

    • product_title - String. Product name
    • product_image - String. Address to a square image (300х300 pixels) of the product (must be accessible via  the link without a password)
    • product_desc - String. Product description (can use HTML tags)
    • product_color (optional) - String. solid hex color of a product (for example, "#FFB042").
    • game_ext_id - String. Game's identifier on the platform
    • game_title - String. Game's name on the platform
    • item_code - String. Item's PIN

The product fields are used to fill out the product card. This occurs once, when the first item with that product is transferred. To edit an already created product, you must contact the platform admin.

This request can be repeated multiple times. If an item with that secret code was already transferred to the platform, then it will be disregarded, not duplicated.

The proposed method of error handling (for example, if a response was not received or if the platform API is unavailable) is as follows: repeat the same request until response code 200 is received.

Request format

curl -u <parner_id>:<partner_secret> -X POST -H "Content-Type: application/json" \
-d '{"token": "<user_token>", "items": [{"product_id": "1", "product_title": "title product_1", "product_image": "https://lootdog.io/img/icons/user-large@2x.png", "product_desc": "some long description", "game_ext_id": "aw", "item_code": "token_from_operator"}]}' \
https://lootdog.io/api/partner/create_items

Response format:

{}

Transferring items from the platform to the partner

There are two ways to solve this problem

Open PIN

If a user wants to activate a partner's item, they press the "Open PIN" button on the platform. Then the user receives the item_code (received in the method create_items) and can activate it from the partner. To do so, the partner's client and site must implement a page that shows what type of item will be contained in the code and whether it may be transferred to the inventory of an authorized user.

This means that each code is unique and it cannot be activated from the partner twice.

Regarding open PINs, users can transfer a PIN to one another after opening it. The PIN may be activated on any account.

Closed PIN

In this case, the user will not see the PIN, and can only activate it on a partner account that is linked to the platform account. To use this option, the partner's API address must first be given to platform staff.

To do this, the partner must implement the API method for activating codes of the type "<partner api address>/token/return" with the following parameters:

  • tid - String. Operation identifier
  • uid - String. User identifier from the partner
  • token - String. PIN that needs to be activated (added to inventory)
  • sig - String. Request signature (how to get the signature is described below)

To get a request signature, a transaction identifier must be signed with a HMAC algorithm, and the partner secret must be used as the key.

Data for partner secret: "partner_secret_1"

{
    "tid": "ld-test-transaction-1",
    "sig": "255b34ea31dc0c364987afd0906fce67",
    "uid": "12345678",
    "token": "oogh0IphahKei3kee7"
}

Example request:

curl -u <parner_id>:<partner_secret> -X POST -H "Content-Type: application/json" \
-d '{"tid": "ld-test-transaction-1", "uid": "12345678", "token": "oogh0IphahKei3kee7", "sig": "255b34ea31dc0c364987afd0906fce67"}' \
https://partnersite.com/token/return

Response format:

Successful:

{"status":"ok"}

Error:

"status":"error", "message":"Invalid token"

It is possible to repeat the request multiple times with the same transaction identifier and return the same result.

Response structure:

  • status - execution result ("ok" or "error")
  • message - status detail (for example,  "Invalid token")

Any response code other than 200 will be received as an internal service error and an attempt will be made to repeat the transaction after some time. If 200 is returned and the status equals "error," this means the code cannot be activated and the user will see an error message that activation cannot be completed.

Sales reports

A partner may access reports through the API in CSV format about transactions involving its items.  The request uses basic HTTP authorization (partner ID: partner secret). 

GET /api/partner/report

Parameters:

  • start_date - selection start date in the format "20180926" 
  • end_date - (optional, by default: today) selection end date in the format "20180926" 
  • with_products - (optional, by default: False). Boolean, whether to break down by product

Criteria:

  • date - date
  • product (if selected) - product name and identifier, if selected in the parameters
  • quantity - number of transactions
  • sum - total sum of transactions (with commission, based on purchase price)

Request format:

curl -u <parner_id>:<partner_secret> https://lootdog.io/api/partner/report?start_date=20181001&end_date=20181005

Example response:

date;quantity;sum
20181001;1350;157671.35
20181002;1180;135491.17
20181003;1278;143158.41
20181004;1300;148315.64
20181005;1551;171154.01