API Reference / Refunds REST

Actions

Lists refund transactions. Refunds are child payments with type REFUND linked to a SETTLED parent via parentPaymentId. Use parentPaymentId to retrieve all refunds for a specific payment.

GET/refunds

List Refunds

Headers

Authorizationstringrequired

Bearer access token returned by the authentication endpoint.

x-api-keystringrequired

The API key used for authentication when making requests to the API Gateway.

conomyhq-api-versionstring

API version selector for Conomy endpoints. Use 24-04-2025 for the current version.

User-Agentstringrequired

Identifies the application making the request.

Query parameters

parentPaymentIdstring

Filters refunds by the parent payment ID.

identityIdstring

Filters refunds by the identity that issued them.

accountNumberstring

Filters refunds by account number.

statusstring

Filters refunds by status (e.g. CREATED, SETTLED, FAILED).

startDatestring

(dd/mm/yyyy) Start date filter on createdAt.

endDatestring

(dd/mm/yyyy) End date filter on createdAt.

sortstring

Sorts results by field — param:asc | param:desc.

limitstring

Maximum number of items to return per page.

offsetstring

Number of items to skip (for pagination).

Responses

200Request processed successfully.

paginationobjectrequiredshow 4 properties

Cursor-based pagination metadata (limit, cursor, hasMore).

resultsobject[]requiredshow items

Refund payment objects for the current page.

400Invalid request parameters or payload.

errorobjectshow 2 properties

messagestringnullable

Human-readable message. May be null.

500Unexpected internal server error.

errorobjectshow 2 properties

messagestringnullable

Human-readable message. May be null.

Request

HTTPcurlTypeScriptPythonGoRust

GET /sandbox/refunds HTTP/1.1
Host: api.conomyhq.com
Authorization: Bearer {ACCESS_TOKEN}
x-api-key: {YOUR_API_KEY}
conomyhq-api-version: 24-04-2025
User-Agent: MyApp/1.0

curl -X GET \
  'https://api.conomyhq.com/sandbox/refunds' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {YOUR_API_KEY}' \
  -H 'conomyhq-api-version: 24-04-2025' \
  -H 'User-Agent: MyApp/1.0'

const response = await fetch('https://api.conomyhq.com/sandbox/refunds', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer {ACCESS_TOKEN}',
    'x-api-key': '{YOUR_API_KEY}',
    'conomyhq-api-version': '24-04-2025',
    'User-Agent': 'MyApp/1.0',
  },
});

const data = await response.json();

import requests

response = requests.get(
    'https://api.conomyhq.com/sandbox/refunds',
    headers={
    'Authorization': 'Bearer {ACCESS_TOKEN}',
    'x-api-key': '{YOUR_API_KEY}',
    'conomyhq-api-version': '24-04-2025',
    'User-Agent': 'MyApp/1.0',
    }
)

data = response.json()

package main

import (
	"encoding/json"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.conomyhq.com/sandbox/refunds", nil)
	req.Header.Set("Authorization", "Bearer {ACCESS_TOKEN}")
	req.Header.Set("x-api-key", "{YOUR_API_KEY}")
	req.Header.Set("conomyhq-api-version", "24-04-2025")
	req.Header.Set("User-Agent", "MyApp/1.0")

	client := &http.Client{}
	resp, _ := client.Do(req)
	defer resp.Body.Close()

	var data map[string]any
	json.NewDecoder(resp.Body).Decode(&data)
}

use reqwest::Client;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new();
    let resp = client
        .get("https://api.conomyhq.com/sandbox/refunds")
        .header("Authorization", "Bearer {ACCESS_TOKEN}")
        .header("x-api-key", "{YOUR_API_KEY}")
        .header("conomyhq-api-version", "24-04-2025")
        .header("User-Agent", "MyApp/1.0")
        .send()
        .await?;

    let data: serde_json::Value = resp.json().await?;
    Ok(())
}

Response

200 400 401 403 404 422 500

{
  "pagination": {
    "count": 0,
    "next": 0,
    "previous": 0,
    "total": 0
  },
  "results": [
    {
      "id": "string",
      "externalId": "string",
      "identityId": "string",
      "accountNumber": "string",
      "totalAmount": "string",
      "currency": "string",
      "status": "string",
      "type": "PURCHASE",
      "createdAt": "string",
      "updatedAt": "string"
    }
  ]
}

{
  "error": {
    "type": "bad_request",
    "info": null
  },
  "message": null
}

{
  "error": {
    "type": "unauthorized",
    "info": null
  },
  "message": null
}

{
  "error": {
    "type": "forbidden",
    "info": null
  },
  "message": null
}

{
  "error": {
    "type": "not_found",
    "info": null
  },
  "message": null
}

{
  "error": {
    "type": "validation_error",
    "info": {
      "field": "string",
      "message": "string"
    }
  },
  "message": null
}

{
  "error": {
    "type": "internal_error",
    "info": null
  },
  "message": null
}