receipt

receipt method of REST API is used to send the data about a user's game purchases. If the user has never logged the game in before, the new profile will be created for the user in Game of Whales.

Game of Whales makes verification of purchases received through the method. It supports verification of purchases from Apple App Store, Google Play and Samsung Apps store. The purchases from other stores will have undefined verify state.
In order to send the data about purchases without verification on Game of Whales side, you should use purchase method.

POST https://api.gameofwhales.com:8488/receipt

version 2.2.0
version 2.1.0
version 2.0.0
version 1.0.0

Request argument	Required or optional	Type	Description
game	required	string	Game key.
user	required	string	User’s ID. Any string can be used, but it should be unique for each user.
common	required	object	Common information about the user. The object includes the following parameters:
{
ip	optional	string	User's IP. It's used to define country, timezone, timezone offset, weather. If the argument is not set, "country" argument should be defined.
country	optional	string	Code of the user's country. It's required if "ip" parameter is not defined. If "ip" is set, "country" argument will be ignored. The list of supporting countries is here.
locale	required	string	User's device's locale defined by RFC 1766. It's used to select the language of push notifications.
platform	required	enum	User's device's platform. Allowed values are "android", "ios", "macosx", "uwp", "web".
store	required	enum	Used store. Allowed values are "AmazonStore", "AppleAppStore", "Facebook", "GooglePlay", "HuaweiStore", "Kongregate", "MacAppStore", "Odnoklassniki", "SamsungApps", "SFRPixtel", "VK", "WindowsStore", "XiaomiStore", "Other".
version	required	string	User's application version.
expId	optional	string	ID of A/B testing experiment. Should be sent as a confirmation of the user's participation in the experiment.
}
event	required	object	Additional information about the event. Should contain the following arguments:
{
currency	required	string	A local currency code (USD, EUR, etc).
price	required	number	A purchase's price in local currency multiplied by 100. Should be equal or more than 0.01
receipt	required	string	A receipt in UnityPurchasing format.
transactionId	required	string	A purchase's transaction ID.
at	optional	timestamp	The date of the event. If the argument isn't defined, the current date will be used.
}

A template for a request using cURL on the command line:

curl -XPOST $URL -H 'Accept-Version: 2.0.0' -H 'Content-Type: application/json' -d @- << EOF 
$REQUEST_JSON
EOF

An example values:

URL = api.gameofwhales.com:8488/receipt

REQUEST_JSON = {"game": "$YOUR_GAME_KEY", "user": "3A15982E-C4CB-0000-0000-D88861BA0C49", "common": {"ip": "91.232.111.204", "locale": "en_EN", "platform": "ios", "store": "AppleAppStore", "version": "1.0.0", "expId": "5d2effe09236b00e38e34c3b"},"event": {"receipt":"{\"Store\":\"AppleAppStore\",\"TransactionID\":\"1000000357435566\",\"Payload\":\"MIIT3QYJKoZIhvcNAQcCoIITzjCCE8oCAQExCzAJBgUrDgMCGgUAMIIDfgYJKoZIhvcNAQcBoIIDbwSCA2sxggNnMAoCAQgCAQEEAhYAMAoCARQCAQEEAgwAMAsCAQECAQEEAwIBADALAgELAgEBBAMCAQAwCwIBDgIBAQQDAgFqMAsCAQ8CAQEEAwI ... 3Ud4Twvz0zv1vYe+lgxHOM5K1bMF2vxpSJRAGuOkHNxudzMlHqhZ+U0D75zFdMQS6Oxt4HPfIyiTRlcOju+uk74TbqksdHPg3ngWn+havxTIn5EjY0pMCfRpy2ZDmctQK8rQgCXKOtlajA==\"}", "transactionId":"1000000357435566", "currency":"USD", "price":105}}

An actual request with the example values:

