Transactions

Transactions API is responsible for all the player's points transactions.

Transactions API Endpoints are used to reward a player, as well as redeem points, refund points, and also view the transactions history of a specific player.
Available Endpoints
Type
Description
Endpoint
POST
​Cashback​
/integrations/transaction/cashback
POST
​Redeem Points​
/integrations/transaction/redeem
POST
​Refund​
/integrations/transaction/refund
POST
​Hold Points​
/integrations/transaction/hold
DELETE
​Reverse Hold​
/integrations/transaction/hold/{holdReference}
POST
​Manual Transaction​
/integrations/transaction/manual
GET
​List Transaction​
/integrations/transaction/list
GET
​List Order Transactions​
/integrations/order/{orderId}/transactions
POST
​Create Coupon​
/integrations/transactions/coupon
POST - Cashback
https://api.gameball.co/api/v3.0/integrations/transaction/cashback
This API is used to reward your players for each unit currency they actually paid for your product or service. The Cashback API is mainly responsible for rewarding your player score and points through Cashback program based on the actual paid amount by your players.
You may find it useful to make use of the Order Endpoint to track completed orders, reward your player and redeem points using a Single API call. This endpoint is specifically designed for E-Commerce Businesses.
mobile or email should be sent along with the playerUniqueId in case (only if) your account supports channel merging.
Request
Header
Attribute
Type
Required
Description
APIKey
string
Yes
Client API key
secretKey
string
Yes
Client Secret Key
Body
Attribute
Type
Required
Description
playerUniqueId
string
Yes
Unique identifier for the player at Gameball
mobile
string
No
Player's unique mobile number. (Sent in case your account supports channel merging)
email
string
No
Player's unique email. (Sent in case your account supports channel merging)
transactionId
string
Yes
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
Yes
Time of transaction in your system in UTC, e.g. order datetime, invoice datetime.
Note: transactionTime is automatically handled when using server-side SDKs.
Example: "2019-09-19T16:14:09.895Z"
amount
number
Yes
Monetary value that the player will be rewarded for based on the Cashback program configurations.
(Note: Amount must be positive).
merchant
object
No
Merchant object as described in Object reference section
In case the player doesn't exist on Gameball before sending the Cashback API call, the player will be created automatically on Gameball and granted the points.
Sample Request Body
{
   "playerUniqueId":"player123",
   "amount":99.98,
   "transactionId":"tra_123456789",
   "transactionTime":"2019-09-19T16:14:09.895Z"
}
Response
Attribute
Type
Description
playerUniqueId
string
Player unique identifier used to uniquely identify the player on Gameball.
gameballTransactionId
integer
Transaction ID on Gameball system.
rewardedPoints
integer
The number of points rewarded to the player for the specified amount.
Sample Response
{
    "playerUniqueId": "player123",
    "gameballTransactionId": 17178,
    "rewardedPoints": 20
}
Usage Example
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 Cashback program.
cURL
Ruby
PHP
Python
.NET
curl -X POST -H 'apiKey: 807b041b7d35425988e354e1f6bce186' \
       -H 'secretKey: klmb041b7d354259l3u4ft35e1q2r3703' -d '{
   "playerUniqueId":"player123",
   "amount":99.98,
   "transactionId":"tra_123456789",
   "transactionTime":"2019-09-19T16:14:09.895Z"
  }' -v -i 'https://api.gameball.co/api/v3.0/integrations/transaction/cashback'
Gameball::Transaction.cashback({
	playerUniqueId:"player123",
	amount:99.98,
	transactionId:"tra_123456789"
})
$cashbackRequest = \Gameball\Models\CashbackRequest::factory("player123",
    99.98, "tra_123456789");
