Skip to main content
POST
/
api
/
v4.0
/
integrations
/
payments
cURL
curl --request POST \
  --url https://api.gameball.co/api/v4.0/integrations/payments \
  --header 'Content-Type: application/json' \
  --header 'apikey: <api-key>' \
  --data '
{
  "customerId": "cust456",
  "paymentId": "6253e03b",
  "paymentDate": "2024-09-21T16:53:28.190Z",
  "totalPaid": 100,
  "email": "john.doe@example.com",
  "mobile": "+1234567890",
  "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": {}
    }
  ],
  "redemption": {
    "pointsHoldReference": "HOLD123",
    "couponsLockReference": "LOCK123",
    "couponCodes": [
      "DISCOUNT10"
    ]
  },
  "extra": {
    "billingAddress": "Jane Smith, Acme Corp, 456 Elm St, Springfield, IL 62704, USA, Tax ID: US987654321",
    "paymentStatus": "Pending"
  },
  "merchant": {
    "uniqueId": "<string>",
    "name": "<string>",
    "branch": {
      "uniqueId": "<string>",
      "name": "<string>"
    }
  },
  "guest": false,
  "channel": "web",
  "cashbackConfigurations": {
    "returnWindow": 7
  }
}
'
{
  "customerId": "cust_123456789",
  "redeemedPoints": 1000,
  "rewardedPoints": 101,
  "paymentDetails": [
    {
      "serviceId": "service_123",
      "decimalPoints": 91.25,
      "points": 91,
      "score": 0
    }
  ]
}
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 Channel Merging Guide.

​
Request Body

​
customerId
string
required
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.
​
email
string
Customer’s email address.
This is required if your account uses email-based channel merging.
​
mobile
string
Customer’s mobile number.
This is required if your account uses mobile-based channel merging.
​
paymentId
string
required
Unique identifier for the payment on your system.
​
paymentDate
datetime
required
Timestamp of when the payment was occurred.
​
totalPaid
float
required
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,includingtaxesandprocessingfees.Ifa120, 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.
​
totalAmount
float
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,includingtaxesandprocessingfees.Ifa120, 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.
​
totalDiscount
float
Total discount applied to the payment.
​
totalProcessingFees
float
Total processing fees associated with the payment.
​
totalTax
float
Total tax amount for the payment.
​
paymentDetails
array
An array containing details about each element in the payment bill. If not provided, the calculation will only consider the total payment values.
​
paymentDetails[].serviceId
string
Unique identifier for the service.
​
paymentDetails[].serviceName
string
Service title or name.
​
paymentDetails[].serviceProvider
string
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.
​
paymentDetails[].amount
float
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.
​
paymentDetails[].tax
float
The total amount of taxes applied to the service. This amount must be positive and reflects the total taxes.
​
paymentDetails[].discount
float
The total discount applied to this service, expressed as a positive value. This amount should reflect the total discounts.
​
paymentDetails[].tags
array
Tags associated with the service for categorization or promotional purposes.
​
paymentDetails[].category
array
Service category, such as Telecom top-up or electricity. It can include one or multiple categories. Example: ["Telecom Top-up", "Internet Bill", "Streaming Subscription"]
​
paymentDetails[].extra
object
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
object
Redemption details for the payment, including points held for redemption.
​
redemption.pointsHoldReference
string
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.
​
redemption.couponsLockReference
string
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".
​
redemption.couponCodes
array
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"]
​
merchant
object
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.
​
merchant.uniqueId
string
Unique identifier for the merchant.
​
merchant.name
string
Name of the merchant.
​
merchant.branch.uniqueId
string
required
Unique identifier for the branch where the payment took place.
​
merchant.branch.name
string
Name of the branch where the payment took place.
​
guest
boolean
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.
​
channel
string
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.
​
cashbackConfigurations
object
This object contains configurations related to the cashback settings.
​
cashbackConfigurations.returnWindow
int
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).
​
extra
object
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

​
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.
​
redeemedPoints
number
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.
​
rewardedPoints
number
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 1spent,andacustomercompletesapaymentworth1 spent, and a customer completes a payment worth 50, the rewardedPoints for this order would be 500 points.
​
paymentDetails
array
Details about each service in the payment, including points rewarded.
​
paymentDetails[].serviceId
string
Unique identifier for the service.
​
paymentDetails[].decimalPoints
number
Fractional points rewarded for this line item.
​
paymentDetails[].points
number
Any points rewarded for this line item.
​
paymentDetails[].score
number
Any score awarded for the line item, if applicable.

Authorizations

​
apikey
string
header
required

Body

application/json
​
customerId
string
required

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"

​
paymentId
string
required

Unique identifier for the payment on your system.

Example:

"6253e03b"

​
paymentDate
string<date-time>
required

Timestamp of when the payment was occurred.

Example:

"2024-09-21T16:53:28.190Z"

​
totalPaid
number
required

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

​
email
string

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

Example:

"john.doe@example.com"

​
mobile
string

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

Example:

"+1234567890"

​
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. 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
number

Total discount applied to the payment.

Example:

20

​
totalProcessingFees
number

Total processing fees associated with the payment.

Example:

10

​
totalTax
number

Total tax amount for the payment.

Example:

10

​
paymentDetails
object[]

An array containing details about each element in the payment bill. If not provided, the calculation will only consider the total payment values.

​
redemption
object

Redemption details for the payment, including points held for redemption.

​
extra
object

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
object

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.

​
guest
boolean

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
enum<string>

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).

Available options:
mobile,
pos,
web,
callcenter
Example:

"web"

​
cashbackConfigurations
object

This object contains configurations related to the cashback settings.

Response

200 - application/json

Payment tracked

​
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.

Example:

"cust_123456789"

​
redeemedPoints
number

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
number

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
object[]

Details about each service in the payment, including points rewarded.