NAV
shell

Introduction

The Rotessa API allows access to the core Rotessa platform. The endpoints allow you to manage customers and transactions in the Rotessa system. Typical use of the API is as follows:

Authentication

Rotessa uses API keys to allow access to the API. API keys are unique tokens used by the API, placed in the request header that grant access to your Rotessa resources.

The Rotessa APi is located at https://api.rotessa.com/v1. The URL for our test environment is https://sandbox-api.rotessa.com/v1.

Access to the test environment can be granted by signing up at sandbox.rotessa.com. Once signed up, email support@rotessa.com with your username to get your sandbox account approved and to gain access to the API.

Generate an API key

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl "<rotessa_endpoint>/customers.json" -H "Authorization: Token token=\"<api_key>\""

Make sure to replace your_api_key with your API key.

Access the API Keys from your Rotessa admin portal: Screenshot of Example Documentation created with Slate

Existing API keys can be revoked and generated. Click Create API Key: Screenshot of Example Documentation created with Slate

Rotessa expects for the API key to be included in all API requests to the server in a header that looks like the following:

Token token="your_api_key"

Customers

Customers represent individual customer accounts from which you which to withdraw funds.

Field Description
id ID of the customer.
custom_identifier Your own unique customer identifier.
name Full name of customer.
email Customer email address.
customer_type Personal or Business
home_phone Home phone number.
cell_phone Cell phone number.
bank_name Bank name.
institution_number Bank institution number.
transit_number Bank transit number.
account_number Bank account number.
address Customer address.
transaction_schedules A list of transaction schedule objects describing the customer’s payment schedules.
financial_transactions A list of financial transactions that have occurred for a customer.

Get All Customers

curl "<rotessa_endpoint>/customers.json" -H "Authorization: Token token=\"<api_key>\""

The above command returns JSON structured like this:

{
  "response": [
    {
      "id": 1,
      "name": "Mike Smith",
      "identifier": "MikeSmith0001",
      "email": "mikesmith@test.com",
      "customer_type": "Personal",
      "home_phone": "(204) 555 5555",
      "cell_phone": "(204) 555 4444",
      "bank_name": "Scotiabank",
      "created_at": "2015-02-10T23:50:45.000-06:00",
      "updated_at": "2015-02-10T23:50:45.000-06:00",
      "custom_identifier": "Mikey",
      "active": true,
      "address": {
        "address_1": "123 Main Street",
        "address_2": "Unit 4",
        "city": "Toronto",
        "province_code": "ON",
        "postal_code": "M1B 0B7"
      }
    },
    {
      "id": 2,
      "name": "Susan Johnson",
      "identifier": "SUSANJO0002",
      "email": "susan@test.com",
      "customer_type": "Business",
      "home_phone": "(204) 111 4321",
      "cell_phone": "(204) 111 1234",
      "bank_name": "Royal Bank",
      "created_at": "2015-02-10T23:50:45.000-06:00",
      "updated_at": "2015-02-10T23:50:45.000-06:00",
      "custom_identifier": "Suze-44",
      "active": true,
      "address": {
        "address_1": "234 Main Street",
        "address_2": "",
        "city": "Calgary",
        "province_code": "AB",
        "postal_code": "T1X 0L3"
      }
    }
  ],
  "count": 2
}

This endpoint retrieves all customers.

HTTP Request

GET https://api.rotessa.com/v1/customers

Get a Specific Customer Based on Rotessa ID

curl "<rotessa_endpoint>/customers/<id>" -H "Authorization: Token token=\"<api_key>\""

The above command returns JSON structured like this:

{
  "response": {
    "id": 1,
    "name": "Mike Smith",
    "identifier": "MikeSmith0001",
    "email": "mikesmith@test.com",
    "home_phone": "(204) 555 5555",
    "cell_phone": "(204) 555 4444",
    "bank_name": "Scotiabank",
    "created_at": "2015-02-10T23:50:45.000-06:00",
    "updated_at": "2015-02-10T23:50:45.000-06:00",
    "custom_identifier": "Mikey",
    "active": true,
    "address": {
      "address_1": "123 Main Street",
      "address_2": "Unit 4",
      "city": "Toronto",
      "province_code": "ON",
      "postal_code": "M1B 0B7"
    }
    "transaction_schedules": [
      {
        "amount": "120.00",
        "frequency": "Weekly",
        "process_date": "2015-05-12",
        "installments": 10,
        "comment": "Monthly Membership Fees",
        "next_process_date": "2015-05-19",
        "created_at": "2015-05-12T23:02:08.000-05:00",
        "updated_at": "2015-05-12T23:04:00.000-05:00"
      }
    ],
    "financial_transactions": [
      {
        "amount": "120.00",
        "process_date": "2015-05-12",
        "status": "Pending",
        "status_reason": null,
        "transaction_schedule_id": 33630,
        "created_at": "2015-05-12T23:04:00.000-05:00",
        "updated_at": "2015-05-12T23:04:00.000-05:00"
      }
    ]
  }
}

