Transactions

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

The Transactions API endpoints are used to reward a customer, redeem points, refund points, and view the transaction history of a specific customer.

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
GET	Hold Details	/integrations/transaction/hold/{holdReference}
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 customers for each unit of currency they actually pay for your product or service. The Cashback API is mainly responsible for rewarding your customers' scores and points through a Cashback program based on the actual amount paid by your customers.

You may find it useful to make use of the Order Endpoint to track completed orders, reward your customer 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 customer at Gameball.
mobile	string	No	Customer's unique mobile number. (Sent in case your account supports channel merging)
email	string	No	Customer'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 customer 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 customer doesn't exist on Gameball before sending the Cashback API call, the customer 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	Customer unique identifier used to uniquely identify the customer on Gameball.
gameballTransactionId	integer	Transaction ID on Gameball system.
rewardedPoints	integer	The number of points rewarded to the customer 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 customer 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

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'

Ruby

Gameball::Transaction.cashback({
	playerUniqueId:"player123",
	amount:99.98,
	transactionId:"tra_123456789"
})

PHP

$cashbackRequest = \Gameball\Models\CashbackRequest::factory("player123",
    99.98, "tra_123456789");
$response = $gameball->transaction->cashback($cashbackRequest);

Python

reward = gameball.rewardObject("player123", 99.98,"tra_123456789")
reward_response = gameball.reward_points(reward)

.NET

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 customer 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 customer 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 customer at Gameball.
mobile	string	No	Customer's unique mobile number. (Sent in case your account supports channel merging)
email	string	No	Customer'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 describes the merchant itself.
otp	string	No	Customer one time password. (Sent in case your account has the OTP configuration enabled). To send otp to a customer use OTP endpoint.
ignoreOTP	boolean	No	The ignoreOTP attribute allows you to skip OTP verification when set to true. If not provided or set to false, OTP verification will be required for accounts configured to use OTP.

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	Customer unique identifier used to uniquely identify the customer 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 the customer with playerUniqueId"player456".

cURL

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'

Ruby

Gameball::Transaction.redeem_points({
	playerUniqueId:"player456",
	transactionId:"tra_123456789",
	holdReference:"2342452352435234",
})

PHP

$redeemRequest = \Gameball\Models\RedeemPointsRequest::factory("player456",
    "2342452352435234", "tra_123456789");
$response = $gameball->transaction->redeemPoints($redeemRequest );

Python

redeem_response = gameball.redeem_points("player456",
    "tra_123456789", hold_reference= "2342452352435234")

.NET

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. By providing the transactionId, Gameball checks for a corresponding cashback or redemption transaction and processes the request accordingly. After the request is successfully processed, the customer's points balance is updated to reflect the canceled or refunded transaction.

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 customer at Gameball.
mobile	string	No	Customer's unique mobile number. (Sent in case your account supports channel merging)
email	string	No	Customer'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 cashback 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	Customer one time password (OTP). (Sent in case your account has OTP configuration enabled), and is sent to the customer 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

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'

Ruby

Gameball::Transaction.reverse_transaction({
  playerUniqueId: "player456",
  transactionId: "1234567890",
  reversedTransactionId: "234567891"
})

PHP

$response = $gameball->transaction
    ->refund("player456", "1234567890", "234567891");

Python

refund_response = gameball.refund("player456", "1234567890", "234567891")

.NET

// 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 customer'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 (default configurations) and automatically expires afterward. Once the hold expires, the points are returned back to the customer 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 customer 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.

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 customer at Gameball.
mobile	string	No	Customer's unique mobile number. (Sent in case your account supports channel merging)
email	string	No	Customer'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 customer points balance on Gameball.
holdPoints	number	No	Points to be held from the customer points balance on Gameball.
otp	string	No	Customer one time password. (Sent in case your account has the OTP configuration enabled). To send otp to a customer use OTP endpoint.
ignoreOTP	boolean	No	The ignoreOTP attribute allows you to skip OTP verification when set to true. If not provided or set to false, OTP verification will be required for accounts configured to use OTP.
hash	string	No	The hash retrieved by the GET - Customer's Hash API. Used to verify the transaction's validity for in-store purchases. For more information check here: Using Virtual ID

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 customer at Gameball
amount	number	Monetary value in the system currency to be held from the customer points balance on Gameball.
holdPoints	number	Points that were held from the customer 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 customer points with playerUniqueId"player456" equivalent to amount of "98.89".

