How It Works

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

Who Can Use It

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

How to Get It

To enable the feature:

1. Configure virtual currency packages, virtual items, game keys packages, or subscriptions.
2. Choose and implement one of the following ways to send friend list: via an API method or via token.
3. Implement the purchase.gift parameter processing in the successful purchase webhook.
4. Contact your Account Manager to complete the setup.

Send Friend List via Token

To let a giver choose the recipient from the suggested list, pass the list of the user's friends as the purchase.gift.friends parameter in the Get Token request. Show the received list in your app. If the list includes only one user, this user is automatically defined as a gift recipient.

To add the information about the gifter, pass the purchase.gift.giver_id, purchase.gift.message, purchase.gift.hide_giver_from_receiver parameters in the request for getting a token.

Example of a token for virtual currency as a gift to the user:

"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"
       }]
   }
}

Example of a token for a subscription as a gift to the user:

"purchase": {
  "gift": {
    "giver_id": "John Smith",
    "message": "GG WP",
    "hide_giver_from_receiver": true,
    "friends": [
    {
      "id": "123",
      "name": "captain",
      "email": "captain@ship.com"
    }
    ]
  }
}

Pass List of Friends via API Request

Implement the API for passing the list of friends and form a signature. To form a signature:

1. Make sure that you specified Webhook URL in Publisher Account > Project settings > Webhooks.
2. Generate request signature.
3. During the API request processing, make sure that the generated signature and the signature passed in the sign parameter match.

Example of the request:

$ 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

Example of the response:

[
  {
  "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
  }
]