Gameball Integrations API

openapi: 3.2.0
info:
  title: Gameball Integrations 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: []
tags:
- name: Integrations
paths:
  /api/v4.0/integrations/customers:
    post:
      summary: Create Customer
      description: Create or update a customer profile in Gameball using a unique customerId. Serving as a consistent identity, this customerId allows you to track a customer's entire journey.
      operationId: createCustomer
      security:
      - apiKey: []
      requestBody:
        description: Customer payload containing identifiers and attributes.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertCustomerRequest'
      responses:
        '200':
          description: Customer created or updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpsertCustomerResponse'
      tags:
      - Integrations
  /api/v4.0/integrations/customers/{customerId}:
    get:
      summary: Get Customer
      description: Retrieve essential customer information from Gameball using a unique customerId. Returns general customer info (no personal data) with the public key.
      operationId: getCustomer
      security:
      - apiKey: []
      parameters:
      - name: customerId
        in: path
        required: true
        schema:
          type: string
        description: Unique identifier for the customer
      responses:
        '200':
          description: Customer found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerResponse'
      tags:
      - Integrations
    delete:
      summary: Delete Customer
      description: Remove a customer profile and associated data from the system.
      operationId: deleteCustomer
      security:
      - apiKey: []
        secretKey: []
      parameters:
      - name: customerId
        in: path
        required: true
        schema:
          type: string
        description: Unique identifier for the customer
      responses:
        '200':
          description: Customer deleted successfully
      tags:
      - Integrations
  /api/v4.0/integrations/customers/{customerId}/details:
    get:
      summary: Get Customer Details
      description: Retrieve comprehensive customer information including personally identifiable information (PII).
      operationId: getCustomerDetails
      security:
      - apiKey: []
        secretKey: []
      parameters:
      - name: customerId
        in: path
        required: true
        schema:
          type: string
        description: Unique identifier for the customer
      responses:
        '200':
          description: Customer details found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerDetailsResponse'
      tags:
      - Integrations
  /api/v4.0/integrations/customers/{customerId}/coupons:
    get:
      summary: Get Customer Coupons
      description: Retrieve customer's available coupons with detailed information on each coupon's type, status, and usage.
      operationId: getCustomerCoupons
      security:
      - apiKey: []
        secretKey: []
      parameters:
      - name: customerId
        in: path
        required: true
        schema:
          type: string
        description: Unique identifier for the customer
      responses:
        '200':
          description: Customer coupons found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerCouponsResponse'
      tags:
      - Integrations
  /api/v4.0/integrations/customers/social-challenges:
    post:
      summary: Achieve Social Campaign
      description: Mark a social campaign as achieved for a customer and grant the configured reward from your backend. This is the server-to-server equivalent of the in-widget social action for Social Activities campaigns.
      operationId: achieveSocialChallenge
      security:
      - apiKey: []
        secretKey: []
      requestBody:
        description: Social challenge achievement payload.
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - customerId
              - challengeId
              properties:
                customerId:
                  type: string
                  maxLength: 100
                  description: The customer's unique ID in your system. The customer must already exist in Gameball.
                  example: customer_123
                challengeId:
                  type: integer
                  minimum: 1
                  description: The ID of the Social Activities campaign to award.
                  example: 11664
                email:
                  type: string
                  description: Customer's email address. Helps identify the customer when channel merging is enabled.
                  example: john.doe@example.com
                mobile:
                  type: string
                  description: Customer's mobile number. Helps identify the customer when channel merging is enabled.
                  example: '+1234567890'
            examples:
              sample:
                summary: Sample request
                value:
                  customerId: customer_123
                  challengeId: 11664
      responses:
        '202':
          description: Social challenge achievement accepted for processing
          content:
            application/json:
              schema:
                type: object
                properties:
                  customerId:
                    type: string
                    description: The customer ID from the request.
                    example: customer_123
                  challengeId:
                    type: integer
                    description: The social campaign ID from the request.
                    example: 11664
                  gameballStatus:
                    type: string
                    description: Present when the Gameball program is disabled. Omitted while Gameball is enabled.
                  message:
                    type: string
                    description: Informational message when the Gameball program is disabled.
                  learnMore:
                    type: string
                    description: Link to learn more when the Gameball program is disabled.
              examples:
                accepted:
                  value:
                    customerId: customer_123
                    challengeId: 11664
        '400':
          description: Invalid request (missing fields, duplicate submission, etc.)
        '401':
          description: Missing or invalid secret key
        '404':
          description: Customer does not exist
        '500':
          description: Unexpected server error
      x-codeSamples:
      - lang: curl
        label: cURL
        source: "curl -X POST 'https://api.gameball.co/api/v4.0/integrations/customers/social-challenges' \\\n  -H 'Content-Type: application/json' \\\n  -H 'apikey: YOUR_API_KEY' \\\n  -H 'secretkey: YOUR_SECRET_KEY' \\\n  -d '{\"customerId\":\"customer_123\",\"challengeId\":11664}'"
      - lang: javascript
        label: JavaScript
        source: "await fetch('https://api.gameball.co/api/v4.0/integrations/customers/social-challenges', {\n  method: 'POST',\n  headers: {\n    'Content-Type': 'application/json',\n    apikey: 'YOUR_API_KEY',\n    secretkey: 'YOUR_SECRET_KEY'\n  },\n  body: JSON.stringify({ customerId: 'customer_123', challengeId: 11664 })\n});"
      - lang: python
        label: Python
        source: "import requests\n\nrequests.post(\n  'https://api.gameball.co/api/v4.0/integrations/customers/social-challenges',\n  json={'customerId': 'customer_123', 'challengeId': 11664},\n  headers={'apikey': 'YOUR_API_KEY', 'secretkey': 'YOUR_SECRET_KEY', 'Content-Type': 'application/json'}\n)"
      - lang: csharp
        label: C#
        source: 'using System.Net.Http;

          using System.Text;


          var client = new HttpClient();

          client.DefaultRequestHeaders.Add("apikey", "YOUR_API_KEY");

          client.DefaultRequestHeaders.Add("secretkey", "YOUR_SECRET_KEY");

          var content = new StringContent("{\"customerId\":\"customer_123\",\"challengeId\":11664}", Encoding.UTF8, "application/json");

          var response = await client.PostAsync("https://api.gameball.co/api/v4.0/integrations/customers/social-challenges", content);

          response.EnsureSuccessStatusCode();'
      tags:
      - Integrations
  /api/v4.0/integrations/customers/{customerId}/hash:
    get:
      summary: Get Customer Hash
      description: Generate a hash for an existing customer based on their unique customerId.
      operationId: getCustomerHash
      security:
      - apiKey: []
        secretKey: []
      parameters:
      - name: customerId
        in: path
        required: true
        schema:
          type: string
        description: Unique identifier for the customer
      responses:
        '200':
          description: Customer hash generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerHashResponse'
      tags:
      - Integrations
  /api/v4.0/integrations/referrals/validate:
    get:
      summary: Validate Referrer Code
      description: Validate whether a provided referral code is valid and eligible for use during customer signup.
      operationId: validateReferrerCode
      security:
      - apiKey: []
      parameters:
      - name: referrerCode
        in: query
        required: true
        schema:
          type: string
        description: The referral code to validate
      - name: forCustomerId
        in: query
        required: false
        schema:
          type: string
        description: Customer ID to prevent self-referral
      responses:
        '200':
          description: Referral code validation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReferralValidationResponse'
      tags:
      - Integrations
  /api/v4.0/integrations/payments:
    post:
      description: 'The API call tracks new payments, specifically tailored for fintech solutions. It captures key payment details, ensuring accurate tracking of customer transactions.


        This API triggers the **"Payment Processed"** event, allowing you to automate follow-up actions such as initiating workflows, sending notifications, or rewarding customers with badges.


        The event includes all properties provided in the payload.'
      security:
      - apiKey: []
        secretKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - customerId
              - paymentId
              - paymentDate
              - totalPaid
              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: cust456
                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'
                paymentId:
                  type: string
                  description: Unique identifier for the payment on your system.
                  example: 6253e03b
                paymentDate:
                  type: string
                  format: date-time
                  description: Timestamp of when the payment was occurred.
                  example: '2024-09-21T16:53:28.190Z'
                totalPaid:
                  type: number
                  description: '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:
                  type: number
                  description: '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: A customer makes a bill payment for their electricity bill of $120, including taxes and processing fees. If a $20 coupon is applied, the totalAmount remains $120 as it represents the original cost of the payment before any discounts are applied.'
                  example: 120
                totalDiscount:
                  type: number
                  description: Total discount applied to the payment.
                  example: 20
                totalProcessingFees:
                  type: number
                  description: Total processing fees associated with the payment.
                  example: 10
                totalTax:
                  type: number
                  description: Total tax amount for the payment.
                  example: 10
                paymentDetails:
                  type: array
                  description: An array containing details about each element in the payment bill. If not provided, the calculation will only consider the total payment values.
                  items:
                    type: object
                    properties:
                      serviceId:
                        type: string
                        description: Unique identifier for the service.
                        example: s_1234
                      serviceName:
                        type: string
                        description: Service title or name.
                        example: Vodafone Topup
                      serviceProvider:
                        type: string
                        description: Company or entity that provides the service being paid for. This could be a telecom operator, an electricity provider, a streaming platform, or any other service vendor.
                        example: Vodafone
                      amount:
                        type: number
                        description: The original amount of a single service before any tax or discount is applied. This reflects the cost of the service, not the total for multiple quantities in a payment.
                        example: 100
                      tax:
                        type: number
                        description: The total amount of taxes applied to the service. This amount must be positive and reflects the total taxes.
                        example: 10
                      discount:
                        type: number
                        description: The total discount applied to this service, expressed as a positive value. This amount should reflect the total discounts.
                        example: 20
                      tags:
                        type: array
                        items:
                          type: string
                        description: Tags associated with the service for categorization or promotional purposes.
                        example:
                        - Telecom
                        - Topup
                      category:
                        type: array
                        items:
                          type: string
                        description: 'Service category, such as Telecom top-up or electricity. It can include one or multiple categories. Example: ["Telecom Top-up", "Internet Bill", "Streaming Subscription"]'
                        example:
                        - Telecom Topup
                      extra:
                        type: object
                        additionalProperties: true
                        description: Key-value pairs containing any extra information about the service, such as size, color, or other custom attributes. The values must be of type string or number.
                        example: {}
                redemption:
                  type: object
                  description: Redemption details for the payment, including points held for redemption.
                  properties:
                    pointsHoldReference:
                      type: string
                      description: Reference from the Hold Points API for redeeming held points. For more details on how hold references are generated and utilized, refer to the Transactions section.
                      example: HOLD123
                    couponsLockReference:
                      type: string
                      description: 'The lock reference for the coupon is a unique identifier used to "lock" a coupon for a specific customer or order. This prevents the coupon from being used by others or on multiple transactions. For more details on how to generate and use lock references, refer to the Coupons section. Example: If you lock a coupon for a specific transaction, the lockReference could look like "lockReference": "abc123def456".'
                      example: LOCK123
                    couponCodes:
                      type: array
                      items:
                        type: string
                      description: 'A list of coupon codes that were applied to the payment. Each code in the array represents a different discount or promotional coupon used during the checkout process. Coupon codes must be locked before they can be used for redemption. Example: If a customer applied two coupon codes, one for a 10% discount and another for free fees, the couponCodes array might look like this: ["DISCOUNT10", "FREEFEES2024"]'
                      example:
                      - DISCOUNT10
                extra:
                  type: object
                  additionalProperties: true
                  description: 'Key-value pairs containing any extra information about the payment. The values must be of type string or number. Example: The extra attribute can store additional details like the billing address and payment status. For instance, when a customer completes a payment, the billing address ensures accurate invoicing by including details like the company name and tax identification number. At the same time, the payment status helps track the transaction—whether it''s "Pending" for deferred payments or "Completed" when successfully processed—ensuring smooth order management and financial compliance.'
                  example:
                    billingAddress: 'Jane Smith, Acme Corp, 456 Elm St, Springfield, IL 62704, USA, Tax ID: US987654321'
                    paymentStatus: Pending
                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 payment took place.
                        name:
                          type: string
                          description: Name of the branch where the payment took place.
                guest:
                  type: boolean
                  description: Indicates whether the customer is a guest (not signed up). Set this to true for guest users; otherwise, they are treated as registered customers by default.
                  example: false
                channel:
                  type: string
                  enum:
                  - mobile
                  - pos
                  - web
                  - callcenter
                  description: 'The channel through which the payment was placed helps track the origin of the payment, particularly useful for systems that support multiple sales or communication channels. By identifying the channel, you can gain valuable insights into customer behavior, optimize channel-specific strategies, and ensure efficient handling of payments across platforms. Possible values: mobile (The payment was placed through your mobile application), pos (The payment was placed in person using a Point of Sale system), web (The payment was placed through your website), callcenter (The payment was placed over the phone by contacting a customer service representative).'
                  example: web
                cashbackConfigurations:
                  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: Payment tracked
          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_123456789
                  redeemedPoints:
                    type: number
                    description: 'Points redeemed by the customer for this payment, if applicable. Example: If a customer has accumulated 500 points and decides to redeem 100 points for a discount on their current payment, the redeemedPoints value for that transaction will be 100. This helps track how many points were used in the transaction and what benefits were applied to the payment based on the customer''s redeemed points.'
                    example: 1000
                  rewardedPoints:
                    type: number
                    description: 'The total number of points rewarded to the customer for making this payment. These points are typically awarded based on your configured cashback rewards. Example: If the store rewards 10 points for every $1 spent, and a customer completes a payment worth $50, the rewardedPoints for this order would be 500 points.'
                    example: 101
                  paymentDetails:
                    type: array
                    description: Details about each service in the payment, including points rewarded.
                    items:
                      type: object
                      properties:
                        serviceId:
                          type: string
                          description: Unique identifier for the service.
                          example: service_123
                        decimalPoints:
                          type: number
                          description: Fractional points rewarded for this line item.
                          example: 91.25
                        points:
                          type: number
                          description: Any points rewarded for this line item.
                          example: 91
                        score:
                          type: number
                          description: Any score awarded for the line item, if applicable.
                          example: 0
      tags:
      - Integrations
  /api/v4.0/integrations/transactions/redeem:
    post:
      description: This API enables customers to redeem loyalty points as a payment method in Gameball, allowing them to use points in place of monetary value during transactions. By providing details such as customerId and amount, this endpoint facilitates point-based redemptions within the purchase process.
      security:
      - apiKey: []
        secretKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - customerId
              - 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 can be used to reverse, cancel, or refund any reward or redemption transactions in Gameball.
                  example: txn98765
                transactionTime:
                  type: string
                  format: date-time
                  description: The time of the transaction in your system (e.g., order datetime, invoice datetime). Must be in UTC (ISO 8601 format).
                  example: '2024-10-11T10:57:43.382Z'
                amount:
                  type: number
                  description: 'The actual monetary value the customer wants to redeem. This will be deducted from their points balance based on the redemption factor. For instance, if the customer wants to redeem $10 and the redemption factor is 0.1, then 100 points will be deducted from their balance to cover this amount. Note: Only one of amount, points, or holdReference must be provided for the redemption.'
                  example: 10
                points:
                  type: integer
                  description: 'The number of points the customer wants to redeem from their balance. This allows the customer to specify exactly how many points they wish to use. Note: Only one of amount, points, or holdReference must be provided for the redemption.'
                  example: 0
                holdReference:
                  type: string
                  description: 'A unique reference obtained from the Hold Points API. If provided, the points in the hold will be used. It is used when points have been reserved previously, allowing the system to redeem the points that are on hold. Example: If you previously used the Hold Points API to hold 100 points, you would provide the holdReference obtained from that hold transaction to redeem the 100 points that were held. Note: Only one of amount, points, or holdReference must be provided for the redemption.'
                  example: null
                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.
                hash:
                  type: string
                  description: A unique, rotating number generated for each customer, used as an additional layer of verification during redemptions. For more details on how the hash is generated and validated, refer to the Customer's Hash section.
                  example: HASH1234
                otp:
                  type: string
                  description: One-time password (OTP) required if OTP is enabled for the customer. This OTP serves as an additional layer of security for verifying the redemption request. For more details on how OTP works and when it is required, refer to the Transaction Validation section.
                  example: '123456'
                ignoreOTP:
                  type: boolean
                  description: This attribute allows you to skip OTP verification when set to true. If not provided or set to false, OTP verification will be required for accounts configured to use OTP.
                  example: false
                reason:
                  type: string
                  maxLength: 255
                  description: An optional reason for the redemption. This can be used to provide context about why the customer is redeeming points (e.g., 'Discount on order', 'Loyalty reward'). The reason will be stored with the transaction and displayed in the dashboard transaction details.
                  example: 'Discount on order #12345'
      responses:
        '200':
          description: Points redeemed 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: string
                    description: Unique identifier for the transaction in the Gameball system.
                    example: '11034734'
                  transactionId:
                    type: string
                    description: A unique identifier for the transaction in your system (e.g., order number or invo

# --- truncated at 32 KB (306 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/gameball/refs/heads/main/openapi/gameball-integrations-api-openapi.yml