Gift for a Friend

How It Works

The Gift for a Friend feature lets users buy virtual currency, virtual items, or game keys for real currency and send them over as gifts to their in-game friends. Following a successful payment, the giver will get a receipt and the recipient will get an email with gift details. The giver can opt to hide their data to send the gift anonymously.

The option has various integration options and allows game projects to enable the giving of:

  • Virtual currency packages
  • Virtual items
  • Game keys

Note: The option is only available to projects that have Xsolla-side user data storage disabled.

Who Can Use It

Partners who have Buy Button integrated and the Virtual Items/Virtual Currency/Game Keys modules enabled.

How to Get It

To enable the feature:

  1. Configure virtual currency packages, virtual items and/or game keys packages.
  2. Implement the Get Friends API method and add the friends object to the request for token.
  3. Implement the handling of the successful payment webhook including the gift data.
  4. Contact your Account Manager to enable the option.

Sending Friend List via Token

If needed, you can add the array of friends of a user to the request. If the array contains one element only, that friend will be automatically considered the gift recipient. You can send a maximum of 100 friends in the request for token. You can also include the gift data in 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 Friend List via API Request

Xsolla will send a request for the list of friends to the webhook URL set for the project.

Creating a Signature

To create an electronic signature:

  1. Order the parameters received from Xsolla alphabetically.
  2. Concatenate the parameter values and the secret key (generated on the project settings page) in one string.
  3. Hash the string using the SHA1 algorithm.
  4. Send the signature in the sign parameter.

Note: When handling the API request, make sure the received signature is the same as 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
  }
]