Payment Tracking

Create orders in Gameball to award points for customer purchases. This API is used to track orders and reward customers for their completed purchases.

Available APIs

Track Payment

POST - Track Payment

https://api.gameball.co/api/v4.0/integrations/payments

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: Requires apikey and secretkey headers.

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

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.

email string Optional Customer's email address.

Note: This is required if your account uses email-based channel merging.

mobile string Optional Customer's mobile number.

Note: 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, 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 Optional 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.

totalDiscount float Optional Total discount applied to the payment.

totalProcessingFees float Optional Total processing feest associated with the payment.

totalTax float Optional Total tax amount for the payment.

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

paymentDetails object

serviceId string Optional Unique identifier for the service.

serviceName string Optional service title or name.

serviceProvider string Optional 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.

amount float Optional The original amount of a single service before any tax or discount is applied. This reflects the cost the service, not the total for multiple quantities in an payment.

tax float Optional The total amount of taxes applied to the service. This amount must be positive and reflects the total taxes.

discount float Optional The total discount applied to this service, expressed as a positive value. This amount should reflect the total discounts.

tags array Optional Tags associated with the service for categorization or promotional purposes.

category array Optional Service category, such as Telecom top-up or electricity. It can include one or multiple categories. Example: ["Telecom Top-up", "Internet Bill", "Streaming Subscription"]

extra object Optional 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 Optional Redemption details for the payment, including points held for redemption.

redemption object

pointsHoldReference string Optional 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.

couponsLockReference string Optional 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".

{
  "lockReference": "abc123def456"
}

couponCodes array Optional

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.

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:

{
  "couponCodes": ["DISCOUNT10", "FREEFEES2024"]
}

merchant object Optional 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 object

uniqueId string Optional Unique identifier for the merchant.

name string Optional Name of the merchant.

branch.uniqueId string Required Unique identifier for the branch where the payment took place.

branch.name string Optional Name of the branch where the payment took place.

guest boolean Optional 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 Optional 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 payment 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 Optional This object contains configurations related to the cashback settings.

cashbackConfigurations object

returnWindow int Optional 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 Optional 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.

{
  "billingAddress": "Jane Smith, Acme Corp, 456 Elm St, Springfield, IL 62704, USA, Tax ID: US987654321",
  "paymentStatus": "Pending"
}

Sample Request

{
  "customerId": "cust456", 
  "email": "john.doe@example.com",
  "mobile": "+1234567890",
  "paymentId": "6253e03b",
  "paymentDate": "2024-09-21T16:53:28.190Z",
  "totalAmount": 120,
  "totalPaid": 100,
  "totalTaxes": 10,
  "totalProcessingFees": 10, 
  "totalDiscount": 20, 
  "paymentDetails": [
    {
      "amount": 100,
      "tax": 10,
      "discount": 20,
      "serviceId": "s_1234",
      "serviceName": "Vodafone Topup",
      "serviceProvider": "Vodafone",
      "category": ["Telecom Topup"],
      "tags": ["Telecom", "Topup"],
      "extra": {}
    }
  ],
  "redemption": {
    "pointsHoldReference": "HOLD123",
    "couponsLockReference": "LOCK123",
    "couponCodes": [
      "DISCOUNT10"
    ]
  },
  "cashbackConfigurations": {
    "returnWindow": 7
  },
  "guest": false,
  "channel": "web",
  "extra": {
    "billingAddress": "Jane Smith, Acme Corp, 456 Elm St, Springfield, IL 62704, USA, Tax ID: US987654321",
    "paymentStatus": "Pending"
  }
}

Response

application/json

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 $1 spent, and a customer complete 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 object

serviceId string Unique identifier for the service.

decimalPoints number Fractional points rewarded for this line item.

points number Any points rewarded for this line item.

score number Any score awarded for the line item, if applicable.

Sample Response

{
    "customerId": "cust_123456789",
    "redeemedPoints": 1000,
    "rewardedPoints": 101,
    "paymentDetails": [
        {
            "serviceId": "service_123",
            "decimalPoints": 91.25,
            "points": 91,
            "score": 0
        },
        {
            "productId": "Fees",
            "decimalPoints": 10.0,
            "points": 10,
            "score": 0
        }
    ]
}

PreviousPayment NextTransactions

Last updated 2 days ago