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.
Type | Description | Endpoint |
POST | /integrations/transaction/cashback | |
POST | /integrations/transaction/redeem | |
POST | /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 |
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.Attribute | Type | Required | Description |
APIKey | string | Yes | Client API key |
secretKey | string | Yes | Client Secret Key |
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 | (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.
{
"playerUniqueId":"player123",
"amount":99.98,
"transactionId":"tra_123456789",
"transactionTime":"2019-09-19T16:14:09.895Z"
}
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. |
{
"playerUniqueId": "player123",
"gameballTransactionId": 17178,
"rewardedPoints": 20
}
The example shown is a request sent to Gameball when you want to reward a player of
playerUniqueId
"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);
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.
Attribute | Type | Required | Description |
APIKey | string | Yes | Client API key |
secretKey | string | Yes | Client Secret Key |
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. |
{
"playerUniqueId":"player456",
"transactionId":"tra_123456789",
"transactionTime":"2019-09-19T16:14:09.895Z",
"redeemedAmount": null,
"holdReference":"2342452352435234"
}
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. |
{
"playerUniqueId": "player456",
"gameballTransactionId": 17179,
"redeemedPoints": 200,
}
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);
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.Attribute | Type | Required | Description |
APIKey | string | Yes | Client API key |
secretKey | string | Yes | Client Secret Key |
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 | |
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. |
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. |
{
"playerUniqueId":"player456",
"transactionId":"1234567890",
"reverseTransactionId":"234567891",
"transactionTime":"2019-09-19T11:14:09.895Z",
"amount": null
}
{
"playerUniqueId":"player456",
"transactionId":"1234567890",
"reverseTransactionId":"234567891",
"transactionTime":"2019-09-19T11:14:09.895Z",
"amount": null,
"lineItems": [{"productId": "p_01", "quantity": 1}]
}
Attribute | Type | Description |
orderTransactions | array |
{
"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"
}
]
}
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
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 body
amount
or holdPoints.
Attribute | Type | Required | Description |
APIKey | string | Yes | Client API key |
secretKey | string | Yes | Client Secret Key |
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. |
{
"playerUniqueId":"player456",
"amount":98.89,
"transactionTime":"2019-09-21T16:53:28.190Z",
}
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. |
{
"playerUniqueId":"player456",
"amount":98.89,
"holdPoints":9889
"holdReference":"ref_12343ds"
}
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);
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.
Attribute | Type | Required | Description |
APIKey | string | Yes | Client API key |
secretKey | string | Yes | Client Secret Key |
Attribute | Type | Required | Description |
holdReference | string | Yes | Hold reference number to be cancelled as received from Gameball. |
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");