This endpoint retrieves a specific customer.

HTTP Request

GET https://api.rotessa.com/v1/customers/<ID>.json

URL Parameters

Parameter Description
ID The ID of the customer to retrieve

Get a Specific Customer Based on Customer Identifier

curl -H 'Content-Type: application/json' -H "Authorization: Token token=\"<api_key>\"" -d '{"custom_identifier": "MikeSmith0001"}' <rotessa_endpoint>/customers/show_with_custom_identifier.json

The above command returns JSON structured like this:

{
  "response": {
    "id": 1,
    "name": "Mike Smith",
    "identifier": "MikeSmith0001",
    "email": "mikesmith@test.com",
    "home_phone": "(204) 555 5555",
    "cell_phone": "(204) 555 4444",
    "bank_name": "Scotiabank",
    "created_at": "2015-02-10T23:50:45.000-06:00",
    "updated_at": "2015-02-10T23:50:45.000-06:00",
    "custom_identifier": "Mikey",
    "active": true,
    "address": {
      "address_1": "123 Main Street",
      "address_2": "Unit 4",
      "city": "Toronto",
      "province_code": "ON",
      "postal_code": "M1B 0B7"
    }
    "transaction_schedules": [
      {
        "amount": "120.00",
        "frequency": "Weekly",
        "process_date": "2015-05-12",
        "installments": 10,
        "comment": "Monthly Membership Fees",
        "next_process_date": "2015-05-19",
        "created_at": "2015-05-12T23:02:08.000-05:00",
        "updated_at": "2015-05-12T23:04:00.000-05:00"
      }
    ],
    "financial_transactions": [
      {
        "amount": "120.00",
        "process_date": "2015-05-12",
        "status": "Pending",
        "status_reason": null,
        "transaction_schedule_id": 33630,
        "created_at": "2015-05-12T23:04:00.000-05:00",
        "updated_at": "2015-05-12T23:04:00.000-05:00"
      }
    ]
  }
}

This endpoint retrieves a specific customer based on a pre-assigned custom_identifier.

HTTP Request

GET https://api.rotessa.com/v1/customers/show_with_custom_identifier.json

URL Parameters

Parameter Description
custom_identifier Your own unique customer identifier.

Create A Customer

curl -X POST -H 'Content-Type: application/json' -H "Authorization: Token token=\"<api_key>\"" -d '{"custom_identifier": "test api", "email": "test@rotessa.com", "name": "Mike Smith", "bank_name": "Scotiabank", "transit_number": "11111", "institution_number": "111", "account_number": "11111111", "address": { "address_1": "123 Main Street", "address_2": "Unit 4", "city": "Toronto", "province_code": "ON", "postal_code": "M1B 0B7" }}' <rotessa_endpoint>/customers.json

The above command returns JSON structured like this:

{
  "response": {
    "name": "Mike Smith",
    "identifier": "MIKESMIT0001",
    "id": 45929,
    "email": "test@rotessa.com",
    "customer_type": "Personal",
    "home_phone": null,
    "cell_phone": null,
    "bank_name": "Scotiabank",
    "created_at": "2015-05-18T12:23:58.739-05:00",
    "updated_at": "2015-05-18T12:23:58.739-05:00",
    "custom_identifier": "test api",
    "active": true,
    "address": {
          "address_1": "123 Main Street",
          "address_2": "Unit 4",
          "city": "Toronto",
          "province_code": "ON",
          "postal_code": "M1B 0B7"
    },
    "transaction_schedules": [],
    "financial_transactions": []
  }
}

This endpoint creates a new customer

HTTP Request

POST https://api.rotessa.com/v1/customers

