G2G OpenAPI Beta (1.0.0)

Introduction

Get started on the G2G OpenAPI with our guide on managing your information on G2G. The G2G OpenAPI can provide the following functionalities for our sellers:

  • Offer management
  • Inventory management

Authentication

Access keys consist of an access key ID and secret access key.

To access G2G OpenAPI, you will need to request from G2G.

When your request to access G2G OpenAPI is approved, you can create access keys from G2G OpenAPI management page. You authenticate with our API by providing the appropriate key in the request Authorization header. Never share your secret keys. Keep them guarded and secure.

Authentication is handled via HTTP headers, as shown in the table below:

Param Type Descritpion
g2g-api-key String Your access key ID created in G2G.
Example: c09222e3fc40ffb25fc947f738b1abf1
g2g-userid String Your G2G user ID.
Example: 509205
g2g-signature String Signature generated by API path, api_key, user_id and timestamp via HMAC-SHA256 hashing algorithm.
Example: e318d3e932719916a9f9ebb57e2011961bd47abfa54a36e040d050d8931596e2
g2g-timestamp timestamp This is to indicate the timestamp of the request, in miliseconds. Required for all requests. Expires in 5 minutes.
Example: 1654675838694

Setup API Key

  1. Login to https://www.g2g.com/.

  2. On top right of the menu bar, click on your avatar, select API Integration.

User Bar Menu

  1. Request API integration access if you have not gotten permission to use G2G OpenAPI.

  2. On the API integration page, click "Generate key" to generate the G2G API and Secret key.

API Integration Page

  1. Please copy the secret key and keep it securely. You will not be able to retrieve the secret key if you lose it, only re-generate a new key.

Generate API Key

  1. You can start to send requests to G2G OpenAPI by generating the g2g-signature and adding it to the HTTP request headers.

Verifying Signatures

Javascript
var CryptoJS = require("crypto-js");

const secretKey = "dJirm8nG5AqQWoh7J5EHw3373Dk95zjRHaQ3gnv99kw"; // Your API Secret Key
const apiKey = "b5769724c1cb1d52c58717d3d12ae2fe"; // Your API Key
const userId = "100000"; // Your User ID
const timestamp = "1653278884000"; // g2g-timestamp
const canonicalUrl = "/v1/offers/G1650445167989US/inventory_items/ba8551d9-47e3-424a-a809-4f043059eefb"; // API Endpoint 

let canonicalString = canonicalUrl + apiKey + userId + String(timestamp);

const signature = CryptoJS.HmacSHA256(canonicalString, secretKey);

console.log(String(signature)) // This value should match with g2g-signature, which is 0884a10b8d07d9fb69cccd3ae0d00fdfbedc6b74fff22ed86b14cd235e73268c

Python
import hashlib, hmac

secret_key = "dJirm8nG5AqQWoh7J5EHw3373Dk95zjRHaQ3gnv99kw" # Your API Secret Key
api_key = "b5769724c1cb1d52c58717d3d12ae2fe" # Your API Key
user_id = "100000" # Your User ID
timestamp = "1653278884000" # g2g-timestamp
canonical_url = "/v1/offers/G1650445167989US/inventory_items/ba8551d9-47e3-424a-a809-4f043059eefb" # API Endpoint 

canonical_string = canonical_url + api_key + user_id + str(timestamp);

signature = hmac.new(
    key=bytes(secret_key.encode("utf8")),
    msg=bytes(canonical_string.encode("utf8")),
    digestmod=hashlib.sha256,
).hexdigest()

print(signature) # This value should match with g2g-signature, which is 0884a10b8d07d9fb69cccd3ae0d00fdfbedc6b74fff22ed86b14cd235e73268c

PHP
$secret_key = "dJirm8nG5AqQWoh7J5EHw3373Dk95zjRHaQ3gnv99kw"; // Your API Secret Key
$api_key = "b5769724c1cb1d52c58717d3d12ae2fe"; // Your API Key
$user_id = "100000"; // Your User ID
$timestamp = "1653278884000"; // g2g-timestamp
$canonical_url = "/v1/offers/G1650445167989US/inventory_items/ba8551d9-47e3-424a-a809-4f043059eefb"; // API Endpoint 
  
$canonical_string = $canonical_url.$api_key.$user_id.(string)$timestamp;
$signature = hash_hmac("sha256", $canonical_string, $secret_key);
  
