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

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

Body

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

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

Body

Sample Request Body

{
   "playerUniqueId":"player456",
   "transactionId":"tra_123456789",
   "transactionTime":"2019-09-19T16:14:09.895Z",
   "redeemedAmount": null,
   "holdReference":"2342452352435234"
}

Response

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

Body

lineItems Object

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

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

Body

Sample Request Body

{
   "playerUniqueId":"player456",
   "amount":98.89,
   "transactionTime":"2019-09-21T16:53:28.190Z",
}

Response

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

Path Parameters

Response

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

Path Parameters

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

Body

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

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

Query Parameters

Response

transaction object

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

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

Response

Body

orderTransaction Object

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

Body

Sample Request

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

Response

Sample Response

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