$response = $gameball->transaction->cashback($cashbackRequest);
reward = gameball.rewardObject("player123", 99.98,"tra_123456789")
reward_response = gameball.reward_points(reward)
var request = new RewardPointsRequest() {
    PlayerUniqueId = "player123",
    TransactionId = "tra_123456789",
    Amount = 99.98
};
​
var response = Gameball.Cashback(request);
POST - Redeem Points
https://api.gameball.co/api/v3.0/integrations/transaction/redeem
The API enables the player to use Gameball points as a payment method since it can be substituted for monetary values. A successful call will return the ID of the redeemed transaction reference created at Gameball.
You may find it useful to make use of the Order Endpoint to track completed orders, reward your player and redeem points using a Single API call. This endpoint is specifically designed for E-Commerce Businesses.
mobile or email should be sent along with the playerUniqueId in case (only if) your account supports channel merging.
otp should be sent along with the request body in case (only if) your account has the OTP configuration enabled.
Request
Header
Attribute
Type
Required
Description
APIKey
string
Yes
Client API key
secretKey
string
Yes
Client Secret Key
Body
Attribute
Type
Required
Description
playerUniqueId
string
Yes
Unique identifier for the player at Gameball.
mobile
string
No
Player's unique mobile number. (Sent in case your account supports channel merging)
email
string
No
Player's unique email. (Sent in case your account supports channel merging)
transactionId
string
Yes
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
Yes
Time of transaction in your system in UTC, e.g. order datetime, invoice datetime.
Note: transactionTime is automatically handled when using server-side SDKs.
Example: "2019-09-19T16:14:09.895Z"
redeemedAmount
number
No
Monetary value in your system currency to be redeemed.
Note: 
- Amount must be positive.
- This field is required in case the holdReference is not provided.
holdReference
number
No
Hold reference ID received after calling Hold Points API.
Note: This field is required in case the redeemedPoints is not provided.
merchant
object
No
Merchant object as described in Object reference section
otp
string
No
Player one time password. (Sent in case your account has the OTP configuration enabled). To send otp to a player use OTP endpoint.
Sample Request Body
{
   "playerUniqueId":"player456",
   "transactionId":"tra_123456789",
   "transactionTime":"2019-09-19T16:14:09.895Z",
   "redeemedAmount": null,
   "holdReference":"2342452352435234"
}
Response
Attribute
Type
Description
playerUniqueId
string
Player unique identifier used to uniquely identify the player on Gameball.
gameballTransactionId
integer
Redeem Transaction ID on Gameball system.
redeemedPoints
integer
The total points redeemed equivalent to the redeemed monetary value.
Sample Response
{
    "playerUniqueId": "player456",
    "gameballTransactionId": 17179,
    "redeemedPoints": 200,
}
Usage Example
The example shown is a request sent to Gameball to redeem an amount equivalent to the amount held in the holdReference for player with playerUniqueId"player456".
cURL
Ruby
PHP
Python
.NET
curl -X POST -H 'apiKey: 807b041b7d35425988e354e1f6bce186' \
       -H 'secretKey: klmb041b7d354259l3u4ft35e1q2r3703' -d '{
   "playerUniqueId":"player456",
   "transactionId":"tra_123456789",
   "transactionTime":"2019-09-19T16:14:09.895Z",
   "redeemedPoints": null,
   "holdReference":"2342452352435234"
  }' -v -i 'https://api.gameball.co/api/v3.0/integrations/transaction/redeem'
Gameball::Transaction.redeem_points({
	playerUniqueId:"player456",
	transactionId:"tra_123456789",
	holdReference:"2342452352435234",
})
$redeemRequest = \Gameball\Models\RedeemPointsRequest::factory("player456",
    "2342452352435234", "tra_123456789");
$response = $gameball->transaction->redeemPoints($redeemRequest );
redeem_response = gameball.redeem_points("player456",
    "tra_123456789", hold_reference= "2342452352435234")
var request = new RedeemPointsRequest() {
	PlayerUniqueId = "player456",
	TransactionId = "tra_123456789",
	HoldReference = "2342452352435234"
};
​
var response = Gameball.RedeemPoints(request);
Redemption can be sent along with events and reward using Actions API endpoint.
POST - Refund
https://api.gameball.co/api/v3.0/integrations/transaction/refund
The API is used to cancel a Cashback transaction or refund a points redemption transaction on Gameball. Using transactionId, Gameball will check if there is a cashback transaction or a redemption transaction linked to this transactionId, then complete the process.  After successful submission, the canceled or refunded transaction will update the player’s point balance accordingly.

