Gifting

With in-game gifting, you can enable players to purchase in-game items as gifts for their friends & family who may enjoy playing a new game. Recipients of a gift will get an email with gift information and gift givers will get a receipt. They can also opt to hide their identity to send the gift anonymously. In either case, enabling gifting can drive both re-engagement and incremental revenue.

This feature has various integration options and allows game projects to sell the following in-game items as gifts:

  • Virtual currency packages
  • Virtual items
  • Game activation keys

The option is only available for projects that have disabled Xsolla-side storage of user-data. Go to your Publisher Account to configure and manage user-data storage settings.

Integration Guide

The following integration options are available depending on the modules enabled for your project:

Pay2Play Module

To enable the feature:

  1. Set up the Pay2Play module.
  2. Contact your account manager to enable the feature.

Virtual Items, Virtual Currency, or Payment Wall Modules

To enable the feature:

  1. Set up the Virtual Items, Virtual Currency, or Payment Wall module(s), respectively.
  2. Implement the API method to send the friend list to Xsolla, or add an object with friend data to the token request.
  3. Implement the handling of the webhook confirming a successful payment and containing the gift data.
  4. Contact your account manager to enable the feature.

Setting up the Module

To enable the feature, you must have the Virtual Items, Virtual Currency, or Payment Wall module(s) set up and turned on.

Sending the Friend List in the Token Request

If necessary, you can add an array with the user’s friend list to the request for token. If the array only contains one friend, they will be automatically identified as the gift recipient. The token request may not contain more than 100 friends. You can also add an object with the gift data to the request.

Request example

"purchase":{

   "virtual_currency":{

       "quantity":100

   },

   "description":{

       "value":"Test Purchase"

   },

   "gift":{

       "giver_id":"John Smith",

       "message":"GG WP",

       "hide_giver_from_receiver" : true,

       "friends": [

       {

        "id": "123",

        "name": "captain",

        "email": "captain@ship.com"

       }]

   }

}

Sending the Friend List via the API

In this case, Xsolla sends a request for the friend list to the project’s webhook URL, which is configured in project settings.

Creating a signature

To create a signature:

  1. Order the parameters received from the Xsolla server in alphabetic order.
  2. Concatenate the parameter values and the project’s secret key, as generated in project settings.
  3. Hash the resulting string using the SHA1 algorithm.
  4. Send the result in the 'sign' parameter.

When processing the API request, make sure that the received signature matches the one sent in the 'sign' parameter.

Getting the List of Friends

Request example

$ curl -v 'https://your.webhook.url?notification_type=friends_list&user=user_id&query=frien&offset=10&limit=20&sign=12dfg3f5gdsf4g5s6dfg2sdg1' \
-X GET \
-u merchant_id:merchant_api_key

Response example

[
  {
  "friends": [
      {
        "id": "1",
        "name": "John Carter",
        "email": "carter@xsolla.com",
        "image_url": "https://partner/link/doctor.jpg"
      },
      {
        "id": "2",
        "name": "John Smith",
        "email": "smith@xsolla.com",
        "image_url": "https://partner/link/cook.jpg"
      }
    ],
  "total": 10
  }
]

Setting up Webhooks

Make sure to update the handling of the Payment webhook, which will now pass the new gift.purchase object in its JSON.

Request example

$curl -v 'https://your.hostname/your/uri' \
-X POST \
-d '{
    "notification_type":"payment",
    "purchase":{
        "virtual_currency":{
            "name":"Coins",
            "sku":"test_package1",
            "quantity":10,
            "currency":"USD",
            "amount":100
        },
        "subscription":{
            "plan_id": "b5dac9c8",
            "subscription_id": "10",
            "product_id": "Demo Product",
            "date_create": "2014-09-22T19:25:25+04:00",
            "date_next_charge": "2014-10-22T19:25:25+04:00",
            "currency": "USD",
            "amount": 9.99
        },
        "checkout":{
            "currency":"USD",
            "amount":50
        },
        "virtual_items":{
            "items":[
                {
                    "sku": "test_item1",
                    "amount":1
                }
            ],
            "currency":"USD",
            "amount":50
        },
        "gift":{
             "giver_ID":"John Smith",
             "receiver_ID":"Ivan Ivanov",
             "receiver_email":"example@example.com",
             "message":"GG WP",
             "hide_giver_from_receiver": true
        },
        "total":{
            "currency":"USD",
            "amount":200
        },
        "promotions":[{
            "technical_name":"Demo Promotion",
            "id":"853"
        }],
        "coupon":{
             "coupon_code":"ICvj45S4FUOyy",
             "campaign_code":"1507"
        }
    },
    "user": {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": "1234567",
        "name": "Xsolla User",
        "country": "US"
    },
    "transaction":{
        "id":1,
        "external_id":1,
        "payment_date":"2014-09-24T20:38:16+04:00",
        "payment_method":1,
        "dry_run":1,
        "agreement":1
    },
    "payment_details":{
        "payment":{
            "currency":"USD",
            "amount":230
        },
        "vat": {
            "currency": "USD",
            "amount": 0
        },
        "payout_currency_rate": 1,
        "payout":{
            "currency":"USD",
            "amount":200
        },
        "xsolla_fee":{
            "currency":"USD",
            "amount":10
        },
        "payment_method_fee":{
            "currency":"USD",
            "amount":20
        }
    },
    "custom_parameters":{
        "parameter1":"value1",
        "parameter2":"value2"
    }
}'