Augustus Returns API
The Returns API from Augustus — 2 operation(s) for returns.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/augustus:augustus-returns-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Augustus Banking Returns API
description: Augustus Banking API
version: 0.1.0
contact:
name: Augustus
url: https://docs.augustus.com
email: developer@augustus.com
servers:
- url: https://api.augustus.com
description: Production
- url: https://api.sandbox.augustus.com
description: Sandbox
security:
- BearerAuth: []
tags:
- name: Returns
paths:
/v1/returns:
get:
description: Lists deposit returns for the merchant with cursor-based pagination.
operationId: ReturnsController_list
parameters:
- name: limit
required: false
in: query
description: Number of results per page (1-100). Defaults to 10.
schema:
minimum: 1
maximum: 100
default: 10
type: integer
- name: cursor
required: false
in: query
description: Opaque cursor from a previous next_cursor.
schema:
type: string
- name: status
required: false
in: query
description: Filter by return status.
schema:
example: sent
type: string
enum:
- initiated
- submitted
- sent
- failed
- returned
- name: deposit_id
required: false
in: query
description: Filter returns belonging to this deposit.
schema:
format: uuid
example: 550e8400-e29b-41d4-a716-446655440004
type: string
- name: created_at.gte
required: false
in: query
description: Include returns whose created_at is greater than or equal to this ISO 8601 timestamp.
schema:
format: date-time
example: '2026-01-01T00:00:00Z'
type: string
- name: created_at.lte
required: false
in: query
description: Include returns whose created_at is less than or equal to this ISO 8601 timestamp.
schema:
format: date-time
example: '2026-02-01T00:00:00Z'
type: string
responses:
'200':
description: Paginated list of returns
content:
application/json:
schema:
$ref: '#/components/schemas/ListReturnsResponseDto'
summary: List returns
tags:
- Returns
post:
description: Initiates a return of funds from a deposit to the source.
operationId: ReturnsController_create
parameters:
- name: Idempotency-Key
in: header
description: 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.
required: true
schema:
type: string
requestBody:
required: true
description: Deposit to return and optional payment rail.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateReturnBodyDto'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ReturnResourceDto'
summary: Create return
tags:
- Returns
/v1/returns/{id}:
get:
description: Retrieves a return by ID.
operationId: ReturnsController_retrieve
parameters:
- name: id
required: true
in: path
description: Unique identifier of the return.
schema:
format: uuid
example: 550e8400-e29b-41d4-a716-446655440005
type: string
responses:
'200':
description: The return resource
content:
application/json:
schema:
$ref: '#/components/schemas/ReturnResourceDto'
summary: Retrieve return
tags:
- Returns
components:
schemas:
ReturnResourceDto:
type: object
properties:
id:
type: string
format: uuid
description: Unique identifier of the return.
example: 550e8400-e29b-41d4-a716-446655440005
type:
type: string
description: Resource type discriminator.
enum:
- return
status:
type: string
enum:
- initiated
- submitted
- sent
- failed
- returned
description: Current status of the return.
example: sent
deposit_id:
type: string
format: uuid
description: ID of the parent deposit.
example: 550e8400-e29b-41d4-a716-446655440004
amount:
type: string
description: Amount as a string decimal (e.g. "100.50").
example: '100.50'
currency:
type: string
enum:
- EUR
- GBP
- USD
- USDC
description: Currency code (ISO 4217 or crypto).
example: USD
failure:
type: object
properties:
code:
type: string
enum:
- account_closed
- account_blocked
- insufficient_funds
- invalid_account_format
- invalid_routing_number
- invalid_instruction
- invalid_amount
- invalid_time
- duplicate_transaction
- payee_verification_failed
- system_error
- provider_system_error
- rejected_by_correspondent_bank
- blocked_by_review
- unknown
description: Failure code.
message:
type: string
description: Human-readable description of the failure.
retry:
type: boolean
description: Whether the return can be retried.
required:
- code
- message
- retry
additionalProperties: false
description: Failure details when status is failed, otherwise null.
example: null
nullable: true
initiated_at:
type: string
format: date-time
description: ISO 8601 UTC timestamp when the return was initiated.
example: '2026-01-15T10:30:00Z'
sent_at:
type: string
format: date-time
description: ISO 8601 UTC timestamp when the return was sent.
example: '2026-01-15T10:35:00Z'
nullable: true
tx_hash:
type: string
description: Transaction hash for crypto returns, or null when not known. Only blockchain rails support this field.
example: null
nullable: true
rail:
type: string
enum:
- sepa
- sepa_instant
- faster_payments
- swift
- internal
- target
- ach
- fedwire
- bitcoin
- bitcoin_testnet4
- ethereum
- ethereum_sepolia
- solana
- solana_devnet
- polygon
- polygon_amoy
- null
description: Payment scheme or blockchain used for the return, or null when unknown.
example: ach
nullable: true
metadata:
type: object
additionalProperties:
type: string
maxLength: 500
description: 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:
invoice_id: INV-2026-0042
required:
- id
- type
- status
- deposit_id
- amount
- currency
- failure
- initiated_at
- sent_at
- tx_hash
- rail
- metadata
additionalProperties: false
ListReturnsResponseDto:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: string
format: uuid
description: Unique identifier of the return.
example: 550e8400-e29b-41d4-a716-446655440005
type:
type: string
description: Resource type discriminator.
enum:
- return
status:
type: string
enum:
- initiated
- submitted
- sent
- failed
- returned
description: Current status of the return.
example: sent
deposit_id:
type: string
format: uuid
description: ID of the parent deposit.
example: 550e8400-e29b-41d4-a716-446655440004
amount:
type: string
description: Amount as a string decimal (e.g. "100.50").
example: '100.50'
currency:
type: string
enum:
- EUR
- GBP
- USD
- USDC
description: Currency code (ISO 4217 or crypto).
example: USD
failure:
type: object
properties:
code:
type: string
enum:
- account_closed
- account_blocked
- insufficient_funds
- invalid_account_format
- invalid_routing_number
- invalid_instruction
- invalid_amount
- invalid_time
- duplicate_transaction
- payee_verification_failed
- system_error
- provider_system_error
- rejected_by_correspondent_bank
- blocked_by_review
- unknown
description: Failure code.
message:
type: string
description: Human-readable description of the failure.
retry:
type: boolean
description: Whether the return can be retried.
required:
- code
- message
- retry
additionalProperties: false
description: Failure details when status is failed, otherwise null.
example: null
nullable: true
initiated_at:
type: string
format: date-time
description: ISO 8601 UTC timestamp when the return was initiated.
example: '2026-01-15T10:30:00Z'
sent_at:
type: string
format: date-time
description: ISO 8601 UTC timestamp when the return was sent.
example: '2026-01-15T10:35:00Z'
nullable: true
tx_hash:
type: string
description: Transaction hash for crypto returns, or null when not known. Only blockchain rails support this field.
example: null
nullable: true
rail:
type: string
enum:
- sepa
- sepa_instant
- faster_payments
- swift
- internal
- target
- ach
- fedwire
- bitcoin
- bitcoin_testnet4
- ethereum
- ethereum_sepolia
- solana
- solana_devnet
- polygon
- polygon_amoy
- null
description: Payment scheme or blockchain used for the return, or null when unknown.
example: ach
nullable: true
metadata:
type: object
additionalProperties:
type: string
maxLength: 500
description: 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:
invoice_id: INV-2026-0042
required:
- id
- type
- status
- deposit_id
- amount
- currency
- failure
- initiated_at
- sent_at
- tx_hash
- rail
- metadata
additionalProperties: false
has_more:
type: boolean
next_cursor:
type: string
example: eyJsYXN0X2lkIjoiNTUwZTg0MDAtZTI5Yi00MWQ0LWE3MTYtNDQ2NjU1NDQwMDA2In0
nullable: true
has_previous:
type: boolean
previous_cursor:
type: string
example: eyJsYXN0X2lkIjoiNTUwZTg0MDAtZTI5Yi00MWQ0LWE3MTYtNDQ2NjU1NDQwMDA2In0
nullable: true
required:
- data
- has_more
- next_cursor
- has_previous
- previous_cursor
additionalProperties: false
CreateReturnBodyDto:
type: object
properties:
deposit_id:
type: string
format: uuid
description: Deposit to return funds from.
example: 550e8400-e29b-41d4-a716-446655440004
metadata:
type: object
propertyNames:
type: string
maxLength: 40
additionalProperties:
type: string
maxLength: 500
description: 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:
invoice_id: INV-2026-0042
nullable: true
required:
- deposit_id
additionalProperties: false
securitySchemes:
BearerAuth:
scheme: bearer
bearerFormat: JWT
type: http
description: Bearer token for authentication with Augustus Banking API
x-provenance:
method: harvested
publisher: Augustus
source: https://api.augustus.com/openapi/2026-05-01.json
note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
stamped by stamp-openapi-provenance.py (roadmap#793)