How to Integrate a Game

How to Integrate a Game

  • Quick Integration
  • Complete Integration
  • The Platform
  • Help

›3. Payments Guide

Complete Guide Overview

  • Complete Guide Overview

1. Panel Guide

  • 1.0. Panel Access
  • 1.1. Create a new game
  • 1.2. Game Configuration
  • 1.3. Shop

    • Shop introduction
    • 1.3.1. Shop Wizard
    • 1.3.2. Shop Offers
    • 1.3.3. Shop Coupons
    • 1.3.4. Shop Themes
    • 1.3.5. Test shop
  • 1.4. Multi-Language
  • 1.5. Releases
  • 1.6. DLCs
  • 1.7. Store Content
  • 1.8. Content
  • 1.9. WebSection
  • 1.10 Purchase Report

    • 1.10.1. Dashboard
    • 1.10.2 Client & App
    • 1.10.3 Gamer Level
    • 1.10.4 Region & Country
    • 1.10.5 Purchase Notifications
    • 1.10.6 Sales Wallet
    • 1.10.7 Player Summary

    1.11 Stats Report

    • 1.11.1. Leads
    • 1.11.2. Retention
    • 1.11.4. Login
    • 1.11.4. Payment
    • 1.11.5. Wishlist

2. Login Guide

  • 2.0. Login overview
  • 2.1. Login with Unity
  • 2.2. Login with C#
  • 2.3. Login with C++/Unreal
  • 2.4. Login with HTTP
  • 2.5. Login with Web Service Definition Language (WSDL)

3. Payments Guide

  • 3.0. First of All
  • 3.1. Payments Integration

4. API Guide

    Releases API

    • Releases Workflow
    • C# example

Glossary

  • Glossary

3.1. Payments Integration

This section explains how to launch a game's shop and how to notify payment events within the game. A game shop is always located at the game's URL shop folder and will look something like this: "https://en.idcgames.com/game_name/shop".

At the Shop section of the Panel you can configure the items you want to sell so you can identify them at the game's backend. Check out the documentation for configuring items at 1. Panel Guide > 1.3. Shop section. There you will be able to configure items, articles, offers, promo codes, apart from the proper shop (tabs, target users, themes, etc).

Launching the shop

There are 3 ways of launching a game's shop:

  • 1. Launch the shop at the IDC Games platform (not recommended).
  • 2. Launch the shop at the game's browser or at an external browser.
  • 3. Launch the shop at the IDC Games launcher.

1. Launching the shop at the IDC Games platform

With this option, the user is directed to the game's shop URL at the platform (web) to make a purchase, where he has to log in before making the purchase. The IDC Games platform will then make an http request to the developer's server, where the developer has to define the callback with the details of the transaction and send the answer to IDC Games. This option is not recommended because the user is not always loged in when making a purchase attempt, and having to log in can disencourage him from completing the process.

2. Launching the shop at the game's browser or at an external browser

The shop is launched with the following code, where "game" is the game's ID:

https://admin.idcgames.com/shop/frontend/index?game=1118&useridc=4583837&tokengame=0664f0c099d3e0a45c4662a189632c03
$md5data = ("$game_secret$useridc$game");
tokengame=md5($md5data);
$token = md5($md5data);
$shopUrl = "https://admin.idcgames.com/shop/frontend/index?";
$urlparams = "game=$game&useridc=$useridc&tokengame=$token";

The developer has to define the callback at the Panel.

Parameters of the answer

Upon a purchase completion, the game will receive callback to the endpoint provided with a POST request wiht a Json inside that will look like this:

{
"action":"idcpayment",
"useridc":"154777",
"gamer_ip":"193.219.96.100",
"transactionid":"WOT_60266b2c66f29",
"sandbox":"1",
"refund":"0",
"country":"ES",
"currency":"EUR",
"amount_total":"10",
"amount_net":"8.33",
"amount_vat":"1.67",
"provider":"Paypal",
"bought_data":[
    {
        "game_item_id":"10coins",
        "game_article_id":"",
        "idc_article_token":"SntXmca2-gFaL-TvGe-Kw0WW6zDpJH",
        "number_of_items":1,
        "price":10,
        "price_net":8.333333333333334,
        "currency":"EUR",
        "article_count":1,
        "has_offer":0,
        "offer_discount":0,
        "has_coupon":0,
        "coupon_discount":0
    },
    {
        "game_item_id":"10coins",
        "game_article_id":"",
        "idc_article_token":"ccum4EhQ-MwCU-7Aie-eyeyoDTxKKr1",
        "number_of_items":1,
        "price":0,
        "price_net":0,
        "currency":"EUR",
        "article_count":1,
        "has_offer":0,
        "offer_discount":0,
        "has_coupon":0,
        "coupon_discount":0
    }
]}
PARAMETER NAME DESCRIPTION TYPE
action Type of event triggered. For purchase events the value is "idcpayment" String
useridc ID of the user that triggers the event within the IDC Games platform String
gamer_ip IP address of the user that triggers the event Number
transactionid Transaction or purchase identifier Number
sandbox Values "0" for false and "1" for true Boolean
refund Values "0" for false and "1" for true Boolean
country Country ISO 3166-1 alpha-2 code String
currency Currency ISO 4217 alphabetic code (EUR, USD, GBP, etc.) String
amount_total Total price of the transaction, the actual price the end user will pay, the sum of all the variables "price" of the items purchased ("bought_items") in the transaction Number
amount_net Total net price of the transaction without VAT, the sum of all the variables "price_net" of the items purchased in the transaction Number
amount_vat Total VAT price of the transaction Number
provider Payment method selected by the user, values "Paypal", "Paysafecard", "Skrill", etc String
bought_data Array for each and every item purchased witht the details of the transaction array
Variables for the bought_data (purchased items) array:

PARAMETER NAME DESCRIPTION TYPE
game_item_id Game item identifier, set by developer at the platform section Shop > Items String
game_article_id Game article identifier, set by developer at the platform section Shop > Articles Number
idc_article_token Article token String
number_of_items Number of game items purchased Number
price End user price of the transaction, the actual price the end user will pay for current item Number
price_net Net price of the transaction without VAT Number
currency ISO 4217 currency alphabetic currency code (EUR, USD, GBP, etc.) String
article_count Number of articles within the transaction Number
has_offer Values "0" for false and "1" for true Boolean
offer_discount Values "0" for false and "1" for true Boolean
has_coupon Values "0" for false and "1" for true Boolean
coupon_discount Values "0" for false and "1" for true Boolean

Example of a callback request:

Developers can test the callback with this example of a PostMan request to a callback URL:

        {
            "name": "Sabotaj",
            "request": {
                "method": "POST",
                "header": [],
                "body": {
                    "mode": "urlencoded",
                    "urlencoded": [
                        {
                            "key": "action",
                            "value": "idcpayment",
                            "type": "text"
                        },
                        {
                            "key": "amount_net",
                            "value": "0",
                            "type": "text"
                        },
                        {
                            "key": "amount_total",
                            "value": "0",
                            "type": "text"
                        },
                        {
                            "key": "amount_vat",
                            "value": "0",
                            "type": "text"
                        },
                        {
                            "key": "bought_data",
                            "value": "[{\"game_item_id\":\"2450SG\",\"game_article_id\":\"\",\"idc_article_token\":\"WHvwlUYP-CHmH-5PTQ-ArvE6nquCvg6\",\"number_of_items\":1,\"price\":0,\"price_net\":0,\"currency\":\"EUR\",\"article_count\":1,\"has_offer\":0,\"offer_discount\":0,\"has_coupon\":1,\"coupon_discount\":1.4}]",
                            "type": "text"
                        },
                        {
                            "key": "country",
                            "value": "FR",
                            "type": "text"
                        },
                        {
                            "key": "currency",
                            "value": "EUR",
                            "type": "text"
                        },
                        {
                            "key": "gamer_ip",
                            "value": "88.8.185.38",
                            "type": "text"
                        },
                        {
                            "key": "provider",
                            "value": "IDC Games",
                            "type": "text"
                        },
                        {
                            "key": "refund",
                            "value": "0",
                            "type": "text"
                        },
                        {
                            "key": "sandbox",
                            "value": "0",
                            "type": "text"
                        },
                        {
                            "key": "transactionid",
                            "value": "WOT_6038ab01f2e96",
                            "type": "text"
                        },
                        {
                            "key": "useridc",
                            "value": "624909",
                            "type": "text"
                        }
                    ]
                },
                "url": {
                    "raw": "https://pay.sabotajoyun.com/idc-ipn",
                    "protocol": "https",
                    "host": [
                        "pay",
                        "sabotajoyun",
                        "com"
                    ],
                    "path": [
                        "idc-ipn"
                    ]
                }
            },
            "response": []
        }
    ]
}

3. Launching the shop at the IDC Games launcher

These are the necessary steps in order to use IDCLauncher Shop. IDC Games Launcher must be executed if you want to use these functions.

  • 1.- Create callback function (see OnPurchaseNotify function code). This is the function that will be called every time that a new notification is received.
  • 2.- Activate notifications (see activatePurchaseNotifications function code). Before opening the shop notifications must be configured, since all the purchase notifications will be received by the callback configured there. Once you activate notifications you will receive all pending purchase notifications for the user. Every purchased element must be added to the user inventory. Once items are added to the user inventory, the transaction must be closed to change it's status from pending to closed.
  • 3. Open shop (see openShopPurchase function code). This function will open IDCGames Launcher shop. If the user makes a successfull transaction, a new purchase notification will be received.
  • 4. Close transaction (see closeShopTransaction function Code). This function is used to notify idcgames that an item has been successfully assigned to a user. Once that an item has been assigned to the user, transaction must be close to avoid receiving repeated purchase notifications.
