> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gameball.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Cashback

> Issue cashback rewards to customers for their transactions.

<Info>
  Security: Provide both `apikey` and `secretkey` headers.
</Info>


## OpenAPI

````yaml POST /api/v4.0/integrations/transactions/cashback
openapi: 3.1.0
info:
  title: Gameball API
  description: >-
    Gameball REST API v4.0 - Complete API reference for integrating loyalty,
    gamification, and customer engagement features
  version: 4.0.0
servers:
  - url: https://api.gameball.co
security:
  - bearerAuth: []
paths:
  /api/v4.0/integrations/transactions/cashback:
    post:
      description: >-
        This API awards loyalty points to customers in Gameball through a
        cashback program based on the amount.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - customerId
                - amount
                - transactionId
                - transactionTime
              properties:
                customerId:
                  type: string
                  description: >-
                    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.
                  example: cust_12345abc
                email:
                  type: string
                  description: >-
                    Customer's email address. This is required if your account
                    uses email-based channel merging.
                  example: john.doe@example.com
                mobile:
                  type: string
                  description: >-
                    Customer's mobile number. This is required if your account
                    uses mobile-based channel merging.
                  example: '+1234567890'
                transactionId:
                  type: string
                  description: >-
                    A unique identifier for a transaction in your system (e.g.,
                    order number or invoice number). This ID is critical for
                    managing transaction lifecycle events such as reversals,
                    cancellations, or refunds in Gameball.
                  example: TXN987654321
                transactionTime:
                  type: string
                  format: date-time
                  description: >-
                    The time of the transaction in your system (e.g., order
                    datetime, invoice datetime).
                  example: '2024-10-11T10:48:56.719Z'
                amount:
                  type: number
                  description: >-
                    Monetary value of the transaction for which the customer
                    will be rewarded, based on the Cashback program
                    configuration.
                  example: 150.75
                merchant:
                  type: object
                  description: >-
                    This object contains details about the specific merchant
                    involved in the transaction, which is particularly important
                    for businesses managing multiple merchants or branches under
                    the same Gameball account. This object can provide
                    identifying information about both the main merchant and any
                    associated branch where the transaction took place.
                  properties:
                    uniqueId:
                      type: string
                      description: Unique identifier for the merchant.
                    name:
                      type: string
                      description: Name of the merchant.
                    branch:
                      type: object
                      required:
                        - uniqueId
                      properties:
                        uniqueId:
                          type: string
                          description: >-
                            Unique identifier for the branch where the
                            transaction took place.
                        name:
                          type: string
                          description: Name of the branch where the transaction took place.
                configurations:
                  type: object
                  description: >-
                    This object contains configurations related to the cashback
                    settings.
                  properties:
                    returnWindow:
                      type: integer
                      description: >-
                        The number of days the cashback will stay in a pending
                        state, typically aligning with the return window in
                        e-commerce to account for potential order cancellations
                        or refunds. The value should be between 0 and 7,300 days
                        (20 years).
                      example: 7
      responses:
        '200':
          description: Cashback issued successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  customerId:
                    type: string
                    description: >-
                      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.
                    example: cust_12345abc
                  gameballTransactionId:
                    type: number
                    description: >-
                      Unique identifier for the transaction in the Gameball
                      system.
                    example: 11034733
                  rewardAmount:
                    type: number
                    description: >-
                      The monetary value equivalent of the points rewarded to
                      the customer for the transaction. Example: If the customer
                      earns 50 points for their purchase and each point is worth
                      $0.10, the rewardAmount will be $5.
                    example: 150.75
                  rewardEquivalentPoints:
                    type: number
                    description: >-
                      The number of points rewarded to the customer for the
                      transaction. Example: If the customer earns 50 points for
                      their purchase, the rewardEquivalentPoints will be 50.
                    example: 0
      security:
        - apiKey: []
          secretKey: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    apiKey:
      type: apiKey
      in: header
      name: apikey
    secretKey:
      type: apiKey
      in: header
      name: secretkey

````