cURL

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'

Ruby

Gameball::Transaction.hold_points({
	playerUniqueId:"player456",
	amount:98.89
})

PHP

$response = $gameball->transaction->holdPoints("player456", 98.89);

Python

hold_response = gameball.hold_points("player456", 98.89)

.NET

var request = new HoldPointsRequest() {
    PlayerUniqueId = "player456",
    Amount = 98.89
};

var response = Gameball.HoldPoints(request);

GET - Hold Details

https://api.gameball.co/api/v3.0/integrations/transaction/hold/{holdReference}

The API call is used to retrieves hold details for a specified hold reference.

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.

Response

Attribute	Type	Description
holdPoints	number	Points that has been held from the customer points balance on Gameball.
amount	number	Monetary value in the system currency that has been held from the customer points balance on Gameball.
expirationDate	Date Time	The date time that the hold will be expired on.
state	string	Hold status. Possible values are: Active Used Expired

Sample Response

{
    "holdPoints": 200,
    "amount": 200,
    "expirationDate": "2024-08-30T10:41:35.332855",
    "state": "active"
}

Usage Example

cURL

curl --location 'https://api.gameball.co/api/v3/Integrations/transaction/hold/d522b047-6b8a-4229-af81-112ff406d5ee' \
--header 'APIKey: 807b041b7d35425988e354e1f6bce186' \
--header 'secretKey: klmb041b7d354259l3u4ft35e1q2r3703'

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 hold 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

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'

Ruby

Gameball::Transaction.reverse_hold("9245fe4a-d402-451c-b9ed-9c1a04247482")

PHP

$response = $gameball->transaction->reverseHold("player456",
    "9245fe4a-d402-451c-b9ed-9c1a04247482");

Python

reverse_hold_response = gameball.reverse_hold("9245fe4a-d402-451c-b9ed-9c1a04247482")

.NET

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 customers for each unit currency they actually paid for your product or service or for an arbitrary amount.

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 customer at Gameball
mobile	string	No	Customer's unique mobile number. (Sent in case your account supports channel merging)
email	string	No	Customer'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"
username	string	Yes	Represents the username of the user in your system that is performing the manual reward for the customer.
reason	string	Yes	Represents the reason you wish to specify as to why the customer is being rewarded.
points	integer	No	Number of points to be rewarded to or deducted from the customer. a "+" value is accumulation while a "-" value is deduction.
amount	number	No	Monetary value that the customer will be rewarded for (or deducted) based on the Cashback program configurations. (Note: Amount must be positive).

Either the amount or the points should be sent along with the request.

In case the customer doesn't exist on Gameball before sending the Manual Transaction API call, the customer 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",
   "username": "admin_storename",
   "reason": "Thank You Gift"
}

Response

Attribute	Type	Description
playerUniqueId	string	Unique identifier for the customer at Gameball
gameballTransactionId	integer	Transaction ID on Gameball system.
amount	number	Monetary value that the customer will be rewarded for based on the Redemption Rate. (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. Example: "2019-09-19T16:14:09.895Z"
points	integer	The number of points rewarded to the customer for the specified amount

Sample Response

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

Usage Example

cURL

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",
   "username": "admin_storename",
   "reason": "Thank You Gift"
}' -v -i 'https://api.gameball.co/api/v3.0/integrations/transaction/manual'

Ruby

Gameball::Transaction.manual_transaction({
   playerUniqueId:"player123",
   amount:99.98,
   transactionId:"tra_123456789",
   username: "admin_storename",
   reason: "Thank You Gift"
})

PHP

$request = \Gameball\Models\ManualTransactionRequest::factory(
            "player123",
            99.98,
            null,
            "tra_123456789",
            "Thank You Gift",
            "admin_storename");
            
$response = $gameball->transaction
    ->manualTransaction($manualRequest);

Python

manual_response = gameball.manual_transaction(
        "player123",
        "tra_123456789",
        "admin_storename",
        "Thank You Gift",
        amount=99.98)

