Skip to main content
POST
/
api
/
v4.0
/
integrations
/
payments
/
cashback
Calculate Payment Cashback
curl --request POST \
  --url https://api.gameball.co/api/v4.0/integrations/payments/cashback \
  --header 'Content-Type: application/json' \
  --header 'apikey: <api-key>' \
  --data '
{
  "customerId": "cust456",
  "email": "john.doe@example.com",
  "mobile": "+1234567890",
  "totalPaid": 100,
  "totalAmount": 120,
  "totalDiscount": 20,
  "totalProcessingFees": 10,
  "totalTax": 10,
  "paymentDetails": [
    {
      "serviceId": "s_1234",
      "serviceName": "Vodafone Topup",
      "serviceProvider": "Vodafone",
      "amount": 100,
      "tax": 10,
      "discount": 20,
      "tags": [
        "Telecom",
        "Topup"
      ],
      "category": [
        "Telecom Topup"
      ],
      "extra": {}
    }
  ],
  "merchant": {
    "uniqueId": "MERCH001",
    "name": "TechGadgetStore",
    "branch": {
      "uniqueId": "BRANCH001",
      "name": "Downtown Branch"
    }
  }
}
'
{
  "totalPoints": 19000,
  "totalScore": 0,
  "paymentDetails": [
    {
      "serviceId": "s_1234",
      "quantity": 1,
      "totalDecimalPoints": 15000,
      "totalPoints": 15000,
      "totalScore": 0,
      "rewardWalletFactor": 20,
      "campaignId": 2149,
      "campaignName": "5x Points Campaign",
      "campaignEndDate": "2024-11-01T08:39:00",
      "campaignImpactWalletFactor": 5,
      "campaignImpactPoints": 12000
    }
  ]
}
Calculate the cashback points to be rewarded for a specific payment. This estimates rewards based on your configured rules and eligibility; it does not perform any reward.
Security: Provide apikey header.

Authorizations

​
apikey
string
header
required

Body

application/json
​
customerId
string

Unique identifier for the customer that you can reference across the customer's whole lifetime. Could be a database ID, random string, email or anything that uniquely identifies the customer. If provided, the cashback calculation will consider the customer's tier. Special tier-based configurations, such as enhanced point accrual rates, may affect the points calculation.

Example:

"cust456"

​
email
string

Customer's email address. Note: This is required if your account uses email-based channel merging.

Example:

"john.doe@example.com"

​
mobile
string

Customer's mobile number. Note: This is required if your account uses mobile-based channel merging.

Example:

"+1234567890"

​
totalPaid
number

The actual amount paid by the customer for the payment, accounting for any discounts or coupons applied. Unlike totalAmount, which reflects the original cost of the payment, totalPaid represents the final amount the customer paid after all adjustments. This value is used for reward calculations in Gameball to determine the points or benefits earned from the payment. Example: A customer makes a bill payment for their electricity bill of $120, including taxes and processing fees. If a $20 coupon is applied, the totalPaid becomes $100, reflecting the discounted amount the customer paid.

Example:

100

​
totalAmount
number

The total cost of the payment, including all item prices, processing fees, and taxes. This value does not account for any discounts or coupons applied and is not used for calculations in Gameball; it is solely saved as historical data linked to the payment. Must be a positive value.

Example:

120

​
totalDiscount
number

Total discount applied to the payment. Must be positive.

Required range: x >= 0
Example:

20

​
totalProcessingFees
number

Total processing fees associated with the payment.

Example:

10

​
totalTax
number

Total tax amount for the payment.

Example:

10

​
paymentDetails
object[]

An array containing details about each service in the payment. If not provided, the calculation will only consider the total payment values.

​
merchant
object

Details about the specific merchant involved in the payment, particularly useful for businesses managing multiple merchants or branches under the same Gameball account.

Response

Cashback calculated successfully

​
totalPoints
number

Total points expected to be earned from the entire payment.

Example:

19000

​
totalScore
number

Total score expected to be earned from the entire payment.

Example:

0

​
paymentDetails
object[]

An array of individual payment services and their cashback calculation details.