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
version 2.2.0
There are no differences from version 2.0.0
version 2.1.0
There are no differences from version 2.0.0
version 2.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. |
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 }