Rotessa API
Rotessa API from Rotessa — 9 path(s) described in OpenAPI.
OpenAPI Specification
# generated: '2026-07-24'
# method: generated
# source: https://rotessa.com/docs/
# note: Rotessa publishes no machine-readable OpenAPI. This spec is a faithful
# generation from the published Slate REST reference at https://rotessa.com/docs/
# (operations, parameters, auth, error format, and response codes as documented).
openapi: 3.1.0
info:
title: Rotessa API
version: v1
description: >-
The Rotessa API provides programmatic access to the core Rotessa platform for
collecting recurring payments directly from customers' bank accounts over
Canadian pre-authorized debit (PAD) and US ACH rails. It lets you manage
customers (bank-account holders), create one-time and recurring transaction
schedules against a customer's bank account, and query the resulting financial
transactions via the transaction report. Authentication is by API key placed in
the Authorization header. Faithful generation from https://rotessa.com/docs/.
contact:
name: Rotessa Support
url: https://support.rotessa.com/
email: support@rotessa.com
termsOfService: https://rotessa.com/legal/
servers:
- url: https://api.rotessa.com/v1
description: Production
- url: https://sandbox-api.rotessa.com/v1
description: Sandbox / test environment
security:
- apiKeyAuth: []
tags:
- name: Customers
description: Create, retrieve, and update the bank-account holders Rotessa withdraws from.
- name: Transaction Schedules
description: Create and manage one-time and recurring PAD/ACH transaction schedules.
- name: Transaction Report
description: Retrieve financial transaction records and their status for reconciliation.
paths:
/customers:
get:
operationId: listCustomers
tags: [Customers]
summary: Get all customers
description: Retrieve the list of customers associated with your Rotessa account.
responses:
'200':
description: A list of customers.
content:
application/json:
schema:
type: array
items: { $ref: '#/components/schemas/Customer' }
'401': { $ref: '#/components/responses/Unauthorized' }
'500': { $ref: '#/components/responses/InternalServerError' }
post:
operationId: createCustomer
tags: [Customers]
summary: Create a customer
description: >-
Create a customer (bank-account holder) that Rotessa can withdraw funds from.
Provide Canadian bank coordinates (institution_number, transit_number) or US
coordinates (routing_number, bank_account_type), plus the account_number.
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/CustomerCreate' }
responses:
'200':
description: The created customer.
content:
application/json:
schema: { $ref: '#/components/schemas/Customer' }
'400': { $ref: '#/components/responses/BadRequest' }
'401': { $ref: '#/components/responses/Unauthorized' }
'422': { $ref: '#/components/responses/UnprocessableEntity' }
patch:
operationId: updateCustomer
tags: [Customers]
summary: Update a customer via PATCH
description: Update an existing customer identified by its Rotessa customer id.
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/CustomerUpdate' }
responses:
'200':
description: The updated customer.
content:
application/json:
schema: { $ref: '#/components/schemas/Customer' }
'400': { $ref: '#/components/responses/BadRequest' }
'401': { $ref: '#/components/responses/Unauthorized' }
'404': { $ref: '#/components/responses/NotFound' }
'422': { $ref: '#/components/responses/UnprocessableEntity' }
/customers/{id}:
get:
operationId: getCustomer
tags: [Customers]
summary: Get a specific customer based on Rotessa ID
parameters:
- name: id
in: path
required: true
description: The ID of the customer to retrieve.
schema: { type: integer }
responses:
'200':
description: The requested customer.
content:
application/json:
schema: { $ref: '#/components/schemas/Customer' }
'401': { $ref: '#/components/responses/Unauthorized' }
'404': { $ref: '#/components/responses/NotFound' }
/customers/show_with_custom_identifier:
post:
operationId: showCustomerByCustomIdentifier
tags: [Customers]
summary: Get a specific customer based on custom identifier
description: Retrieve a customer by the merchant-supplied custom_identifier.
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [custom_identifier]
properties:
custom_identifier:
type: string
description: The custom identifier of the customer to retrieve.
responses:
'200':
description: The requested customer.
content:
application/json:
schema: { $ref: '#/components/schemas/Customer' }
'401': { $ref: '#/components/responses/Unauthorized' }
'404': { $ref: '#/components/responses/NotFound' }
/customers/update_via_post:
post:
operationId: updateCustomerViaPost
tags: [Customers]
summary: Update a customer via POST
description: >-
Update an existing customer using POST (for clients that cannot issue PATCH).
Identify the customer by its Rotessa id.
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/CustomerUpdate' }
responses:
'200':
description: The updated customer.
content:
application/json:
schema: { $ref: '#/components/schemas/Customer' }
'400': { $ref: '#/components/responses/BadRequest' }
'401': { $ref: '#/components/responses/Unauthorized' }
'404': { $ref: '#/components/responses/NotFound' }
'422': { $ref: '#/components/responses/UnprocessableEntity' }
/transaction_schedules:
post:
operationId: createTransactionSchedule
tags: [Transaction Schedules]
summary: Create a transaction schedule with Rotessa Customer ID
description: >-
Create a one-time or recurring transaction schedule against a customer's bank
account, identifying the customer by Rotessa customer_id.
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/TransactionScheduleCreate' }
responses:
'200':
description: The created transaction schedule.
content:
application/json:
schema: { $ref: '#/components/schemas/TransactionSchedule' }
'400': { $ref: '#/components/responses/BadRequest' }
'401': { $ref: '#/components/responses/Unauthorized' }
'422': { $ref: '#/components/responses/UnprocessableEntity' }
/transaction_schedules/create_with_custom_identifier:
post:
operationId: createTransactionScheduleWithCustomIdentifier
tags: [Transaction Schedules]
summary: Create a transaction schedule with custom identifier
description: >-
Create a transaction schedule identifying the customer by the merchant-supplied
custom_identifier instead of the Rotessa customer_id.
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/TransactionScheduleCreateWithCustomIdentifier' }
responses:
'200':
description: The created transaction schedule.
content:
application/json:
schema: { $ref: '#/components/schemas/TransactionSchedule' }
'400': { $ref: '#/components/responses/BadRequest' }
'401': { $ref: '#/components/responses/Unauthorized' }
'422': { $ref: '#/components/responses/UnprocessableEntity' }
/transaction_schedules/{id}:
get:
operationId: getTransactionSchedule
tags: [Transaction Schedules]
summary: Get a specific transaction schedule
parameters:
- name: id
in: path
required: true
description: The ID of the transaction schedule to retrieve.
schema: { type: integer }
responses:
'200':
description: The requested transaction schedule.
content:
application/json:
schema: { $ref: '#/components/schemas/TransactionSchedule' }
'401': { $ref: '#/components/responses/Unauthorized' }
'404': { $ref: '#/components/responses/NotFound' }
patch:
operationId: updateTransactionSchedule
tags: [Transaction Schedules]
summary: Update a specific transaction schedule with transaction ID
parameters:
- name: id
in: path
required: true
description: The ID of the transaction schedule to update.
schema: { type: integer }
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/TransactionScheduleUpdate' }
responses:
'200':
description: The updated transaction schedule.
content:
application/json:
schema: { $ref: '#/components/schemas/TransactionSchedule' }
'400': { $ref: '#/components/responses/BadRequest' }
'401': { $ref: '#/components/responses/Unauthorized' }
'404': { $ref: '#/components/responses/NotFound' }
'422': { $ref: '#/components/responses/UnprocessableEntity' }
delete:
operationId: deleteTransactionSchedule
tags: [Transaction Schedules]
summary: Delete a specific transaction schedule
parameters:
- name: id
in: path
required: true
description: The ID of the transaction schedule to delete.
schema: { type: integer }
responses:
'200':
description: The transaction schedule was deleted.
'401': { $ref: '#/components/responses/Unauthorized' }
'404': { $ref: '#/components/responses/NotFound' }
/transaction_schedules/update_via_post:
post:
operationId: updateTransactionScheduleViaPost
tags: [Transaction Schedules]
summary: Update a specific transaction schedule via POST
description: Update a transaction schedule using POST (for clients that cannot issue PATCH).
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/TransactionScheduleUpdate' }
responses:
'200':
description: The updated transaction schedule.
content:
application/json:
schema: { $ref: '#/components/schemas/TransactionSchedule' }
'400': { $ref: '#/components/responses/BadRequest' }
'401': { $ref: '#/components/responses/Unauthorized' }
'404': { $ref: '#/components/responses/NotFound' }
'422': { $ref: '#/components/responses/UnprocessableEntity' }
/transaction_report:
get:
operationId: showTransactionReport
tags: [Transaction Report]
summary: Show transaction report
description: >-
Retrieve financial transaction records and their status for reconciliation and
reporting. Paginated at 1000 transactions per page.
parameters:
- name: start_date
in: query
required: true
description: The earliest process date (YYYY-MM-DD) of the list of transactions.
schema: { type: string, format: date }
- name: end_date
in: query
required: false
description: The last process date (YYYY-MM-DD) of the list of transactions. Optional.
schema: { type: string, format: date }
- name: status
in: query
required: false
description: Filter by the given financial status of the transactions.
schema:
type: string
enum: [All, Pending, Approved, Declined, Chargeback]
default: All
- name: page
in: query
required: false
description: Page selected based on 1000 transactions per page.
schema: { type: integer, minimum: 1 }
responses:
'200':
description: A list of financial transactions.
content:
application/json:
schema:
type: array
items: { $ref: '#/components/schemas/FinancialTransaction' }
'401': { $ref: '#/components/responses/Unauthorized' }
'406': { $ref: '#/components/responses/NotAcceptable' }
components:
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: Authorization
description: >-
API key placed in the Authorization header in the form
`Authorization: Token token="<your_api_key>"`. Keys are created and revoked
in the Rotessa admin portal.
responses:
BadRequest:
description: Bad Request - your request includes invalid parameters.
content:
application/json:
schema: { $ref: '#/components/schemas/ErrorEnvelope' }
Unauthorized:
description: Unauthorized - your API key is not valid or is missing.
content:
application/json:
schema: { $ref: '#/components/schemas/ErrorEnvelope' }
NotFound:
description: Not Found - the specified resource could not be found.
content:
application/json:
schema: { $ref: '#/components/schemas/ErrorEnvelope' }
NotAcceptable:
description: Not Acceptable - you requested a format that isn't json.
content:
application/json:
schema: { $ref: '#/components/schemas/ErrorEnvelope' }
UnprocessableEntity:
description: Unprocessable Entity - your request results in invalid data.
content:
application/json:
schema: { $ref: '#/components/schemas/ErrorEnvelope' }
InternalServerError:
description: Internal Server Error - we had a problem with our server. Try again later.
schemas:
Address:
type: object
description: Customer address.
properties:
address_1: { type: string }
address_2: { type: string }
city: { type: string }
province_code: { type: string, description: Province/state code }
postal_code: { type: string }
country: { type: string }
Customer:
type: object
properties:
id: { type: integer, description: ID of the customer }
uuid: { type: string, description: UUID of the customer }
custom_identifier: { type: string, description: Your own unique customer identifier }
name: { type: string, description: Full name of customer }
email: { type: string, description: Customer email address }
customer_type: { type: string, enum: [Personal, Business] }
home_phone: { type: string }
phone: { type: string }
bank_name: { type: string }
institution_number: { type: string, description: Bank institution number for Canadian customers }
transit_number: { type: string, description: Bank transit number for Canadian customers }
bank_account_type: { type: string, enum: [Savings, Checking], description: For American customers }
authorization_type: { type: string, enum: ['In Person', 'Online'] }
routing_number: { type: string, description: Bank routing number for American customers }
account_number: { type: string, description: Bank account number }
address: { $ref: '#/components/schemas/Address' }
transaction_schedules:
type: array
items: { $ref: '#/components/schemas/TransactionSchedule' }
financial_transactions:
type: array
items: { $ref: '#/components/schemas/FinancialTransaction' }
CustomerCreate:
type: object
required: [name, account_number]
properties:
name: { type: string, description: Full name of customer }
custom_identifier: { type: string, description: Your own customer identifier. Must be unique. }
email: { type: string }
home_phone: { type: string }
phone: { type: string }
bank_name: { type: string }
institution_number: { type: string, description: Bank institution number for Canadian customers }
transit_number: { type: string, description: Bank transit number for Canadian customers }
bank_account_type: { type: string, enum: [Savings, Checking], description: For American customers }
authorization_type: { type: string, enum: ['In Person', 'Online'] }
routing_number: { type: string, description: Routing number for American customers }
account_number: { type: string, description: Bank account number }
address: { $ref: '#/components/schemas/Address' }
customer_type: { type: string, enum: [Personal, Business] }
CustomerUpdate:
allOf:
- type: object
properties:
id: { type: integer, description: The ID of the customer to update }
- $ref: '#/components/schemas/CustomerCreate'
TransactionSchedule:
type: object
properties:
id: { type: integer, description: ID of the transaction schedule }
uuid: { type: string, description: UUID of the transaction schedule }
amount: { type: number, description: Amount for schedule }
process_date: { type: string, description: The initial date to begin withdrawing funds }
frequency: { $ref: '#/components/schemas/Frequency' }
installments: { type: integer, description: The number of installments. Leave blank to continue indefinitely. }
comment: { type: string, description: A place to enter notes for the transaction schedule }
next_process_date: { type: string, description: The next date that funds will be withdrawn }
financial_transactions:
type: array
items: { $ref: '#/components/schemas/FinancialTransaction' }
TransactionScheduleCreate:
type: object
required: [customer_id, amount, process_date, frequency]
properties:
customer_id: { type: integer, description: ID of customer }
amount: { type: number, description: Amount for schedule }
process_date: { type: string, description: The initial date to begin withdrawing funds (e.g. November 20, 2016) }
frequency: { $ref: '#/components/schemas/Frequency' }
installments: { type: integer, description: The number of installments. If excluded, schedule is indefinite. }
comment: { type: string, description: Optional comment for schedule }
TransactionScheduleCreateWithCustomIdentifier:
type: object
required: [custom_identifier, amount, process_date, frequency]
properties:
custom_identifier: { type: string, description: Your own unique custom identifier for the customer }
amount: { type: number, description: Amount for schedule }
process_date: { type: string, description: The initial date to begin withdrawing funds }
frequency: { $ref: '#/components/schemas/Frequency' }
installments: { type: integer, description: The number of installments. If excluded, schedule is indefinite. }
comment: { type: string, description: Optional comment for schedule }
TransactionScheduleUpdate:
type: object
required: [id]
properties:
id: { type: integer, description: The ID of the transaction schedule to update }
amount: { type: number, description: Amount for the schedule }
comment: { type: string, description: Optional comment for schedule }
Frequency:
type: string
description: Frequency of the transaction schedule.
enum:
- Once
- Weekly
- Every Other Week
- Monthly
- Every Other Month
- Quarterly
- Semi-Annually
- Yearly
FinancialTransaction:
type: object
properties:
id: { type: integer, description: ID of the financial transaction }
uuid: { type: string, description: UUID of the financial transaction }
amount: { type: number, description: Transaction amount }
process_date: { type: string, description: The scheduled process date of the transaction }
status:
type: string
description: The current status of the transaction.
enum: [Future, Pending, Approved, Declined, Chargeback]
status_reason:
type: string
description: The reason for the Declined or Chargeback status of a transaction.
transaction_schedule_id: { type: integer, description: ID of the transaction schedule that created this transaction }
bank_name: { type: string }
institution_number: { type: string }
transit_number: { type: string }
account_number: { type: string }
ErrorEnvelope:
type: object
description: >-
Rotessa error envelope. Errors are returned as a list of objects each carrying
a machine-readable error_code and a human-readable error_message.
properties:
errors:
type: array
items:
type: object
properties:
error_code: { type: string, example: installments_required }
error_message: { type: string, example: Installments value must be at least 1. }