curl -XPOST 'api.gameofwhales.com:8488/receipt' -H 'Accept-Version: 2.0.0' -H 'Content-Type: application/json' -H 'Content-Type: application/json' -d @- << EOF
{"game": "$YOUR_GAME_KEY", "user": "3A15982E-C4CB-0000-0000-D88861BA0C49", "common": {"ip": "91.232.111.204", "locale": "en_EN", "platform": "ios", "store": "AppleAppStore", "version": "1.0.0", "expId": "5d2effe09236b00e38e34c3b"},"event": {"receipt":"{\"Store\":\"AppleAppStore\",\"TransactionID\":\"1000000357435566\",\"Payload\":\"MIIT3QYJKoZIhvcNAQcCoIITzjCCE8oCAQExCzAJBgUrDgMCGgUAMIIDfgYJKoZIhvcNAQcBoIIDbwSCA2sxggNnMAoCAQgCAQEEAhYAMAoCARQCAQEEAgwAMAsCAQECAQEEAwIBADALAgELAgEBBAMCAQAwCwIBDgIBAQQDAgFqMAsCAQ8CAQEEAwI ... 3Ud4Twvz0zv1vYe+lgxHOM5K1bMF2vxpSJRAGuOkHNxudzMlHqhZ+U0D75zFdMQS6Oxt4HPfIyiTRlcOju+uk74TbqksdHPg3ngWn+havxTIn5EjY0pMCfRpy2ZDmctQK8rQgCXKOtlajA==\"}", "transactionId":"1000000357435566", "currency":"USD", "price":105}}
EOF

RESPONSE ARGUMENTS

Response argument	Required or optional	Type	Description
receipts	optional	object[]	The information about purchases. It includes the following properties:
[
{
transaction	required	string	A purchase's transaction ID.
verifyState	required	string	The result of purchase validation. The value can be: "legal" - a purchase is legal. "illegal" - a purchase is a cheater's. "undefined" - the system couldn't verify a purchase. "bypass" - the system doesn't verify a purchase. "double" - the system has had purchase with the same transaction ID.
}
]
properties	required	object	User's properties. The object includes the following properties:
{
user	required	string	User’s ID.
group	required	string	User's group. The property is used for analyzing of push and special offer campaigns.
revenue	required	number	The current amount of the user's purchases.
custom property	optional	string, boolean, object	Additional custom properties. They are returned only if they are defined on Game of Whales side.
}
experiment	optional	object	The data about A/B testing experiment in which the user was included. The object isn't returned if the user doesn't take part in any experiment.
{
id	required	string	ID of the experiment.
key	required	string	String-key of the experiment.
groupKey	required	string	Experiment's group in which the user was included.
payload	optional	string	Payload for the experiment's group.
signature	required	string	Encrypted data about the experiment. It can be used to verify the experiment on the game server side.
}
serverTime	required	timestamp	The current time of Game of Whales server.

An example of a response:

{
    "receipts": [
        {
            "transaction": "1000000357435566",
            "verifyState": "legal"
        }
    ],
    "properties": {
        "user": "3A15982E-C4CB-0000-0000-D88861BA0C49",
        "group": "b",
        "revenue": 3
    },
    "experiment":
    {
        "id": "5d2effe09236b00e38e34c3b",
        "key": "exp_cr",
        "groupKey": "B",
        "payload": "{\"btnColor\": \"grean\", \"btnSize\": \"big\"}",
        "signature": "f6c66c70f459b13..."
    },
    "serverTime": 1545381287159
}

version 1.0.0

REQUEST ARGUMENTS

Arguments are in JSON format with the Content-Type application/json.

Request argument	Required or optional	Type	Description
game	required	string	Game key.
user	required	string	User’s ID. Any string can be used, but it should be unique for each user.
common	required	object	Common information about the user. The object includes the following parameters:
{
ip	optional	string	User's IP. It's used to define country, timezone, timezone offset, weather. If the argument is not set, "country" argument should be defined.
country	optional	string	Code of the user's country. It's required if "ip" parameter is not defined. If "ip" is set, "country" argument will be ignored. The list of supporting countries is here.
locale	required	string	User's device's locale defined by RFC 1766. It's used to select the language of push notifications.
platform	required	enum	User's device's platform. Allowed values are "android", "ios", "macosx", "uwp", "web".
store	required	enum	Used store. Allowed values are "AmazonStore", "AppleAppStore", "Facebook", "GooglePlay", "HuaweiStore", "Kongregate", "MacAppStore", "Odnoklassniki", "SamsungApps", "SFRPixtel", "VK", "WindowsStore", "XiaomiStore", "Other".
version	required	string	User's application version.
}
event	required	object	Additional information about the event. Should contain the following arguments:
{
currency	required	string	A local currency code (USD, EUR, etc).
price	required	number	A purchase's price in local currency multiplied by 100. Should be equal or more than 0.01
receipt	required	string	A receipt in UnityPurchasing format.
transactionId	required	string	A purchase's transaction ID.
at	optional	timestamp	The date of the event. If the argument isn't defined, the current date will be used.
}

