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
/integrations/transaction/redeem
POST
Refund
/integrations/transaction/refund
POST
/integrations/transaction/hold
DELETE
/integrations/transaction/hold/{holdReference}
POST
/integrations/transaction/manual
GET
/integrations/transaction/list
GET
/integrations/order/{orderId}/transactions
POST
/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

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

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

https://api.gameball.co/api/v3.0/integrations/transaction/manual
Access manual points reward API to reward your players for each unit currency they actually paid for your product or service or for an arbitrary amount.
mobile or