.NET

var request = new ManualTransactionRequest() {
    PlayerUniqueId = "player123",
    Amount = 99.98,
    TransactionId = "tra_123456789",
    Reason = "Thank You Gift",
    Username = "admin_storename"
};

var response = Gameball.ManualTransaction(request);

GET - List Transactions

https://api.gameball.co/api/v3.0/integrations/transaction/list

This API is used to get transactions from Gameball. The result is paged and can be filtered.

Request

Header

Attribute	Type	Required	Description
APIKey	string	Yes	Client API key
secretKey	string	Yes	Client Secret Key

Query Parameters

Attribute	Type	Required	Description
page	integer	No	Result page number. Starts from 1.
limit	integer	No	Result page size. (The default result page size is 50 transactions, and the maximum limit is 200)
direction	string	No	'+' to return addition transactions and '-' to return deduction transactions.
from	date	No	From date.
to	date	No	To date.
transactionId	string	No	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.
status	enum	No	Transaction status. Possible values are: 1 => Active 2 => Pending 3 => Blocked 4 => Expired
playerUniqueId	string	No	Used to get a specific customer's transactions list.

Response

Attribute	Type	Description
transactions	object	array of paged transaction objects ordered by transactionTime desc.
count	integer	currently displayed transactions list count,
total	integer	total number of transactions available matching the applied filters Example: "count": 50 "total": 200

transaction object

Attribute	Type	Description
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.
gameballTrasnactionId	integer	Transaction ID on Gameball system.
type	string	Can be one of the following: AchievementReward: Transaction captured by Gameball when a customer achieves VIP tier/reward campaign/referral. PaymentReward: Transaction captured by Gameball to reward a customer for every placed order. Refund: Transaction captured by Gameball that refunds customer points that has been redeemedin a refunded order. Redemption: Transaction captured by Gameball whenever a customer redeems his points. Expiry: Transaction captured by Gameball whenever a customer's points expire, to signal that some of the customer points have expired. Cancel: Transaction Captured by Gameball whenever a customer cancels a specific order, deducts the rewarded points from the customer. Migration: Transaction captured by Gameball after adding/deducting points during updating/migrating customers using a csv file. ManualAccumulation: Transaction captured by Gameball for any manually added points to a customer's balance. DiscountCode : Transaction captured by Gameball whenever a customer creates a coupon code. ManualDeduction : Transaction captured by Gameball for any manually removed points from a customer's balance. ManualReward : Same as AchievementReward but when the achievement is rewarded manually.
direction	string	Either "+" or "-" indicating transaction was an addition or deduction.
playerUniqueId	string	Customer unique identifier used to uniquely identify the customer on Gameball.
points	integer	Number of points involved in the transaction.
amount	number	Monetary amount involved in the transaction.
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. Example: "2019-09-19T16:14:09.895Z"
status	enum	Transaction status. Possible values are: Active Pending Blocked Expired
couponCode	string	Code of the coupon (In case of DiscountCode coupon type).
isCouponUsed	boolean	A Boolean flag indicating if the coupon was used or not.
couponType	string	Indicates the type of the coupon, the value of the string can be one of the following: free_shipping percentage_discount fixed_discount free_product fixed_rate_discount custom
merchantName	string	Merchant name for transaction.
branchName	string	Branch Name for transaction.
expiryDate	string	Time of points expiry in UTC Example: "2019-09-19T16:14:09.895Z"
pointsBalanceBefore	integer	The total points balance before the transaction.
pointsBalanceAfter	integer	The total points balance after the transaction.
achievementName	string	The name of the reward campaign that was achieved in case of transaction type AchievementReward.
reason	string	The reason of the transaction in case of transaction type ManualAccumilation or ManualDeduction.

Sample Response