[DllImport("idclib_64.dll", CharSet = CharSet.Ansi)]
        private static extern int activatePurchaseNotifications(string gameId, string gameSecret, int type, NotifyCallBack callBack);


        [DllImport("idclib_64.dll", CharSet = CharSet.Unicode)]
        private static extern int shopPurchase(string transactionid, string extra, int userlevel);


        [DllImport("idclib_64.dll", CharSet = CharSet.Ansi)]
        private static extern int closePurchaseTransaction(string userId, string transactionId, string idcPaymentId);

        public delegate void PurchaseNotifyCallBack(IntPtr data, int len);
        private void activatePurchaseNotifications(string gameId, string secret)
        {
            //gameId            - Id for the game in IDCGames portal. Provided by IDCGames
            //gameSecret        - Keyword for game in IDCGames portal. Provided by IDCGames
            //OnPurchaseNotify   - name of the function that will be executed when a notification is received. In order to use it you need to declare a PurchaseNotifyCallBack delegate
            int iRet = activatePurchaseNotifications(tGameId.Text, tSecret.Text, OnPurchaseNotify);
            if (iRet == 0)
            {
                bActivateNotifications.Enabled = false;
            }

        }

        //funcion called whenever a new purchase notification is received
        //userId: User Id in IdcPlatform. Received in IDCLogin
        //transactionID - Game Id for the transaction. Generated by game when transaction is created
        //idcPyamentId: Payment Id assigned by IDCGames to the transaction.
        //data: Json with purchases data information
        //len: length of the json string
        private void OnPurchaseNotify(string userId, string transactionId, string idcPaymentId, IntPtr data, int len)
        {
            if (this.InvokeRequired)
            {
                this.Invoke(new Action(() => this.OnPurchaseNotify(userId, transactionId, idcPaymentId, data, len)));
                return;
            }

            if (len > 0)
            {
                var arr = new byte[len];
                Marshal.Copy(data, arr, 0, len);
                var msg = Encoding.Unicode.GetString(arr).TrimEnd(new Char[] { '\0' });
                tShopTransactionId.Text = transactionId;
                tPaymentId.Text = idcPaymentId;
                tReceivedNotifications.AppendText(DateTime.Now.ToShortDateString() + " " + DateTime.Now.ToLongTimeString() + Environment.NewLine + "Transaction ID: " + transactionId +Environment.NewLine + "Payment ID: " + idcPaymentId + Environment.NewLine + "Purchase data:" + msg + Environment.NewLine + Environment.NewLine);
            }
        }

        private void openShopPurchase(string transactionid, string extra, int userLevel)
        {
            //transactionID - Game Id for the transaction. Generated by game when transaction is requested and received in payment notification
            //extra         - Json with information about transaction, for example, selected items. Check format in documentation.
            //userlevel     - Used if game has different shops for different user levels configured
            int ret = shopPurchase(tShopTransactionId.Text, extra,userLevel);
            if (ret != 0)
            {
                ShowError("Error creating shop transaction");
            }
        }

        private void closeShopTransaction(string userId, string transactionId, string idcPaymentId)
        {
            //userId        - User Id in IdcPlatform. Received in IDCLogin
            //transactionID - Game Id for the transaction. Generated by game when transaction is created and received in payment notification
            //idcPaymentID  - Payment Id assigned by IDCGames to the transaction. Received in payment notification
            int ret = closePurchaseTransaction(userId, transactionId, idcPaymentId);
            if (ret == 0)
            {
                MessageBox.Show("Transaction closed successfully");
            }
            else
            {
                ShowError("Error closing transaction");
            }
        }

Configure the notification of payment events:

There are 2 ways of receiving payment notifications:

  • DLL event, which invokes a function where the items of the purchase are notified. If a purchase takes place at the web and the game is not launched at the time, the DLL event will receive the notification upon the next launching of the game.
  • Callback URL (optional). Add a Callback URL at the panel which contains within all the the information related to a purchase.
← 3.0. First of AllReleases Workflow →
  • Launching the shop
  • 1. Launching the shop at the IDC Games platform
  • 2. Launching the shop at the game's browser or at an external browser
  • 3. Launching the shop at the IDC Games launcher
How to Integrate a Game
All Documentation
How to integrate a game at idcgames.comComing soon
Facebook Open Source
Copyright © 2023 IDC/Games S.L.