Post Parameters

Parameter Default Description
name - Full name of customer
custom_identifier - Your own customer identifier. Must be unique.
email - Email address
home_phone - Home phone number
cell_phone - Cell phone number
bank_name - Bank name of customer
institution_number - Bank institution number
transit_number - Bank transit number
account_number - Bank account number
address - Customer address parameters.
customer_type - Personal or Business

Update A Customer

curl -X PATCH -H 'Content-Type: application/json' -H "Authorization: Token token=\"<api_key>\"" -d '{"custom_identifier": "MIKEY", "email": "test@rotessa.com", "name": "Mike Smith", "bank_name": "Scotiabank", "transit_number": "11111", "institution_number": "333", "account_number": "23123132", "customer_type": "Personal", "address": { "address_1": "123 Main Street", "address_2": "Unit 4", "city": "Toronto", "province_code": "QC", "postal_code": "M1B 0B7" }}' <rotessa_endpoint>/customers/<id>.json

The above command returns JSON structured like this:

{
  "response": {
    "name": "Mike Smith",
    "identifier": "MIKEY",
    "email": "test@rotessa.com",
    "customer_type": "Personal",
    "home_phone": null,
    "cell_phone": null,
    "bank_name": "TD",
    "created_at": "2015-05-18T12:23:58.739-05:00",
    "updated_at": "2015-05-18T12:23:58.739-05:00",
    "custom_identifier": "asdf1234",
    "active": true,
    "address": {
          "address_1": "321 First Street",
          "address_2": "Unit 5",
          "city": "Winnipeg",
          "province_code": "MB",
          "postal_code": "M1B 0B7"
    },
    "transaction_schedules": [],
    "financial_transactions": []
  }
}

This endpoint creates a new customer

HTTP Request

POST https://api.rotessa.com/v1/customers

PATCH Parameters

Parameter Description
ID The ID of the customer to retrieve

Transaction Schedules

Transaction schedules are the method by which recurring or one time payments are scheduled in Rotessa for a customer. Payments require a schedule date, which must be at least 2 business days in the future, as well as a frequency.

Field Description
id ID of the transaction schedule.
process_date The initial date to begin withdrawing funds. (e.g. November 20, 2016)
installments The number of installments. Leave blank to continue withdrawing funds indefinitely.
comment A places to enter notes for the transaction schedule.
next_process_date The next date that funds will be withdrawn.
financial_transactions A list of financial transactions generated as a result of the payment schedule specified.

Schedule frequency

The frequency of a transaction schedule must be one of the following values:

Frequency Description
Once One time payment.
Weekly Every week.
Every Other Week Every two weeks.
Monthly Every month.
Every Other Month Every two months.
Quarterly Every 3 months.
Semi-Annually Every six months.
Yearly Once a year.

Transaction schedules have an optional installments parameter that allow you to schedule a set number of payments. To schedule payments indefinitely simply omit this parameter and Rotessa will continue withdrawing funds until the schedule is cancelled.

Get A Specific Transaction Schedule

curl "<rotessa_endpoint>/transaction_schedules/<id>.json" -H "Authorization: Token token=\"<api_key>\""

The above command returns JSON structured like this:

{
  "response": {
    "id": "1",
    "amount": "100.00",
    "frequency": "Monthly",
    "process_date": "2017-05-24",
    "installments": null,
    "comment": "Membership fees",
    "next_process_date": "2017-05-24",
    "created_at": "2017-05-16T14:43:22.101-05:00",
    "updated_at": "2017-05-16T14:43:22.101-05:00",
    "financial_transactions": []
  }
}

This endpoint creates a transaction schedule for a customer.

HTTP Request

GET https://api.rotessa.com/v1/transaction_schedules/<ID>.json

URL Parameters

Parameter Description
ID The ID of the transaction schedule to retrieve

Create A Transaction Schedule with Rotessa Customer ID

curl -X POST -H 'Content-Type: application/json' -H "Authorization: Token token=\"<api_key>\""  -d '{"id":45079, "amount": 100, "frequency": "Monthly", "process_date": "November 24, 2017", "comment": "Membership fees"}' <rotessa_endpoint>/transaction_schedules.json

The above command returns JSON structured like this:

{
  "response": {
    "id": "1",
    "amount": "100.00",
    "frequency": "Monthly",
    "process_date": "2017-11-24",
    "installments": null,
    "comment": "Membership fees",
    "next_process_date": "2015-05-24",
    "created_at": "2015-05-16T14:43:22.101-05:00",
    "updated_at": "2015-05-16T14:43:22.101-05:00",
    "financial_transactions": []
  }
}

This endpoint creates a transaction schedule for a customer.

HTTP Request

POST https://api.rotessa.com/v1/transaction_schedules.json

Post Parameters

Parameter Description
customer_id ID of customer
amount Amount for schedule
process_date The initial date to begin withdrawing funds. (e.g. November 20, 2016)
frequency Frequecy of transaction. Must be one of preceding valid frequecies.
installments The number of installments. If value is excluded, schedule is indefinite.
comment Optional comment for schedule.

This endpoint creates a transaction schedule for a customer.

HTTP Request

GET https://api.rotessa.com/v1/transaction_schedules/<ID>.json

URL Parameters

Parameter Description
ID The ID of the transaction schedule to retrieve

Create A Transaction Schedule with Custom Identifier


curl -XPOST -H 'Content-Type: application/json' -H "Authorization: Token token=\"<api_key>\""  -d '{"custom_identifier":"MikeSmith0001", amount": 100, "frequency": "Monthly", "process_date": "November 24, 2017", "comment": "Membership fees"}' <rotessa_endpoint>/v1/transaction_schedules/create_with_custom_identifier.json


The above command returns JSON structured like this:

{
  "response": {
    "id": "1",
    "amount": "100.00",
    "frequency": "Monthly",
    "process_date": "2017-11-24",
    "installments": null,
    "comment": "Membership fees",
    "next_process_date": "2015-05-24",
    "created_at": "2015-05-16T14:43:22.101-05:00",
    "updated_at": "2015-05-16T14:43:22.101-05:00",
    "financial_transactions": []
  }
}

This endpoint creates a transaction schedule for a customer.

HTTP Request

POST https://api.rotessa.com/v1/transaction_schedules/create_with_custom_identifier.json

Post Parameters

Parameter Description
custom_identifier Your own unique custom identifier for the customer
amount Amount for schedule
process_date The initial date to begin withdrawing funds. (e.g. November 20, 2016)
frequency Frequecy of transaction. Must be one of preceding valid frequecies.
installments The number of installments. If value is excluded, schedule is indefinite.
comment Optional comment for schedule.

Update A Specific Transaction Schedule

curl -X PATCH -H 'Content-Type: application/json' -H "Authorization: Token token=\"<api_key>\"" -d '{"amount": 150, "comment": "New Membership fees"}' <rotessa_endpoint>/transaction_schedules/<id>.json

The above command returns JSON structured like this:

{
  "response": {
    "id": "1",
    "amount": "150.00",
    "frequency": "Monthly",
    "process_date": "2017-05-24",
    "installments": null,
    "comment": "New Membership fees",
    "next_process_date": "2017-05-24",
    "created_at": "2017-05-16T14:43:22.101-05:00",
    "updated_at": "2017-05-16T14:45:13.101-05:00",
    "financial_transactions": []
  }
}

This endpoint updates a transaction schedule for a customer.

HTTP Request

PATCH https://api.rotessa.com/v1/transaction_schedules/<ID>.json

URL Parameters

Parameter Description
id The ID of the transaction schedule to retrieve
comment Optional comment for schedule

Delete A Specific Transaction Schedule

curl -X DELETE -H "Authorization: Token token=\"<api_key>\"" "<rotessa_endpoint>/transaction_schedules/<id>.json"

This endpoint deletes a transaction schedule for a customer.

A successfully deleted transaction schedule will return no errors.

HTTP Request

DELETE https://api.rotessa.com/v1/transaction_schedules/<ID>.json

URL Parameters

Parameter Description
ID The ID of the transaction schedule to retrieve

Financial Transactions

Financial transactions are are a history of the payments made for a customer. Financial transactions are created as a result of Transaction Schedules, and typcially move from a status of Pending -> Approved or Pending -> Declined. If a later chargeback occurs after a successful payment has been reported, financial transactions will be moved to a status of Chargeback.

