Skip to main content
When a customer returns items or cancels an order, use the Refund API to reverse the transaction. Gameball restores any points redeemed on the original order, deducts the points it earned, and keeps the customer’s balance accurate, which is essential for fair returns and clean financial reconciliation.

​
Refund an Order

curl -X POST 'https://api.gameball.co/api/v4.0/integrations/transactions/refund' \
  -H 'Content-Type: application/json' \
  -H 'APIKey: YOUR_API_KEY' \
  -H 'SecretKey: YOUR_SECRET_KEY' \
  -d '{
    "customerId": "12345",
    "refundTransactionId": "REFUND0001",
    "reverseTransactionId": "ORD000123",
    "transactionTime": "2025-10-19T12:30:00Z",
    "refundAmount": 100.00
  }'

{
  "gameballTransactionId": "11034735",
  "refundTransactionId": "REFUND0001",
  "refundAmount": 100.00,
  "refundEquivalentPoints": 100
}

​
Request Fields

​
customerId
string
required
The unique identifier for the customer.
​
refundTransactionId
string
required
A unique identifier for this refund transaction.
​
reverseTransactionId
string
required
The original orderId being refunded. Must match an existing order.
​
transactionTime
string
required
When the refund occurred, in ISO 8601 format.
​
refundAmount
number
required
The amount being refunded. Use the original order’s totalPaid for a full refund, or a smaller value for a partial refund.
Behind the scenes, Gameball reverses the original order, restores any points redeemed on it, deducts any points it earned, updates the balance, and records the refund in the transaction history. refundEquivalentPoints is the point value of the refunded amount.

​
Tips & Gotchas

  • Always use a unique refundTransactionId per refund.
  • reverseTransactionId must match an existing order ID.
  • Partial refunds are supported, adjust refundAmount accordingly.
  • Process refunds as soon as the return is confirmed.

Refund Transaction API

Complete API reference for refund transactions