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:
- Configure virtual currency packages, virtual items, game keys packages, or subscriptions.
- Choose and implement one of the following ways to send friend list: via an API method or via token.
- Implement the
purchase.gift
parameter processing in the successful purchase webhook. - 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:
- http
"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:
- http
"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:
- Make sure that you specified Webhook URL in Publisher Account > Project settings > Webhooks.
- Generate request signature.
- During the API request processing, make sure that the generated signature and the signature passed in the
sign
parameter match.
Example of the request:
- http
$ 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:
- http
[
{
"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
}
]
Was this article helpful?
Rate this page
Don’t want to answer
Thank you for your feedback!
Found a typo or other text error? Select the text and press Ctrl+Enter.