echo $signature; // This value should match with g2g-signature, which is 0884a10b8d07d9fb69cccd3ae0d00fdfbedc6b74fff22ed86b14cd235e73268c

API Call Flows

Create Offer Flow

Create Offer API Call Flow

Upload Code Flow

Upload Code Flow is mainly for Digital Code order.

Create Offer API Call Flow

Order Delivery Flow

direct_top_up only supported in V2 and V2 is coming soon. Stay tuned!

Order Delivery Flow is mainly for Direct Top Up order.

Deliver Order API Call Flow

Understand delivery attributes for Direct Top Up

  1. Buyer has to fill in Order Information when place order.

Order Information

  1. When you call Get Attributes API, delivery_method_list will be returned in the response.
  2. Under delivery_method_list, lookup attribute_group_list.
  3. From the Order Information sample image, you will get below response:
{
    "attribute_group_list": [
        {
            "attribute_group_id": "e02308e5",
            "attribute_group_name": "User ID",
            "input_field": "text",
            "input_settings": {},
            "is_required": true,
            "attribute_key": "delivery_info_1",
            "attribute_list": []
        },
        {
            "attribute_group_id": "1759fb6c",
            "attribute_group_name": "Servers (Ragnarok X: Next Generation)",
            "input_field": "dropdown",
            "input_settings": {
                "is_searchable": false
            },
            "is_required": true,
            "attribute_key": "delivery_info_2",
            "attribute_list": [
                {
                    "attribute_id": "98f0250f",
                    "attribute_name": "Aldebaran",
                    "sub_attribute_list": []
                },
                {
                    "attribute_id": "6ab853d2",
                    "attribute_name": "Angeling",
                    "sub_attribute_list": []
                },
                ... // more options
            ]
        }
    ]
}
  • The 1st attribute is a text field, which is refers to User ID input and the attribute_key is delivery_info_1.
  • The 2nd attribute is a dropdown field, which is refers to Server input and the attribute_key is delivery_info_2.
  • You are adviced to use attribute_key for integration instead of attribute_group_id or attribute_group_name.
  1. When order is placed, you will receive webhook order.api_delivery and delivery_method_list will be provided in the payload.
{
    "delivery_method_list": [
        {
            "attribute_group_id": "e02308e5",
            "attribute_group_name": "User ID",
            "attribute_key": "delivery_info_1",
            "attribute_id": "",
            "attribute_value": "",
            "value": "hello_world"
        },
        {
            "attribute_group_id": "1759fb6c",
            "attribute_group_name": "Servers (Ragnarok X: Next Generation)",
            "attribute_key": "delivery_info_2",
            "attribute_id": "98f0250f",
            "attribute_value": "Aldebaran",
            "value": ""
        }
    ]
}
  1. From the sample payload above,
  • delivery_info_1 refers to User ID and hello_world is the User ID provided by buyer.
  • delivery_info_2 refers to Servers and Aldebaran is the server chosen by buyer.

Order Status Flow

Order Status Flow

# Order Status Description
1 unpaid Buyer started the checkout process but not yet complete the payment.
2 cancelled Order is cancelled.
3 unpaid (rollback from cancelled) A cancelled order is moved back to unpaid.
4 paid Buyer has completed the checkout process and payment is done and confirmed.
5 start_delivering Delivery is ready.
6 delivering Delivery in progress.
7 awaiting_buyer_confirmation Delivery completed, pending buyer to confirm order received.
8 delivered Buyer has confirmed order received. Quantities in the order is fully delivered.
9 partial_delivered Buyer has confirmed order received. Only some quantities in the order is delivered.
10 delivering (rollback from delivered / partial_delivered) Buyer reported issue after confirmed receipt.
11 refunded Quantity is refunded due to not receiving or defect.

Error Handling

The following code snippet is a sample error response that contains an error code and message pair:

{
  "code": 40400001,
  "message": "The requested resource does not exist.",
  "warning": "",
  "request_id": "595285dc-9c43-4b9c-a1e6-0cd9aff5b084",
  "payload": {}
}

When troubleshooting the error, you can divide the error code into two components: REST API HTTP status code and error category code. See the following error code sample:

40400001

  • 404 - HTTP status code 404
  • 00001 - G2G OpenAPI error code

Status Code

