---
title: "Create return request"
method: POST
path: "/return_requests"
tags: ["Return Requests"]
---

# Create return request

`POST /return_requests`

Create a return request for a payment order previously executed.

## Request body

- ReturnRequestCreationDetails
  - `related_payment_id` string, uuid, required — The ID of the payment order to be returned.
  - `return_reason` string, required — Authorised reasons depend on the payment scheme. For SEPA, refer to [SEPA reason codes](https://docs.numeral.io/reference/sepa-reason-codes).
  - `metadata` object — Additional client data in JSON format. See [Metadata](https://docs.numeral.io/reference/metadata).

## Response `200`

Successfully created return request.

- ReturnRequestDetails
  - `id` string, uuid, required — The UUID of the return request.
  - `object` 'return_request', 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.
  - `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 request. It can be an incoming payment or a payment order.
  - `return_reason` string, required — The reason for asking the payment's return. Authorised reasons depend on the payment scheme. For SEPA, refer to [SEPA reason codes](https://docs.numeral.io/reference/sepa-reason-codes).
  - `status` 'received' | 'accepted' | 'denied' | 'rejected' | 'pending' | 'failed' | 'sent', required — The lifecycle stage of this return request. It will be updated as the return request is processed. See [return request's lifecycle](https://docs.numeral.io/reference/returns-lifecycle).
  - `status_details` string, required — The details of the status of this return request.
  - `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
  - `created_at` string, date-time, required — The UTC timestamp of the creation of this return request.
  - `additional_information` string[], required — Additional free-text information provided by the bank when denying a return request (populated from the `<AddtlInf>` field of the inbound camt.029 message). Empty array when no additional information was provided.

## Other responses

- `400` — Validation error.
- `404` — The specified resource was not found.
- `409` — Conflict.
- `415` — Unsupported Media Type.
- `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)