Sign in

v36

latestOpenAPI 3.1.0raw.githubusercontent.com2026-08-017439390.7 KB
Payments

Calculate Payment Cashback

This API calculates the cashback points to be rewarded for a specific payment in Gameball, based on provided payment details. It considers configured cashback rules and customer eligibility.

Security: Requires apiKey header.

Channel Merging Available: If your system uses different customer IDs across multiple channels (e.g., online and offline), Gameball's channel merging feature helps unify customer profiles. By including the customer's mobile number or email (based on your merging configuration) with each request, Gameball will combine activities into a single profile.

Important: This API calculates the expected cashback points but does not perform any actual reward or action for the customer.

post/api/v4.0/integrations/payments/cashback

Request body

customerIdstring

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.

emailstring

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

mobilestring

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

totalPaidnumber

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.

totalAmountnumber

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.

totalDiscountnumber

Total discount applied to the payment. Must be positive.

totalProcessingFeesnumber

Total processing fees associated with the payment.

totalTaxnumber

Total tax amount for the payment.

Example request

{
  "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"
    }
  }
}

Response

Cashback calculated successfully

totalPointsnumber

Total points expected to be earned from the entire payment.

totalScorenumber

Total score expected to be earned from the entire payment.

Example response

{
  "totalPoints": 19000,
  "paymentDetails": [
    {
      "serviceId": "s_1234",
      "quantity": 1,
      "totalDecimalPoints": 15000,
      "totalPoints": 15000,
      "rewardWalletFactor": 20,
      "campaignId": 2149,
      "campaignName": "5x Points Campaign",
      "campaignEndDate": "2024-11-01T08:39:00",
      "campaignImpactWalletFactor": 5,
      "campaignImpactPoints": 12000
    }
  ]
}