POST /api/v4.0/integrations/transactions/refund

This API processes refunds or cancellations of cashback and points redemption transactions in Gameball. By providing a reverseTransactionId, Gameball identifies the related cashback or redemption transaction and adjusts the customer's points balance accordingly to reflect the refunded or canceled transaction.

post/api/v4.0/integrations/transactions/refund

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.

refundTransactionIdstring required

A unique identifier for the refund process transaction in your system (e.g., refund number or transaction ID). This ID helps track and reference the refund process itself. Example: If a refund is processed for an item, the refundTransactionId could be REFUND-98765, which refers to the specific new refund transaction.

reverseTransactionIdstring required

The unique transaction ID representing the original order being refunded, reversed, or canceled. This ID is sent as reverseTransactionId in the payload and links to the previous transaction. Example: If a customer requests a refund for an order previously made with transaction ID ORDER-12345, the reverseTransactionId will be ORDER-12345 to indicate which order is being refunded.

transactionTimestring date-time required

The timestamp of the original transaction in your system (e.g., order datetime, invoice datetime). Must be in UTC (ISO 8601 format).

refundAmountnumber

The amount to be refunded from the original transaction. The entire transaction is refunded if this field is not provided. Note: For a full refund, you can use any of the following approaches: Send the refund request without the refundAmount field, Send the refund request with refundAmount set to null, Send the refund request with refundAmount equal to the total paid in the original order.

Example request

{
  "customerId": "cust_12345abc",
  "email": "john.doe@example.com",
  "mobile": "+1234567890",
  "refundTransactionId": "txn987657111",
  "reverseTransactionId": "txn6342347194477",
  "transactionTime": "2024-10-13T17:11:00.249Z",
  "refundAmount": 15
}

Response

Refund processed successfully

gameballTransactionIdstring

Unique identifier for the refund transaction in the Gameball system.

refundTransactionIdstring

Unique identifier for the refund process transaction in your system (e.g., refund number or transaction ID). This ID helps track and reference the refund process itself. Example: If the refund process for an order has a transaction ID REFUND-54321, this ID will be used to track the refund operation.

refundAmountnumber

The amount refunded from the original transaction. Example: If a customer was originally charged $100 and you refunded $40, the refundAmount will be 40.

refundEquivalentPointsnumber

The number of points equivalent to the monetary value refunded in the transaction. Example: If $40 is refunded and your points-to-currency ratio is 1 point = $0.10, then the refundEquivalentPoints would be 400 points.

Example response

{
  "gameballTransactionId": "11034735",
  "refundTransactionId": "txn987657111",
  "refundAmount": 15,
  "refundEquivalentPoints": 150
}

Changes

Changed in 4 of the 38 revisions of this API.4314

Dec 17, 2025262228c134293See the full diff
- ○
  the endpoint scheme security apiKey AND secretKey was added to the API
  api-security-added
- ○
  the endpoint scheme security apiKey was removed from the API
  api-security-removed
- ○
  the endpoint scheme security secretKey was removed from the API
  api-security-removed
Sep 30, 20257887186517673310See the full diff
- ▲
  added the new required request property refundTransactionId
  new-required-request-property
- ▲
  added the new required request property reverseTransactionId
  new-required-request-property
- ▲
  added the new required request property transactionTime
  new-required-request-property
- ●
  removed the request property originalTransactionId
  request-property-removed
- ●
  removed the optional property refundedPoints from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property success from the response with the 200 status
  response-optional-property-removed
- ○
  added the new optional request property email
  new-optional-request-property
- ○
  added the new optional request property lineItems
  new-optional-request-property
- ○
  added the new optional request property merchant
  new-optional-request-property
- ○
  added the new optional request property mobile
  new-optional-request-property
- ○
  the request property refundAmount became optional
  request-property-became-optional
- ○
  removed the non-success response with the status 400
  response-non-success-status-removed
- ○
  added the optional property gameballTransactionId to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property refundAmount to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property refundEquivalentPoints to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property refundTransactionId to the response with the 200 status
  response-optional-property-added
Sep 10, 202595e7f65e5afd1See the full diff
- ○
  endpoint added
  endpoint-added
Sep 2, 2025919eb7a392aa1See the full diff
- ▲
  api path removed without deprecation
  api-path-removed-without-deprecation
This revision also has 38 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Full history