mobile or email should be sent along with the playerUniqueId in case (only if) your account supports channel merging.
Request
Header
Attribute
Type
Required
Description
APIKey
string
Yes
Client API key
secretKey
string
Yes
Client Secret Key
Body
Attribute
Type
Required
Description
playerUniqueId
string
Yes
Unique identifier for the player at Gameball
mobile
string
No
Player's unique mobile number. (Sent in case your account supports channel merging)
email
string
No
Player's unique email. (Sent in case your account supports channel merging)
transactionId
string
Yes
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
Yes
Time of transaction in your system in UTC, e.g. order datetime, invoice datetime.
Note: transactionTime is automatically handled when using server-side SDKs.
Example: "2019-09-19T16:14:09.895Z"
reverseTransactionId
string
Yes
Unique transaction ID which identifies the underlying reversed transaction in your system, e.g. canceled order number, refunded invoice number. It will be used for reversing any reward or redemption transaction on Gameball.
amount
number
No
The amount to be refunded from the transaction. The whole order is cancelled if not provided.
Example: In case the total order value is 100 USD and you just need to return an item from this order with value 15 USD. 
lineItems
array
No
A list of line item objects, each containing information about an item in the order.
otp
string
No
Player one time password (otp). (Sent in case your account has otp configuration enabled), and is sent to the player using the OTP endpoint.
​
lineItems Object
Attribute
Type
Required
Description
productId
string
No
The ID of the product that the line item belongs to
quantity
number
No
Number of items purchased of this line item that needs to be returned. Must be positive.
Sample Request Body
{
   "playerUniqueId":"player456",
   "transactionId":"1234567890",
   "reverseTransactionId":"234567891",
   "transactionTime":"2019-09-19T11:14:09.895Z",
   "amount": null
}
Sample Request Body (With LineItems)
{
   "playerUniqueId":"player456",
   "transactionId":"1234567890",
   "reverseTransactionId":"234567891",
   "transactionTime":"2019-09-19T11:14:09.895Z",
   "amount": null,
   "lineItems": [{"productId": "p_01", "quantity": 1}]
}
Response
Attribute
Type
Description
orderTransactions
array
An array of orderTransaction objects​
Sample Response
{
    "orderTransactions": [
        {
            "transactionDate": "2021-10-19T21:46:24",
            "gameballTransactionId": 384081,
            "transactionType": "Payment",
            "amount": 70.0,
            "equivalentPoints":7.0,
            "transactionId": "111131212"
        },
        {
            "transactionDate": "2018-01-10T17:12:26.895",
            "gameballTransactionId": 384090,
            "transactionType": "PartialRefund",
            "amount": 10.0,
            "equivalentPoints":1.0,            
            "transactionId": "1111201801"
        },
        {
            "transactionDate": "2018-02-10T17:12:26.895",
            "gameballTransactionId": 384091,
            "transactionType": "PartialRefund",
            "amount": 10.0,
            "equivalentPoints":1.0,            
            "transactionId": "11112018101"
        }
    ]
}
Usage Example
The example shown is a request sent to Gameball after canceling a transactionId “234567891” on your system.
cURL
Ruby
PHP
Python
.NET
curl -X POST -H 'apiKey: 807b041b7d35425988e354e1f6bce186' \
       -H 'secretKey: klmb041b7d354259l3u4ft35e1q2r3703' -d '{
   "playerUniqueId":"player456",
   "transactionId":"1234567890",
   "reverseTransactionId":"234567891",
   "transactionTime":"2019-09-19T11:14:09.895Z",
  }' -v -i 'https://api.gameball.co/api/v3.0/integrations/transaction/refund'
Gameball::Transaction.reverse_transaction({
  playerUniqueId: "player456",
  transactionId: "1234567890",
  reversedTransactionId: "234567891"
})
$response = $gameball->transaction
    ->refund("player456", "1234567890", "234567891");
