Skip to main content
POST
/
api
/
v4.0
/
integrations
/
transactions
/
refund
cURL
curl --request POST \
  --url https://api.gameball.co/api/v4.0/integrations/transactions/refund \
  --header 'Content-Type: application/json' \
  --header 'apikey: <api-key>' \
  --data '
{
  "customerId": "cust_12345abc",
  "refundTransactionId": "txn987657111",
  "reverseTransactionId": "txn6342347194477",
  "transactionTime": "2024-10-13T17:11:00.249Z",
  "email": "john.doe@example.com",
  "mobile": "+1234567890",
  "refundAmount": 15,
  "merchant": {
    "uniqueId": "<string>",
    "name": "<string>",
    "branch": {
      "uniqueId": "<string>",
      "name": "<string>"
    }
  },
  "lineItems": [
    {
      "productId": "<string>",
      "quantity": 123,
      "price": 123,
      "sku": "<string>",
      "tags": [
        "<string>"
      ],
      "category": [
        "<string>"
      ],
      "weight": 123,
      "vendor": "<string>",
      "collection": [
        "<string>"
      ],
      "title": "<string>",
      "taxes": 123,
      "discount": 123,
      "extra": {}
    }
  ]
}
'
{
  "gameballTransactionId": "11034735",
  "refundTransactionId": "txn987657111",
  "refundAmount": 15,
  "refundEquivalentPoints": 150
}

​
Refund

Process refunds for previous point redemption transactions.

Authorizations

​
apikey
string
header
required

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.

Example:

"cust_12345abc"

​
refundTransactionId
string
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.

Example:

"txn987657111"

​
reverseTransactionId
string
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.

Example:

"txn6342347194477"

​
transactionTime
string<date-time>
required

The timestamp of the original transaction in your system (e.g., order datetime, invoice datetime).

Example:

"2024-10-13T17:11:00.249Z"

​
email
string

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

Example:

"john.doe@example.com"

​
mobile
string

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

Example:

"+1234567890"

​
refundAmount
number

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:

15

​
merchant
object

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.

​
lineItems
object[]

An array of items from the original transaction that are being refunded. If provided, only the items listed in this array will be refunded from the reverseTransactionId. If this field is not provided, the entire transaction specified by the reverseTransactionId will be refunded.

Response

200 - application/json

Refund processed successfully

​
gameballTransactionId
string

Unique identifier for the refund transaction in the Gameball system.

Example:

"11034735"

​
refundTransactionId
string

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.

Example:

"txn987657111"

​
refundAmount
number

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

Example:

15

​
refundEquivalentPoints
number

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:

150