Подарок другу

Вы можете дать возможность пользователям приобретать пакеты виртуальной валюты, виртуальные товары или ключи доступа в качестве подарка друзьям в игре. После успешной оплаты покупателю отправляется чек, получателю - письмо с информацией о подарке. Покупатель подарка также может скрыть свои данные и отправить подарок анонимно.

Опция имеет несколько вариантов интеграции и предлагает игровым проектам следующие варианты покупок подарка:

Покупка пакета виртуальной валюты
Покупка виртуальных товаров
Покупка ключа активации игры

Опция доступна только для проектов, у которых отключено хранение данных пользователей на стороне Xsolla.

Сценарии взаимодействия

Передача списка друзей в токене

Передача списка друзей через API

Руководство по интеграции

В зависимости от модулей, которые включены для вашего проекта, доступны следующие варианты интеграции:

Модуль Pay2Play

Для подключения модуля необходимо:

Настроить модуль Pay2Play.
Связаться с аккаунт-менеджером проекта для включения опции.

Модуль виртуальной валюты, модуль виртуальных товаров или модуль реальной валюты

Для подключения опции необходимо:

Настроить модуль виртуальной валюты, виртуальных товаров или модуль реальной валюты.
Реализовать метод API для передачи списка друзей в Xsolla или добавить объект с данными о друзьях в запрос на получение токена.
Реализовать обработку оповещения об успешной оплате с добавленными данными о подарке.
Связаться с аккаунт-менеджером проекта для включения опции.

Настройка модуля

Для подключения опции необходимо запустить модуль виртуальной валюты, виртуальных товаров или модуль виртуальной валюты.

Передача списка друзей в токене

При необходимости в запрос можно добавить массив со списком друзей пользователя. Если массив содержит всего один элемент, переданный друг автоматически определяется как получатель подарка. В запросе на получение токена можно передавать не более 100 друзей. В запрос также можно включить объект с данными о подарке.

Пример запроса

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

       }]

   }

}

Передача списка друзей по запросу к API

Xsolla отправляет проекту запрос на получение списка друзей по адресу, указанному в качестве webhook URL в настройках проекта.

Формирование подписи

Процесс формирования подписи включает следующие шаги:

Параметры, переданные в запросе от сервера Xsolla, сортируются в алфавитном порядке.
Значения параметров и секретный ключ проекта (генерируется на странице настройки проекта) конкатенируются в строку.
Полученная строка хешируется с помощью SHA1 хеш-алгоритма.
Подпись передается в параметре sign.

При обработке запроса к API необходимо проверить, что полученная подпись и подпись, переданная в параметре sign, совпадают.

Получение списка друзей

Пример запроса

$ 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

Пример ответа

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

Настройка оповещений

При включении модулей виртуальной валюты и виртуальных товаров обязательным шагом является обработка оповещения Payments. При включении опции Подарок другу в JSON оповещения добавляется новый объект gift.purchase.

Пример запроса

$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"
    }
}'