---
title: "Initiate a transfer return"
method: POST
path: "/v1/transfer-returns"
tags: ["Accounts and money", "Founder login"]
---

# Initiate a transfer return

`POST /v1/transfer-returns`

## Request

- Base URL: `https://hyperscale0.ai`
- URL: `https://hyperscale0.ai/v1/transfer-returns`
- Auth: HTTP bearer

Opens a return against a posted transfer, or against a completed payout by also naming the payout. Admission enforces the per-reason time window against the posted moment. No money moves until the return completes: in sandbox the next clock advance or maintenance tick completes it, and in live Hyperscale operations complete it once the provider settles the return. waitsFor names which. A return may target a reversal's compensating transfer, but a return of a return is refused: the original return is dishonored instead. A transfer that already has a refund, reversal or adjustment is refused with transfer_lineage_conflict.

## Headers

- `X-Hyperscale-Environment` 'sandbox' | 'live'
- `Idempotency-Key` string, required

## Request body

- object
  - `returnId` string: Hyperscale transfer return ID
  - `originalTransferId` string, required: Hyperscale transfer ID
  - `reason` 'insufficient_funds' | 'account_closed' | 'no_account' | 'invalid_account' | 'balance_cap_exceeded' | 'unauthorized' | 'other', required

## Response `201`

Success

- TransferReturnCreateOutput
  - `returnId` string, required: Hyperscale transfer return ID
  - `tenantId` string, required: Organization tenant ID
  - `originalTransferId` string, required: Hyperscale transfer ID
  - `reason` 'insufficient_funds' | 'account_closed' | 'no_account' | 'invalid_account' | 'balance_cap_exceeded' | 'unauthorized' | 'other', required
  - `windowExpiresAt` string, date-time, required
  - `returnStatus` 'initiated', required
  - `waitsFor` 'sandbox_clock_advance' | 'provider_settlement', required: What completes the return. In sandbox, the next sandbox clock advance or maintenance tick, within about a minute. In live, the provider settling the return, after which Hyperscale operations complete it.

## Other responses

- `default`: ErrorResponse. See x-error-codes and x-errors for codes, HTTP statuses and retry guidance.

---

[API](https://skmtc.dev/hyperscale0/apis/hyperscale-product-api.md) · [All operations](https://skmtc.dev/hyperscale0/apis/hyperscale-product-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hyperscale0/apis/hyperscale-product-api/revisions/e9e8faa044d5?raw)