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 |
| 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.Unicode)]
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.