Changed on

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.

post/api/v4.0/integrations/payments

Request

  • Base URL: https://api.gameball.co
  • URL: https://api.gameball.co/api/v4.0/integrations/payments
  • Auth: API key in header apikey and API key in header secretkey

Request body

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

emailstring

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

mobilestring

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

paymentIdstring required

Unique identifier for the payment on your system.

paymentDatestring date-time required

Timestamp of when the payment was occurred.

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

totalAmountnumber

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.

totalDiscountnumber

Total discount applied to the payment.

totalProcessingFeesnumber

Total processing fees associated with the payment.

totalTaxnumber

Total tax amount for the payment.

extraobject

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.

guestboolean

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'mobile' | 'pos' | 'web' | 'callcenter'

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 request

{
  "customerId": "cust456",
  "email": "john.doe@example.com",
  "mobile": "+1234567890",
  "paymentId": "6253e03b",
  "paymentDate": "2024-09-21T16:53:28.190Z",
  "totalPaid": 100,
  "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"
  },
  "channel": "web",
  "cashbackConfigurations": {
    "returnWindow": 7
  }
}

Response

Payment tracked

customerIdstring

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.

redeemedPointsnumber

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.

rewardedPointsnumber

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 response

{
  "customerId": "cust_123456789",
  "redeemedPoints": 1000,
  "rewardedPoints": 101,
  "paymentDetails": [
    {
      "serviceId": "service_123",
      "decimalPoints": 91.25,
      "points": 91
    }
  ]
}

Changes

  • 262228c13429Revision changes
    • info

      the endpoint scheme security apiKey AND secretKey was added to the API

    • info

      the endpoint scheme security apiKey was removed from the API

    • info

      the endpoint scheme security secretKey was removed from the API

  • 788718651767Revision changes
    • info

      removed the non-success response with the status