Purchase Rewards

The purchase reward API is mainly responsible for rewarding your player score and points through Purchase Reward program based on the actual paid amount by your players.

Gameball allows you to reward your players with score, points, or both based on the configured settings on Gameball Purchase Reward program. To learn more about puchase rewards, check this article at our Help Center.

Reward can be sent along with Events and Redemption using Actions Composite API endpoint.

The following APIs use Hashing Function SHA1, check how hashing is done below.

Reward Points

POST /integrations/transaction/reward

Access reward points API to reward your players for each unit currency they actually paid for your product or service.

Headers

NameTypeDescription

APIKey

string

Client API key

Request Body

NameTypeDescription

merchant

object

Merchant object as described in Object reference section

playerUniqueId

string

Player unique identifier used to uniquely identify the player on Gameball.

amount

number

Monetary value that the player will be rewarded for based on the Purchase Reward program configurations. (Amount must be positive).

transactionId

string

Unique transaction ID which identifies the underlying transaction in your system, e.g. order number, invoice number. It will be used for reversing any reward or redemption transaction on Gameball.

transactionTime

string

Time of transaction in your system in UTC, e.g. order datetime, invoice datetime. Note: transactionTime is automatically handled when using server-side SDKs.

hash

string

Hashed body with SHA1 algorithm. As described in Hashing Transaction Messages section. Note: hashing is automatically handled when using server-side SDKs.

playerAttributes

object

An object containing all of the attributes of the player. Player object is described in Object Reference section.

{
    "playerUniqueId": "player123",
    "playerAttributes": null,
    "gameballTransactionId": 17178,
    "amount": "99.98",
    "transactionId": "tra_123456789",
    "transactionTime": "2019-09-19T16:14:09.895Z"
}

Response Description

Attribute

Description

playerUniqueId

Player unique identifier used to uniquely identify the player on Gameball.

playerAttributes

An object containing all of the attributes of the player. Player Object is described in Object Reference section.

gameballTransactionId

Transaction ID on Gameball system.

amount

Monetary value that the player will be rewarded for based on the Purchase Reward. (Amount must be positive)

transactionId

Unique transaction ID which identifies the underlying transaction in your system, e.g. order number, invoice number. It will be used for reversing any reward or redemption transaction on Gameball.

transactionTime

Time of transaction in your system in UTC, e.g. order datetime, invoice datetime. Note:transactionTime is automatically handled when using server-side SDKs.

points

The number of points rewarded to the player for the specified amount

In case the player doesn't exist on Gameball before sending the Purchase Reward API call, the player will be created automatically on Gameball and granted the points.

Usage Examples

Example One

The example shown is a request sent to Gameball when you want to reward a player ofplayerUniqueId"player123" with points equivalent to amount of 99.98. The points to be granted will be according to your points configurations on Purchase Reward program.

curl -X POST -H 'apiKey: 807b041b7d35425988e354e1f6bce186' -d '{
   "playerUniqueId":"player123",
   "amount":99.98,
   "transactionId":"tra_123456789",
   "transactionTime":"2019-09-19T16:14:09.895Z",
   "hash":"f3437e2919ab9f853c7ccde92f4f2b9a6def42db"
  }' -v -i 'https://api.gameball.co/api/v2.0/integrations/transaction/reward'

Example Two

The example shown is a request sent to Gameball when you want to reward a player ofplayerUniqueId"player456" with points equivalent to amount of 2500.

In addition to reward information, playerAttributes object is sent to Gameball to create or update player details in our system with any custom attributes.

curl -X POST -H 'apiKey: 807b041b7d35425988e354e1f6bce186' -d '{
   "playerUniqueId":"player456",
   "amount":2500,
   "transactionId":"tra_123456789",
   "playerAttributes":{
      "displayName":"Tyrion Lannister",
      "firstName":"Tyrion",
      "lastName":"Lannister",
      "email":"tyrion@example.com",
      "gender":"M",
      "dateOfBirth":"1978-01-11T00:00:00.000Z",
      "joinDate":"2019-09-19T21:06:29.158Z",
      "custom": {
            "location":"Miami",
            "graduationDate":"2018-07-04T21:06:29.158Z",
            "isMarried":false
        }
   },
   "transactionTime":"2019-09-19T16:14:09.895Z",
   "hash":"f3437e2919ab9f853c7ccde92f4f2b9a6def42db"
  }' -v -i 'https://api.gameball.co/api/v2.0/integrations/transaction/reward'

Last updated