Skip to main content
This guide provides a detailed walkthrough of how to integrate Gameball’s loyalty and rewards features into your payment processing flow. The integration covers various scenarios to enhance your customers’ experience, including loyalty point accumulation, coupon usage, and seamless redemption for fintech, SaaS, and service-based businesses.

​
Quick Overview

ScenarioUse CaseKey APIs
Basic PaymentEarn points on paymentPOST /api/v4.0/integrations/payments
With Points RedemptionRedeem points at checkoutPOST /api/v4.0/integrations/hold-points + POST /api/v4.0/integrations/payments
With Coupon CodesApply discount codesPOST /api/v4.0/integrations/coupons/{code}/validate + POST /api/v4.0/integrations/payments
Each scenario outlines a practical process that focuses on customer interactions, ensuring they can easily navigate loyalty rewards, coupons, and promotions as they complete their payments.

​
1️⃣ Submitting a Payment

Let’s explore how the Payments API works, starting with what your customers experience and how their actions on your fintech platform interact with Gameball to trigger rewards and campaigns.

​
Customer Journey

1

💳 Customer initiates payment

A customer, Sarah, visits your fintech platform and initiates a bill payment for her electricity bill.
2

💰 Customer completes payment

At checkout, she pays $120 for her electricity bill, including processing fees.
3

✅ Payment is confirmed

Sarah’s payment is confirmed and your system communicates with Gameball.

​
What Happens in the Background

The moment Sarah’s payment is completed, your platform communicates with Gameball through the Payments API. This triggers a payment_processed event in the background, sending details like:
Basic payment metadata including totals and timestamps:
{
  "paymentId": "PAY12345",
  "paymentDate": "2024-10-16T08:13:29.290Z",
  "totalPaid": 120.00,
  "totalAmount": 120.00,
  "totalProcessingFees": 2.50,
  "totalTax": 5.00
}
Detailed service information for each item in the payment:
{
  "paymentDetails": [
    {
      "serviceId": "ELEC001",
      "serviceName": "Electricity Bill",
      "serviceProvider": "PowerCo",
      "amount": 120.00,
      "category": ["Utilities"]
    }
  ]
}
Customer identifier to link the payment to the right profile:
{
  "customerId": "15327289462816"
}
Complete Payment Request: Here’s what the full API payload looks like when everything is combined: 
{
  "customerId": "15327289462816",
  "paymentId": "PAY12345",
  "paymentDate": "2024-10-16T08:13:29.290Z",
  "totalPaid": 120.00,
  "totalAmount": 120.00,
  "totalProcessingFees": 2.50,
  "totalTax": 5.00,
  "paymentDetails": [
    {
      "serviceId": "ELEC001",
      "serviceName": "Electricity Bill",
      "serviceProvider": "PowerCo",
      "amount": 120.00,
      "category": ["Utilities"]
    }
  ]
}

​
Gameball Processing

Once the payment_processed event is triggered:
1

Payment data mapping

The Payments API automatically sends the payment details to Gameball, mapping your payment attributes to event metadata.
2

Campaign evaluation

Gameball evaluates the payment metadata based on your configured campaigns.
3

Rewards issued

Sarah earns rewards, such as cashback or loyalty points, based on your Gameball settings.
For example, if you’ve configured a rewards campaign for customers making their first payment, Sarah earns a $10 cashback reward.

​
Seamless Automation

✅ With Payments API

Automated & Integrated
  • Auto reward triggering on payment
  • No manual event creation needed
  • Multi-module integration (cashback, campaigns)
  • Real-time balance updates
  • Instant payment-campaign linking

❌ Without Payments API

Manual & Fragmented
  • Manual event creation required
  • Complex multi-step tracking
  • Disconnected workflows
  • Delayed reward processing
  • Error-prone data entry
For instance:
  • If Sarah qualifies for cashback, Gameball calculates the amount and updates her balance instantly and you can display it using the Get Customer Balance API.
Want to show customers potential points before they complete a payment? Check out Previewing Potential Points to learn how to display points on payment pages.
Gameball widget displaying customer balance
This image showcases the Gameball widget displaying the customer’s balance. You can also retrieve the same information programmatically using the Get Customer Balance API for seamless integration with your application.
  • If you’re sending payment-based notifications, Sarah might receive a message like: “Congratulations, Sarah! You’ve earned 100 points for your last payment.”

​
Customer Experience

Sarah’s experience remains smooth and rewarding:
  1. She completes a payment without any extra steps
  2. She receives instant confirmation about her reward points or cashback, enhancing her satisfaction
  3. Over time, Sarah can redeem these points for discounts, keeping her engaged and loyal to your platform

​
Why This Matters

Seamless Customer ExperienceKeep customers engaged with rewards without adding friction to their payment journey.
Streamlined Internal ProcessesSave time with automatic data mapping and event creation—no manual work required.
Flexible Campaign TargetingTie specific payments or services to targeted campaigns, driving engagement effectively.
If you need to integrate points redemption or coupon codes with your payment submission, refer to these detailed guides:

Points Redemption

Learn how to integrate points redemption during payment submission, including how to hold points and link them to payments.

Coupon Codes

Discover how to validate, lock, and apply coupon codes when customers make payments.

​
🚀 Payment vs Orders

Understanding when to use Payments API vs Orders API:
AspectPayments APIOrders API
Use CaseBill payments, subscriptions, servicesProduct purchases, e-commerce
StructurepaymentDetails (services)lineItems (products)
IndustriesFintech, SaaS, utilitiesE-commerce, retail
Common FieldsserviceProvider, processingFeessku, vendor, shipping
Payments API is designed for non-commerce transactions like bill payments, subscription renewals, and service fees. Use the Orders API for e-commerce product purchases.