Returns

Create return

Initiates a return of funds from a deposit to the source.

post/v1/returns

Headers

Idempotency-Keystring required

Idempotency key for safe retries. Reusing a key with an identical request body returns the cached response. Reusing a key with a different body returns 409.

Request body

deposit_idstring uuid required

Deposit to return funds from.

rail'sepa' | 'sepa_instant' | 'faster_payments' | 'null' nullable required

Payment scheme or blockchain used for the return, or null to let the platform choose.

Example request

{
  "deposit_id": "550e8400-e29b-41d4-a716-446655440004"
}

Response

Success

idstring uuid required

Unique identifier of the return.

type'return' required

Resource type discriminator.

status'initiated' | 'sent' | 'failed' | 'returned' required

Current status of the return.

deposit_idstring uuid required

ID of the parent deposit.

amountstring required

Amount as a string decimal (e.g. "100.50").

currency'EUR' | 'GBP' | 'USD' | 'USDC' required

Currency code (ISO 4217 or crypto).

initiated_atstring date-time required

ISO 8601 UTC timestamp when the return was initiated.

sent_atstring date-time nullable required

ISO 8601 UTC timestamp when the return was sent.

tx_hashstring nullable required

Transaction hash for crypto returns, or null when not known. Only blockchain rails support this field.

Payment scheme or blockchain used for the return, or null when unknown.

Example response

{
  "id": "550e8400-e29b-41d4-a716-446655440005",
  "deposit_id": "550e8400-e29b-41d4-a716-446655440004",
  "amount": "100.50",
  "currency": "EUR",
  "initiated_at": "2026-01-15T10:30:00Z",
  "sent_at": "2026-01-15T10:35:00Z"
}