---
title: "List returns"
method: GET
path: "/returns"
tags: ["Returns"]
---

# List returns

`GET /returns`

List and filter returns.

## Query parameters

- `limit` integer
- `starting_after` string
- `sort_order` 'asc' | 'desc'
- `connected_account_id` string
- `type` 'sepa' | 'sepa_instant'
- `return_type` 'return' | 'refund' | 'reversal'
- `status` 'pending' | 'sent' | 'processing' | 'executed' | 'received' | 'rejected'
- `related_payment_id` string, uuid
- `related_payment_type` string
- `start_date` string, date
- `end_date` string, date
- `start_value_date` string, date
- `end_value_date` string, date
- `direction` 'credit' | 'debit'
- `reconciliation_status` 'reconciled' | 'partially_reconciled' | 'unreconciled' | 'excluded'
- `file_id` string
- `aggregation_reference` string
- `validation.type` 'internal_account_is_active' | 'direct_debit_mandate_is_active' | 'liquidity_screening' | 'sanctions_screening' | 'risk_screening' | 'limits_screening' | 'mambu_authorization'
- `validation.status` 'queued' | 'in_progress' | 'successful' | 'failed' | 'pending_investigation' | 'pending_retry' | 'canceled' | 'technical_error'

## Response `200`

List of filtered returns.

- ReturnSearchResult
  - `records` ReturnDetails[], required
    - `id` string, uuid, required — The UUID of the return.
    - `object` 'return', required — Label used to identify this kind of object
    - `type` 'sepa' | 'sepa_instant', required — The payment scheme or network. Only `sepa` and `sepa_instant` are supported for now.
    - `direction` 'credit' | 'debit', required — The direction of the return. `credit` for credit transfer returns (SCT/SCT Inst), and `debit` for direct debit returns (SDD).
    - `return_type` 'return' | 'refund' | 'reversal', required — The type of the return. Authorized values include `return`, `refund` and `reversal`. Only available when related payment is a direct debit.
    - `connected_account_id` string, uuid, required — The ID of the connected account.
    - `related_payment_id` string, uuid, required — The ID of the payment being returned, either an incoming payment or a payment order.
    - `related_payment_type` 'payment_order' | 'incoming_payment', required — The type of the payment corresponding to the return. It can be an incoming payment or a payment orders.
    - `return_reason` string, required — The reason for returning the payment. Authorised reasons depend on the payment scheme. For SEPA, refer to [SEPA reason codes](https://docs.numeral.io/reference/sepa-reason-codes).
    - `status` 'received' | 'pending-approval' | 'approved' | 'canceled' | 'failed' | 'processing' | 'sent' | 'executed' | 'rejected', required — The lifecycle stage of this return. It will be updated as the return is processed. See [return's lifecycle](https://docs.numeral.io/reference/returns-lifecycle).
    - `status_details` string, required — The details of the status of this return.
    - `metadata` object, required — Additional client data in JSON format. See [Metadata](https://docs.numeral.io/reference/metadata).
    - `bank_data` object, required — Bank data, such as message and transaction IDs, in JSON format.
      - `file_id` string, uuid, required
      - `message_id` string, required
      - `transaction_id` string, required
      - `end_to_end_id` string, required
      - `file_reference` string
    - `value_date` string, date, required — The value date of the return.
    - `returned_amount` integer, required — The absolute value of the return in the specified currency's smallest unit. For euro payments, the smallest unit is cents. €20 is represented as 2000.
    - `currency` 'EUR', required — The currency of the return. Only `EUR` is supported for now.
    - `receiving_account_number` string, required — The account receiving the return.
    - `originating_account_number` string — The account number of the originator of the return.
    - `originating_account_holder_name` string — The holder name of the originating account.
    - `originating_account_bank_name` string, nullable — The bank name of the originating account.
    - `originating_account_bank_address` CommonAddress — The address of the account holder, as an address object.
      - `line_1` string — Line 1.
      - `line_2` string — Line 2.
      - `building_number` string — Building number.
      - `street_name` string — Street name.
      - `postal_code` string — Postal / zip code.
      - `region_state` string — Region or state.
      - `city` string — City.
      - `country` string — ISO 3166 alpha-2 country code.
      - `department` string, nullable — Department name or code.
      - `sub_department` string, nullable — Sub-department name.
      - `building_name` string, nullable — Name of the building.
      - `floor` string, nullable — Floor number or identifier.
      - `postal_box` string, nullable — Postal box.
      - `room` string, nullable — Room number.
      - `city_location_name` string, nullable — Specific city location or landmark.
      - `district_name` string, nullable — District name or administrative region.
    - `receiving_account_bank_name` string, nullable — The bank name of the receiving account.
    - `receiving_account_bank_address` CommonAddress — The address of the account holder, as an address object.
      - `line_1` string — Line 1.
      - `line_2` string — Line 2.
      - `building_number` string — Building number.
      - `street_name` string — Street name.
      - `postal_code` string — Postal / zip code.
      - `region_state` string — Region or state.
      - `city` string — City.
      - `country` string — ISO 3166 alpha-2 country code.
      - `department` string, nullable — Department name or code.
      - `sub_department` string, nullable — Sub-department name.
      - `building_name` string, nullable — Name of the building.
      - `floor` string, nullable — Floor number or identifier.
      - `postal_box` string, nullable — Postal box.
      - `room` string, nullable — Room number.
      - `city_location_name` string, nullable — Specific city location or landmark.
      - `district_name` string, nullable — District name or administrative region.
    - `reconciliation_status` 'unreconciled' | 'partially_reconciled' | 'reconciled' | 'excluded', required — The reconciliation status of the return, which is either `unreconciled`, `reconciled`, `partially_reconciled`, or `excluded`.
    - `reconciled_amount` integer, required — The amount that is already reconciled. It is the sum of the amount of the reconciliations related to this return.
    - `created_at` string, date-time, required — The UTC timestamp of the creation of this return.

## Other responses

- `400` — Validation error.
- `500` — Internal server error.

---

[API](https://skmtc.net/numeral/apis/payments.md) · [All operations](https://skmtc.net/numeral/apis/payments/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/numeral/payments/revisions/220f101cc2ef/schema)