---
title: "Calculate Payment Cashback"
method: POST
path: "/api/v4.0/integrations/payments/cashback"
tags: ["Payments"]
---

# Calculate Payment Cashback

`POST /api/v4.0/integrations/payments/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.

## Request body

- object
  - `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.
  - `email` string — Customer's email address. **Note:** This is required if your account uses email-based channel merging.
  - `mobile` string — Customer's mobile number. **Note:** This is required if your account uses mobile-based channel merging.
  - `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.
  - `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.
  - `totalDiscount` number — Total discount applied to the payment. Must be positive.
  - `totalProcessingFees` number — Total processing fees associated with the payment.
  - `totalTax` number — Total tax amount for the payment.
  - `paymentDetails` object[] — An array containing details about each service in the payment. If not provided, the calculation will only consider the total payment values.
    - `serviceId` string — Unique identifier for the service.
    - `serviceName` string — Service title or name.
    - `serviceProvider` string — Company or entity that provides the service being paid for.
    - `amount` number — The original amount of a single service before any tax or discount is applied.
    - `tax` number — The total amount of taxes applied to the service. Must be positive.
    - `discount` number — The total discount applied to this service, expressed as a positive value.
    - `tags` string[] — Tags associated with the service for categorization or promotional purposes.
    - `category` string[] — Service category. It can include one or multiple categories.
    - `extra` object — Key-value pairs containing any extra information about the service. The values must be of type string or number.
  - `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.
    - `uniqueId` string — Unique identifier for the merchant.
    - `name` string — Name of the merchant.
    - `branch` object — Branch information where the payment took place.
      - `uniqueId` string — Unique identifier for the branch.
      - `name` string — Name of the branch.

## Response `200`

Cashback calculated successfully

- object
  - `totalPoints` number — Total points expected to be earned from the entire payment.
  - `totalScore` number — Total score expected to be earned from the entire payment.
  - `paymentDetails` object[] — An array of individual payment services and their cashback calculation details.
    - `serviceId` string — Unique identifier for the service.
    - `quantity` number — The quantity of the service.
    - `totalDecimalPoints` number — The total decimal points earned for this service, including any campaign impact.
    - `totalPoints` number — The total points earned for this service, including any campaign impact. **Example:** If the base points for a service are 50 and a campaign adds 150 points, the totalPoints would be 200.
    - `totalScore` number — The total score earned for this service. This value is separate from points and is based on your cashback rewards configuration.
    - `rewardWalletFactor` number — The multiplier applied to the service amount to calculate the base points earned. This factor represents how many points are earned per unit of currency spent. **Example:** If the account rewards 10 points for every $1 spent, the rewardWalletFactor would be 10.
    - `campaignId` integer, nullable — The unique identifier for the active transactional campaign that affects the cashback reward for this service. If no campaign is applicable, this field will be null.
    - `campaignName` string, nullable — The name of the active transactional campaign that affects the cashback reward for this service. If no campaign is applicable, this field will be null.
    - `campaignEndDate` string, date-time, nullable — The end date of the active campaign affecting this service. This is the date when the campaign will no longer influence points or rewards.
    - `campaignImpactWalletFactor` number — The multiplier applied by the campaign to the base points calculation. **Example:** If the campaign offers 3x points, the campaignImpactWalletFactor would be 3.
    - `campaignImpactPoints` number — The total number of additional points given for this service due to the campaign's impact. **Example:** If the base points for a service are 100 and the campaign offers 5x points, the campaignImpactPoints would be 400.

## Other responses

- `400` — Invalid request payload
- `401` — Authentication failed
- `500` — Internal server error

---

[API](https://skmtc.net/gameballers/apis/gameball-api.md) · [All operations](https://skmtc.net/gameballers/apis/gameball-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gameballers/gameball-api/revisions/3b11e1670d61/schema)