Returns

Create return

Changed on

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

post/v1/returns

Request

  • Base URL
    https://api.augustus.com
  • URL
    https://api.augustus.com/v1/returns
  • Auth
    HTTP bearer

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.

metadataobject nullable

Set of up to 50 key-value string pairs you can attach to store structured information, such as correlating this resource with an object in your own system. Keys may be up to 40 characters and values up to 500 characters.

Example request

{
  "deposit_id": "550e8400-e29b-41d4-a716-446655440004",
  "metadata": {
    "invoice_id": "INV-2026-0042"
  }
}

Response

Success

idstring uuid required

Unique identifier of the return.

type'return' required

Resource type discriminator.

status'initiated' | 'submitted' | '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.

rail'sepa' | 'sepa_instant' | 'faster_payments' | 'swift' | 'internal' | 'target' | 'ach' | 'fedwire' | 'bitcoin' | 'bitcoin_testnet4' | 'ethereum' | 'ethereum_sepolia' | 'solana' | 'solana_devnet' | 'polygon' | 'polygon_amoy' | 'null' nullable required

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

metadataobject required

Set of up to 50 key-value string pairs you can attach to store structured information, such as correlating this resource with an object in your own system. Keys may be up to 40 characters and values up to 500 characters.

Example response

{
  "id": "550e8400-e29b-41d4-a716-446655440005",
  "status": "sent",
  "deposit_id": "550e8400-e29b-41d4-a716-446655440004",
  "amount": "100.50",
  "currency": "USD",
  "initiated_at": "2026-01-15T10:30:00Z",
  "sent_at": "2026-01-15T10:35:00Z",
  "rail": "ach",
  "metadata": {
    "invoice_id": "INV-2026-0042"
  }
}

Changes