A template for a request using cURL on the command line:

curl -XPOST $URL -H 'Accept-Version: 1.0.0' -H 'Content-Type: application/json' -d @- << EOF 
$REQUEST_JSON
EOF

An example values:

URL = api.gameofwhales.com:8488/receipt

REQUEST_JSON = {"game": "$YOUR_GAME_KEY", "user": "3A15982E-C4CB-0000-0000-D88861BA0C49", "common": {"ip": "91.232.111.204", "locale": "en_EN", "platform": "ios", "store": "AppleAppStore", "version": "1.0.0"},"event": {"receipt":"{\"Store\":\"AppleAppStore\",\"TransactionID\":\"1000000357435566\",\"Payload\":\"MIIT3QYJKoZIhvcNAQcCoIITzjCCE8oCAQExCzAJBgUrDgMCGgUAMIIDfgYJKoZIhvcNAQcBoIIDbwSCA2sxggNnMAoCAQgCAQEEAhYAMAoCARQCAQEEAgwAMAsCAQECAQEEAwIBADALAgELAgEBBAMCAQAwCwIBDgIBAQQDAgFqMAsCAQ8CAQEEAwI ... 3Ud4Twvz0zv1vYe+lgxHOM5K1bMF2vxpSJRAGuOkHNxudzMlHqhZ+U0D75zFdMQS6Oxt4HPfIyiTRlcOju+uk74TbqksdHPg3ngWn+havxTIn5EjY0pMCfRpy2ZDmctQK8rQgCXKOtlajA==\"}", "transactionId":"1000000357435566", "currency":"USD", "price":105}}

An actual request with the example values:

curl -XPOST 'api.gameofwhales.com:8488/receipt' -H 'Accept-Version: 1.0.0' -H 'Content-Type: application/json' -H 'Content-Type: application/json' -d @- << EOF
{"game": "$YOUR_GAME_KEY", "user": "3A15982E-C4CB-0000-0000-D88861BA0C49", "common": {"ip": "91.232.111.204", "locale": "en_EN", "platform": "ios", "store": "AppleAppStore", "version": "1.0.0"},"event": {"receipt":"{\"Store\":\"AppleAppStore\",\"TransactionID\":\"1000000357435566\",\"Payload\":\"MIIT3QYJKoZIhvcNAQcCoIITzjCCE8oCAQExCzAJBgUrDgMCGgUAMIIDfgYJKoZIhvcNAQcBoIIDbwSCA2sxggNnMAoCAQgCAQEEAhYAMAoCARQCAQEEAgwAMAsCAQECAQEEAwIBADALAgELAgEBBAMCAQAwCwIBDgIBAQQDAgFqMAsCAQ8CAQEEAwI ... 3Ud4Twvz0zv1vYe+lgxHOM5K1bMF2vxpSJRAGuOkHNxudzMlHqhZ+U0D75zFdMQS6Oxt4HPfIyiTRlcOju+uk74TbqksdHPg3ngWn+havxTIn5EjY0pMCfRpy2ZDmctQK8rQgCXKOtlajA==\"}", "transactionId":"1000000357435566", "currency":"USD", "price":105}}
EOF

RESPONSE ARGUMENTS

Response argument	Required or optional	Type	Description
receipts	optional	object[]	The information about purchases. It includes the following properties:
[
{
transaction	required	string	A purchase's transaction ID.
verifyState	required	string	The result of purchase validation. The value can be: "legal" - a purchase is legal. "illegal" - a purchase is a cheater's. "undefined" - the system couldn't verify a purchase. "bypass" - the system doesn't verify a purchase. "double" - the system has had purchase with the same transaction ID.
}
]
properties	required	object	User's properties. The object includes the following properties:
{
user	required	string	User’s ID.
group	required	string	User's group. The property is used for analyzing of push and special offer campaigns.
revenue	required	number	The current amount of the user's purchases.
custom property	optional	string, boolean, object	Additional custom properties. They are returned only if they are defined on Game of Whales side.
}
serverTime	required	timestamp	The current time of Game of Whales server.

An example of a response:

{
    "receipts": [
        {
            "transaction": "1000000357435566",
            "verifyState": "legal"
        }
    ],
    "properties": {
        "user": "3A15982E-C4CB-0000-0000-D88861BA0C49",
        "group": "b",
        "revenue": 3
    },
    "serverTime": 1545381287159
}