The following table summarizes the HTTP response codes you may receive from the G2GOpen API.

Status Code Description
200 Everything worked as expected.
400 The request was unacceptable, often due to missing a required parameter, incorrect data type or incorrect request schema.
401 No valid API key provided. For eg:
  • API key mismatch with user_id
  • The status of the API key is denied
403 The API key doesn't have permissions to perform the request.
404 The requested resource doesn't exist.
409 The request conflicts with another request.
422 Unprocessable Entity.
429 The request cannot be completed because client have exceeded his rate limits.
500 Something went wrong on G2GOpenAPI’s end, these are rare.

Error Code

Code Descritpion
40000001 The request was unacceptable, often due to missing a required parameter.
40100001 The request is not authorized and cannot access the requested resource.
40300001 The application identified with the request is not available.
40400001 The requested resource does not exist.
40900001 The requested resource already exists.
40900002 Data constraint violation.
42200001 Validation error.
42900001 Throttle request.
50000001 The server encounters an unexpected exception while trying to process the request. Please retry the request.

API Versions

Version Descritpion
V1 This is current version of G2G OpenAPI.
V2 Coming soon. Only available to be integrated in G2G test server.

G2G Official - OpenAPI Sample

Please visit https://github.com/g2g-official/open-api-sample to download the sample postman collection as a reference to kickstart your API integration.

Product

Everything about your products.

Get Services

Get list of all available services.

query Parameters
language
string
Default: "en"
Enum: "en" "zh-CN" "id" "zh-TW"

Language

Responses

Response samples

Content type
application/json
{
  • "code": 20000001,
  • "message": "",
  • "warning": "",
  • "request_id": "595285dc-9c43-4b9c-a1e6-0cd9aff5b084",
  • "payload": {
    }
}

Get Brands

Get brands of a service.

path Parameters
service_id
required
string <uuid>
Example: 44b3148a-0dc8-4262-81d8-c762559f0d74

The unique identifier of a service.

Note: This API have a limit of 1000 results per request
query Parameters
language
string
Default: "en"
Enum: "en" "zh-CN" "id" "zh-TW"

Language

q
string
Example: q=itunes

Search brands by keyword.

after
string <uuid>
Example: after=ba683457-f9d0-4330-bea7-923ed300d2e5

Retrieve next set of brands.

Responses

Response samples

Content type
application/json
{
  • "code": 20000001,
  • "message": "",
  • "warning": "",
  • "request_id": "595285dc-9c43-4b9c-a1e6-0cd9aff5b084",
  • "payload": {
    }
}

Get Products

Get products of a brand.

query Parameters
category_id
string <uuid>
Example: category_id=f6fc99db-96d2-4158-a29f-663d9a2f6199

The unique identifier of a category.

service_id
string <uuid>
Example: service_id=44b3148a-0dc8-4262-81d8-c762559f0d74

The unique identifier of a service. Required when category_id is not provided

brand_id
string <uuid>
Example: brand_id=8c42b2d4-6d2c-4188-931a-240d2f94183f

The unique identifier of a brand. Required when service_id is provided

q
string
Example: q=itunes

Search products by brand keyword.

Responses

Response samples

Content type
application/json
{
  • "code": 20000001,
  • "message": "",
  • "warning": "",
  • "request_id": "5cd2b212-868f-4d0a-b05f-37e93a37529b",
  • "payload": {
    }
}

Get Attributes

Get attributes of a product.

path Parameters
product_id
required
string <uuid>
Example: 4a610301-4e3a-4cc7-b242-35ebc1a521a7

The unique identifier of a product.

Responses

Response samples

Content type
application/json
{
  • "request_id": "e48919cd-12be-4005-ba09-fe4004f08925",
  • "code": 20000001,
  • "message": "",
  • "warning": "",
  • "payload": {
    }
}

Offer

Everything about your offers.

Create Offer

Create a new offer.

Request Body schema: application/json
product_id
required
string <uuid>

The unique identifier of the product.

title
string

The title of an offer. Not applicable for Giftcard

description
string

Description of an offer.Not applicable for Giftcard

min_qty
required
integer >= 1

Minimum purchase quantity.

api_qty
required
int >= 0

The quantity of stock to sell in G2G via OpenAPI.

low_stock_alert_qty
required
int >= 0

When reach low_stock_alert_qty, will receive offer.low_stock webhook