refund_response = gameball.refund("player456", "1234567890", "234567891")
// Some code
POST - Hold Points
https://api.gameball.co/api/v3.0/integrations/transaction/hold
The API is used to hold a specific amount of points from the player’s points balance. This is used to guarantee the availability of the points to be redeemed until the checkout process is completed. After a successful call, the API returns a holdReference number that is used later in the redemption API. The hold is active at Gameball for 10 minutes and automatically expires afterward. Once the hold expires, the points are returned back to the player balance if this hold was not followed by a Redeem transaction.
You may find it useful to make use of the Order Endpoint to track completed orders, reward your player and redeem points using a Single API call. This endpoint is specifically designed for E-Commerce Businesses.
In case this API is used, to successfully redeem the points, it should be followed by a Redemption API Call with the same resulted holdReference provided from this endpoint.
mobile or email should be sent along with the playerUniqueId in case (only if) your account supports channel merging.
Only one of the following attributes must be sent in the request bodyamountor holdPoints.
Request
Header
Attribute
Type
Required
Description
APIKey
string
Yes
Client API key
secretKey
string
Yes
Client Secret Key
Body
Attribute
Type
Required
Description
playerUniqueId
string
Yes
Unique identifier for the player at Gameball
mobile
string
No
Player's unique mobile number. (Sent in case your account supports channel merging)
email
string
No
Player's unique email. (Sent in case your account supports channel merging)
transactionTime
string
Yes
Time of transaction in your system in UTC, e.g. order datetime, invoice datetime.
Note: transactionTime is automatically handled when using server-side SDKs.
Example: "2019-09-19T16:14:09.895Z"
amount
number
No
Monetary value in the system currency to be held from the player points balance on Gameball.
holdPoints
number
No
Points to be held from the player points balance on Gameball.
Sample Request Body
{
   "playerUniqueId":"player456",
   "amount":98.89,
   "transactionTime":"2019-09-21T16:53:28.190Z",
}
Response
Attribute
Type
Description
playerUniqueId
string
Unique identifier for the player at Gameball
amount
number
Monetary value in the system currency to be held from the player points balance on Gameball.
holdPoints
number
Points that were held from the player points balance on Gameball.
holdReference
string
Hold reference ID to be used in points redemption.
Sample Response
{
   "playerUniqueId":"player456",
   "amount":98.89,
   "holdPoints":9889
   "holdReference":"ref_12343ds"
}
Usage Example
The example shown is a request sent to Gameball to hold player points with playerUniqueId"player456" equivalent to amount of "98.89".
cURL
Ruby
PHP
Python
.NET
curl -X POST -H 'apiKey: 807b041b7d35425988e354e1f6bce186' \
       -H 'secretKey: klmb041b7d354259l3u4ft35e1q2r3703' -d '{
   "playerUniqueId":"player456",
   "amount":98.89,
   "transactionTime":"2019-09-21T16:53:28.190Z",
  }' -v -i 'https://api.gameball.co/api/v3.0/integrations/transaction/hold'
Gameball::Transaction.hold_points({
	playerUniqueId:"player456",
	amount:98.89
})
$response = $gameball->transaction->holdPoints("player456", 98.89);
hold_response = gameball.hold_points("player456", 98.89)
var request = new HoldPointsRequest() {
    PlayerUniqueId = "player456",
    Amount = 98.89
};
​
var response = Gameball.HoldPoints(request);
Delete - Reverse Hold
https://api.gameball.co/api/v3.0/integrations/transaction/hold/{holdReference}
The API call is used to cancel previously held points. It can be called to cancel non-expired hold requests within the 10 minutes validity period.
Request
Header
Attribute
Type
Required
Description
APIKey
string
Yes
Client API key
secretKey
string
Yes
Client Secret Key
Path Parameters
Attribute
Type
Required
Description
holdReference
string
Yes
Hold reference number to be cancelled as received from Gameball.
Usage Example
The example shown is a request sent to Gameball to remove held points with  playerUniqueId"player456" an holdReference equals “9245fe4a-d402-451c-b9ed-9c1a04247482“.
cURL
Ruby
PHP
Python
.NET
curl -x DELETE -H 'apiKey: 807b041b7d35425988e354e1f6bce186' \
       -H 'secretKey: klmb041b7d354259l3u4ft35e1q2r3703'