Field Description
id ID of the financial transaction.
amount Transaction amount.
process_date The scheduled process date of the transaction.
status The current status of the transaction.
status_reason The reason for the Declined or Chargeback status of a transactions.
transaction_schedule_id ID of the transction schedule that created this financial transaction.
bank_name Bank name.
institution_number Bank institution number.
transit_number Bank transit number.
account_number Bank account number.

Status

Financial transactions can be in one of the following statuses

Status Description
Future The financial transaction has not yet been scheduled.
Pending The financial transaction is being processed.
Approved The financial transaction was successful.
Declined The financial transaction was declined for the reason specified in status_reason.

Status reasons

Financial transactions, if Declined or Chargeback will have a value in the status_reason field.

Reason
NSF
Payment Stopped/Recalled
Edit Reject
Funds Not Cleared
Account closed
Invalid/Incorrect Account No.
Account Not Found
Account Frozen
Agreement Revoked
No Debit Allowed

Transaction Report

The transaction report endpoint is the main interface by which your system can determine the current state of payments processed by Rotessa. The transaction report is limited to transcations 3 years into the futre or 1000 transactions, whichever comes first.

Show Transaction Report

The endpoint provides 4 parameters which can be queried.

curl -X GET -H 'Content-Type: application/json' -H "Authorization: Token token=\"<api_key>\""  "<rotessa_endpoint>/transaction_report.json?start_date=2016-09-12&end_date=2016-11-12&filter=All"

The above command returns JSON structured like this:

{
  "response": [
    {
      "id": 123456,
      "customer_id": 1,
      "custom_identifier": "Mikey"
      "amount": "120.00",
      "process_date": "2015-05-12",
      "status": "Pending",
      "status_reason": null,
      "transaction_schedule_id": 1,
      "created_at": "2015-05-12T23:04:00.000-05:00",
      "updated_at": "2015-05-12T23:04:00.000-05:00"
    },
    {
      "id": 123457,
      "customer_id": 1,
      "custom_identifier": "Mikey"
      "amount": "120.00",
      "process_date": "2015-05-19",
      "status": "Approved",
      "status_reason": null,
      "transaction_schedule_id": 2,
      "created_at": "2015-05-28T23:36:50.000-05:00",
      "updated_at": "2015-05-28T23:40:57.000-05:00"
    },
    {
      "id": 123458,
      "customer_id": 1,
      "custom_identifier": "Mikey"
      "amount": "120.00",
      "process_date": "2015-06-02",
      "status": "Future",
      "status_reason": null,
      "transaction_schedule_id": 3,
      "created_at": null,
      "updated_at": null
    },
    {
      "id": 123459,
      "customer_id": 1,
      "custom_identifier": "Mikey"
      "amount": "120.00",
      "process_date": "2015-06-09",
      "status": "Future",
      "status_reason": null,
      "transaction_schedule_id": 4,
      "created_at": null,
      "updated_at": null
    },

HTTP Request

POST https://api.rotessa.com/v1/transaction_report

Parameter Description
start_date The earliest process date (YYYY-MM-DD) of the list of transactions.
end_date The last process date (YYYY-MM-DD) of the list of transactions. Optional
status Filter by the given financial status of the transactions.
page Page selected based on 1000 transactions per page

The status parameter can be one of the following values.

Parameter Description
‘All’ Return all the transactions. This is the default value.
'Pending’ Only pending transactions. These are transactions still being processed by Rotessa.
'Approved’ Only approved transactions. These are considered successful transactions.
'Declined’ Only declined transactions. These are failed transactions.
'Chargeback’ Only chargeback transactions. These are failed transactions.

Errors

Errors are structured in the following format:

{
  "errors": [
    {
      "error_code": "installments_required",
      "error_message": "Installments value must be at least 1."
    },
    {
      "error_code": "process_date_timing",
      "error_message": "Process date must be at least 2 business days in the future."
    }
  ]
}

Error format

Errors are returned from Rotessa in the for of a list of values in the errors key of response. Each error has an error_code and error_message, corresponding to the type of error that has occurred.

HTTP Response codes

The Rotessa API uses the following http error codes:

Error Code Meaning
400 Bad Request – Your request includes invalid parameters
401 Unauthorized – Your API key is not valid or is missing
404 Not Found – The specified resource could not be found
406 Not Acceptable – You requested a format that isn’t json
422 Unprocessable Entity – Your request results in invalid data.
500 Internal Server Error – Rotessa system cannot process your request. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.