> ## 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.
# Payment Tracking
> Create payments in Gameball to award points for customer transactions.
Create payments in Gameball to award points for customer transactions. This API is used to track payments and reward customers for their completed transactions.
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.
**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.
For more information, head to the [Omni-Channel Handling Guide](/tutorials/experiences/more/omni-channel).
## Request Body
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.
Customer's email address.
This is required if your account uses email-based channel merging.
Customer's mobile number.
This is required if your account uses mobile-based channel merging.
Unique identifier for the payment on your system.
Timestamp of when the payment was occurred.
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. This is the value used to calculate any points or rewards earned from the payment.
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.
Total discount applied to the payment.
Total processing fees associated with the payment.
Total tax amount for the payment.
An array containing details about each element in the payment bill. If not provided, the calculation will only consider the total payment values.
Unique identifier for the service.
Service title or name.
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.
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.
The total amount of taxes applied to the service. This amount must be positive and reflects the total taxes.
The total discount applied to this service, expressed as a positive value. This amount should reflect the total discounts.
Tags associated with the service for categorization or promotional purposes.
Service category, such as Telecom top-up or electricity. It can include one or multiple categories. Example: `["Telecom Top-up", "Internet Bill", "Streaming Subscription"]`
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`.
Redemption details for the payment, including points held for redemption.
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**.
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"`.
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"]`
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.
Unique identifier for the merchant.
Name of the merchant.
Unique identifier for the branch where the payment took place.
Name of the branch where the payment took place.
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.
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 (POS) system, such as at a physical store or outlet.
* `web`: The payment was placed through your website.
* `callcenter`: The payment was placed over the phone by contacting a customer service representative or a call center.
This object contains configurations related to the cashback settings.
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)**.
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.
## Response
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.
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.
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.
Details about each service in the payment, including points rewarded.
Unique identifier for the service.
Fractional points rewarded for this line item.
Any points rewarded for this line item.
Any score awarded for the line item, if applicable.
## OpenAPI
````yaml POST /api/v4.0/integrations/payments
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/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.
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
security:
- apiKey: []
secretKey: []
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
apiKey:
type: apiKey
in: header
name: apikey
secretKey:
type: apiKey
in: header
name: secretkey
````