{
    "transactions":[
       {
          "transactionId":"trx123",
          "gameballTransactionId":"gbtrx123",
          "transactionTime":"2019-09-21T16:53:28.190Z",
          "type":"Cash Back",
          "direction":"+",
          "playerUniqueId":"1234",
          "points":500,
          "amount":10,
          "status":"Active",
          "merchantName":"merchant",
          "branchName":"branch",
          "expiryDate": "2019-10-21T16:53:28.190Z",
          "pointsBalanceBefore": 1000,
          "pointsBalanceAfter": 1500
       },
       {
        "transactionId": "trx1234",
        "gameballTrasnactionId": "gbtrx1234",
        "type": "DiscountCode",
        "direction": "-",
        "playerUniqueId": "1234",
        "points": 1700,
        "amount": 17.0,
        "transactionTime": "2022-09-28T11:58:34.579234",
        "status": "Active",
        "couponCode": "50OFF",
        "isCouponUsed": false,
        "couponType": "fixed_rate_discount",
        "merchantName": "merchant",
        "branchName": "branch",
        "expiryDate": "2022-10-28T11:58:34.579234",
        "pointsBalanceBefore": 1000,
        "pointsBalanceAfter": 2700
    }
    ],
    "count":50,
    "total":344
 }

Usage Example

cURL

curl -X GET -H 'apiKey: 807b041b7d35425988e354e1f6bce186' \
       -H 'secretKey: klmb041b7d354259l3u4ft35e1q2r3703' -v -i 
 'https://api.gameball.co/api/v3.0/integrations/transactions/list'

Ruby

Gameball::Transaction.list_transactions({
   page:2,
   limit:10
})

PHP

$response = $gameball->transaction->listTransactions(2, 10);

Python

transactions = gameball.list_transactions(page= 1, limit= 50)

.NET

var response = Gameball.ListTransactions(Page= 1, Limit= 50);

merchant object

Attribute	Type	Description
uniqueId	string	Merchant unique id or code
name	string	Merchant name
branch	object	Optional branch information
branch.uniqueId	string	Branch unique id or code
branch.name	string	Branch name

Get - List Order Transactions

https://api.gameball.co/api/v3.0/integrations/order/{orderId}/transactions

This endpoint is used to list all the transactions (such as refunds) relating to an order.

Request

Header

Attribute	Type	Required	Description
APIKey	string	Yes	Client API Key
secretkey	string	Yes	Client Secret Key

Response

Body

Attribute	Type	Description
orderTransactions	array	An array of orderTransaction objects.
total	integer	Total number of transactions available matching the applied filters Example: "count": 50 "total": 20
count	integer	Returned currently displayed transactions list count.

orderTransaction Object

Attribute	Type	Description
transactionDate	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. Example: "2019-09-19T16:14:09.895Z"
gameballTransactionId	integer	Transaction ID on Gameball system.
transactionType	string	Transaction type string. Can be one of the following: AchievementReward Payment Refund Redemption Expiry Cancel Migration ManualAccumulation DiscountCode ManualDeduction ManualReward
amount	number	Monetary amount involved in the transaction.
equivalentPoints	number	Equivalent points to the amount.
transactionId	string	Transaction ID that was sent from the client's system.

Response Example

{
    "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"
        }
    ],
    "total": 3,
    "count": 3
}

POST - Create Coupon

https://api.gameball.co/api/v3.0/integrations/transactions/coupon

This endpoint is used to create coupons for a specific customer.

Request

Header

Attribute	Type	Required	Description
APIKey	string	Yes	Client API key
secretKey	string	Yes	Client Secret Key

Body

Attribute	Type	Description
value	double	The monetary value to be redeemed. Only used with the general redemption rule.
playerUniqueId	string	Unique identifier for the customer at Gameball.
ruleId	integer	The Id of the redemption rule that is being redeemed. You can get the Ids of all your redemption rules through the GET - Redemption Rules API.

Sample Request

{
    "value": 17000000,
    "playerUniqueId": "player",
    "ruleId":191269
}

Response

Attribute	Type	Description
code	string	Code of the coupon that was created.
url	string	URL associated with the Coupon group, it could be null. (if you are not using predefined coupons)
startDate	DateTime	Date at which you can start using coupon.
expiryDate	DateTime	Date at which coupon expires and can no longer be used.

Sample Response

{
    "code": "freesundae1",
    "url": "https://www.mcdonalds.eg/sundae",
    "startDate": "2021-12-13T18:18:45.775Z",
    "expiryDate": "2022-12-13T18:18:45.775Z"
}