-v -i 'https://api.gameball.co/api/v3.0/integrations/transaction/hold/9245fe4a-d402-451c-b9ed-9c1a04247482'
Gameball::Transaction.reverse_hold("9245fe4a-d402-451c-b9ed-9c1a04247482")
$response = $gameball->transaction->reverseHold("player456",
    "9245fe4a-d402-451c-b9ed-9c1a04247482");
reverse_hold_response = gameball.reverse_hold("9245fe4a-d402-451c-b9ed-9c1a04247482")
var response = Gameball.ReverseHold("9245fe4a-d402-451c-b9ed-9c1a04247482");
POST - Manual Transaction

Type	Description	Endpoint
POST	Cashback	/integrations/transaction/cashback
POST	Redeem Points	/integrations/transaction/redeem
POST	Refund	/integrations/transaction/refund
POST	Hold Points	/integrations/transaction/hold
DELETE	Reverse Hold	/integrations/transaction/hold/{holdReference}
POST	Manual Transaction	/integrations/transaction/manual
GET	List Transaction	/integrations/transaction/list
GET	List Order Transactions	/integrations/order/{orderId}/transactions
POST	Create Coupon	/integrations/transactions/coupon

Attribute	Type	Required	Description
`playerUniqueId`	string	Yes	Unique identifier for the player at Gameball
`mobile`	string	No	Player's unique mobile number. (Sent in case your account supports channel merging)
`email`	string	No	Player's unique email. (Sent in case your account supports channel merging)
`transactionId`	string	Yes	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	Yes	Time of transaction in your system in UTC, e.g. order datetime, invoice datetime. Note: `transactionTime` is automatically handled when using server-side SDKs. Example: `"2019-09-19T16:14:09.895Z"`
`amount`	number	Yes	Monetary value that the player will be rewarded for based on the Cashback program configurations. (Note: Amount must be positive).
`merchant`	object	No	Merchant object as described in Object reference section

Attribute	Type	Description
`playerUniqueId`	string	Player unique identifier used to uniquely identify the player on Gameball.
`gameballTransactionId`	integer	Transaction ID on Gameball system.
`rewardedPoints`	integer	The number of points rewarded to the player for the specified amount.

Attribute	Type	Required	Description
`playerUniqueId`	string	Yes	Unique identifier for the player at Gameball.
`mobile`	string	No	Player's unique mobile number. (Sent in case your account supports channel merging)
`email`	string	No	Player's unique email. (Sent in case your account supports channel merging)
`transactionId`	string	Yes	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	Yes	Time of transaction in your system in UTC, e.g. order datetime, invoice datetime. Note: `transactionTime` is automatically handled when using server-side SDKs. Example: `"2019-09-19T16:14:09.895Z"`
`redeemedAmount`	number	No	Monetary value in your system currency to be redeemed. Note: - Amount must be positive. - This field is required in case the `holdReference` is not provided.
`holdReference`	number	No	Hold reference ID received after calling Hold Points API. Note: This field is required in case the `redeemedPoints` is not provided.
`merchant`	object	No	Merchant object as described in Object reference section
`otp`	string	No	Player one time password. (Sent in case your account has the OTP configuration enabled). To send otp to a player use OTP endpoint.

Attribute	Type	Description
`playerUniqueId`	string	Player unique identifier used to uniquely identify the player on Gameball.
`gameballTransactionId`	integer	Redeem Transaction ID on Gameball system.
`redeemedPoints`	integer	The total points redeemed equivalent to the redeemed monetary value.

Attribute	Type	Required	Description
`productId`	string	No	The ID of the product that the line item belongs to
`quantity`	number	No	Number of items purchased of this line item that needs to be returned. Must be positive.

Attribute	Type	Description
`orderTransactions`	array	An array of `orderTransaction` objects