Refunds Report

Report refund transactions with Zotlo

This API service is a read-only reporting endpoint that allows you to query all refund transactions processed through Zotlo in a secure, performant, and scalable manner. It enables you to view refunds to users using various filters such as date range, package/product, and country. The endpoint allows you to fetch large volumes of refund records efficiently and manage your financial reporting and operational workflows smoothly.

The service operates with the GET method, and the main endpoint is as follows:

GET https://api.zotlo.com/v1/reports/activity/refund

Parameter	Description	Required
limit	The maximum number of records to return. (Default: 25, Max: 100)	Optional
country	Filters transactions by the country where the payment was processed.	Optional
package_id	Filters transactions by the associated package .	Optional
start_date	Lists transactions created after the specified date. (Format: Y-m-d)	Optional
end_date	Lists transactions created after the specified date. (Format: Y-m-d)	Optional
before	To navigate to the previous page, send the before cursor value returned in the previous response.	Required only during pagination step.
after	To navigate to the previous page, send the before cursor value returned in the previous response.	Required only during pagination step.

Example Request:

To send a request to the Transaction Report Service, you must include your Access Key, Access Secret, and App ID in the request headers. You can obtain these credentials from the Zotlo Panel → Developer Tools → API Keys section.

GET https://api.zotlo.com/v1/reports/activity/refund?limit=50?&start_date=2025-11-01&end_date=2025-11-30 HTTP/1.1
AccessKey: ••••••
AccessSecret: ••••••
Content-Type: application/json
ApplicationId: •
Language: ••

Successful Response Examples

{
  "meta": {
    "requestId": "5896c0267514-REQ-69246705a5ea3",
    "httpStatus": 200
  },
  "result": {
    "data": [
      {
        "teamId": 1,
        "appId": 1,
        "packageId": "web_premium",
        "subscriberId": "3a33eb5d-3e4b-4875-916f-7e9fb5867f3f",
        "transactionId": "29d557b4-2563-497b-ad1f-677ac6910b81",
        "country": "TR",
        "price": "200.00",
        "currency": "TRY",
        "exchangeRate": "[]",
        "reason": "{\"reason\":\"\",\"user\":\"API: \"}",
        "refundDate": "2025-11-10 08:28:08",
        "refundType": "REFUND"
      },
      {
        "teamId": 1,
        "appId": 1,
        "packageId": "web_premium",
        "subscriberId": "8aa4de92-a86d-4330-bb3c-6995a5f837ed",
        "transactionId": "6edc57b0-86a1-4ba7-bf9a-81d05afbf505",
        "country": "TR",
        "price": "200.00",
        "currency": "TRY",
        "exchangeRate": "[]",
        "reason": "{\"reason\":\"\",\"user\":\"API: \"}",
        "refundDate": "2025-11-10 08:26:59",
        "refundType": "REFUND"
      }
    ],
    "paging": {
      "cursors": {
        "previous": null,
        "next": "jxNrkD7SxgoepgGb9tOAdytGbmJYSkh2V2hsVC8xRVlXODZKRmZRMkw4Y1dHcWZ0em5YdmxBa3hqckx3MkxBUitRUjNzL2dkQ0gwa2N2MFBRT3lpbDlsNnFjODZ1OHJsdlI3TmY2S2ZjUlFqYnhBbS9SRG5kdHhocHM1aTJYaFBwNS9STkRwci9YYUp3N2FEODdjZ3FacFNhbVlmUEtRMlZscUR6eFdxNEdZdUhuNWI3SnF2UEJYa29FakcvMEZTbXhrSk1tdktTYjV4c085Q2lTVnN4elJtNll4aEFpSkJ3WWkrSVE9PQ"
      },
      "previous": "https://local-api.zotlo.com:39443/v1/reports/activity/refund",
      "next": "https://local-api.zotlo.com:39443/v1/reports/activity/refund?after=jxNrkD7SxgoepgGb9tOAdytGbmJYSkh2V2hsVC8xRVlXODZKRmZRMkw4Y1dHcWZ0em5YdmxBa3hqckx3MkxBUitRUjNzL2dkQ0gwa2N2MFBRT3lpbDlsNnFjODZ1OHJsdlI3TmY2S2ZjUlFqYnhBbS9SRG5kdHhocHM1aTJYaFBwNS9STkRwci9YYUp3N2FEODdjZ3FacFNhbVlmUEtRMlZscUR6eFdxNEdZdUhuNWI3SnF2UEJYa29FakcvMEZTbXhrSk1tdktTYjV4c085Q2lTVnN4elJtNll4aEFpSkJ3WWkrSVE9PQ"
    }
  }
}

Failed Response Example

In successful cases, our services return an HTTP status code of 200. In unsuccessful cases, an HTTP Status Code of 400 or 500 is returned. A sample error response is as follows.

{
  "meta": {
    "requestId": "5896c0267514-REQ-692464aa9a8c8",
    "httpStatus": 400,
    "errorMessage": "Invalid start_date format. Use Y-m-d",
    "errorCode": "400024"
  },
  "result": []
}

Failed Response Parameters

The parameters for unsuccessful requests are as follows. Failed requests return an error code of 400 or 500.

requestId	A unique ID assigned to every request. Used for identifying and tracking errors in system logs.
httpStatus	The HTTP status code of the error.
errorMessage	The error message returned by the API. You can view all error codes here.
errorCode	The error code provided by Zotlo for this specific error.