NAV

Clients

Clients represent the individual or company that the funds will be deposited to.

Create client

curl -X POST -H 'Content-Type: application/json' -H "Authorization: Token token=\"<PLATFORM_API_KEY>\"" -d '{"business_name": "Condo Corp 1234", "operating_as": "Purple Sky Condos", "business_incorporation_number": "123123123", "business_type": "Partnership", "transit_number": "11001", "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" }, "owners":[{"name": "John Smith", "position": "Board Director 1", "date_of_birth": "June 1, 2020", "address": { "address_1": "123 Main Street", "city": "Toronto", "province_code": "ON", "postal_code": "M1B 0B7" }},{"name": "Jane Smith", "position": "Board Director 2", "date_of_birth": "March 1, 2020", "address": { "address_1": "123 Main Street", "address_2": "Unit 4", "city": "Toronto", "province_code": "ON", "postal_code": "M1B 0B7" }}], "associated_client": 4321}' <ROTESSA_ENDPOINT>/v2/clients

The above command returns JSON structured like this:

{
  "account_number": "11111111",
  "address": {
    "address_1": "123 Main Street",
    "address_2": "Unit 4",
    "city": "Toronto",
    "id": 12345,
    "postal_code": "M1B 0B7",
    "province_code": "ON"
  },
  "api_keys": [
    {
      "key": "<API_KEY>"
    }
  ],
  "bank_account_type": null,
  "business_incorporation_number": "123123123",
  "business_name": "test api",
  "business_type": "Partnership",
  "country_code": "CA",
  "id": 1234,
  "institution_number": "111",
  "operating_as": "operating as name",
  "owners": [
    {
      "completion_status": "Complete",
      "date_of_birth": "2020-06-01",
      "id": 2350,
      "name": "test name",
      "position": "test position"
    },
    {
      "completion_status": "Complete",
      "date_of_birth": "2020-03-01",
      "id": 2351,
      "name": "test name 2",
      "position": "test position 2"
    }
  ],
  "routing_number": null,
  "status": "Pending",
  "transit_number": "11001",
  "veriff_session_url": "<VERIFF_SESSION_URL>",
  "veriff_submission_status": "<VERIFF_SESSION_SUBMISSION_STATUS>",
  "veriff_decision_status:": "<VERIFF_SESSION_DECISION_STATUS>",
  "website": null
}

This endpoint creates a new client.

Client Parameters

Parameter Required Description
business_name TRUE Legal business name
operating_as TRUE Common business name
business_incorporation_number TRUE --
business_type TRUE One of ['Ltd/Corp', 'Partnership', 'Proprietorship', 'Not for Profit']
address TRUE --
transit_number CA --
institution_number CA --
account_number TRUE --
routing_number US --
bank_account_type US One of ['Savings', 'Checkings']
owners TRUE --
associated_client FALSE ID of existing client with identical information

Address Parameters

Parameter Required Description
address_1 TRUE --
address_2 FALSE --
city TRUE --
province_code TRUE --
postal_code TRUE --

Owner Parameters

Parameter Required Description
name TRUE --
position TRUE --
date_of_birth TRUE --
address TRUE --

Partial Client Creation

Create a client with some or all of the required fields and update the client until they have the required fields to be automatically promoted to pending for review. Use this if you intend to upload documents for a client as documents can only be added to clients while they have a created status.

curl -X POST -H 'Content-Type: application/json' -H "Authorization: Token token=\"<PLATFORM_API_KEY>\"" -d '{"business_name": "Condo Corp 1234", "operating_as": "Purple Sky Condos", "business_incorporation_number": "123123123", "business_type": "Partnership", "transit_number": "11001", "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>/v2/clients/create_client

The above command returns JSON structured like this:

{
  "account_number": "11111111",
  "address": {
    "address_1": "123 Main Street",
    "address_2": "Unit 4",
    "city": "Toronto",
    "id": 12345,
    "postal_code": "M1B 0B7",
    "province_code": "ON"
  },
  "api_keys": [],
  "bank_account_type": null,
  "business_incorporation_number": "123123123",
  "business_name": "Condo Corp 1000",
  "business_type": "Partnership",
  "country_code": "CA",
  "id": 1234,
  "institution_number": "111",
  "operating_as": "Purple Sky Condos",
  "owners": [],
  "routing_number": null,
  "status": "Created",
  "transit_number": "11001",
  "veriff_session_url": "<VERIFF_SESSION_URL>",
  "veriff_submission_status": "<VERIFF_SESSION_SUBMISSION_STATUS>",
  "veriff_decision_status:": "<VERIFF_SESSION_DECISION_STATUS>",
  "website": null
}

This endpoint creates a new client that can be incomplete.

Update a client

curl -X PATCH -H 'Content-Type: application/json' -H "Authorization: Token token=\"<PLATFORM_API_KEY>\"" -d '{"business_name": "Condo Corp 1234", "operating_as": "Purple Sky Condos", "business_incorporation_number": "123123123", "business_type": "Partnership", "transit_number": "11001", "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" }, "owners":[{"name": "John Smith", "position": "Board Director 1", "date_of_birth": "June 1, 2020", "address": { "address_1": "123 Main Street", "city": "Toronto", "province_code": "ON", "postal_code": "M1B 0B7" }},{"name": "Jane Smith", "position": "Board Director 2", "date_of_birth": "March 1, 2020", "address": { "address_1": "123 Main Street", "address_2": "Unit 4", "city": "Toronto", "province_code": "ON", "postal_code": "M1B 0B7" }}], "associated_client": 4321}' <ROTESSA_ENDPOINT>/v2/clients/<CLIENT_ID>

The above command returns JSON structured like this:

{
  "account_number": "11111111",
  "address": {
    "address_1": "123 Main Street",
    "address_2": "Unit 4",
    "city": "Toronto",
    "id": 12345,
    "postal_code": "M1B 0B7",
    "province_code": "ON"
  },
  "api_keys": [
    {
      "key": "<API_KEY>"
    }
  ],
  "bank_account_type": null,
  "business_incorporation_number": "123123123",
  "business_name": "test api",
  "business_type": "Partnership",
  "country_code": "CA",
  "id": 1234,
  "institution_number": "111",
  "operating_as": "operating as name",
  "owners": [
    {
      "completion_status": "Complete",
      "date_of_birth": "2020-06-01",
      "id": 2350,
      "name": "test name",
      "position": "test position"
    },
    {
      "completion_status": "Complete",
      "date_of_birth": "2020-03-01",
      "id": 2351,
      "name": "test name 2",
      "position": "test position 2"
    }
  ],
  "routing_number": null,
  "status": "Pending",
  "transit_number": "11001",
  "veriff_session_url": "<VERIFF_SESSION_URL>",
  "veriff_submission_status": "<VERIFF_SESSION_SUBMISSION_STATUS>",
  "veriff_decision_status:": "<VERIFF_SESSION_DECISION_STATUS>",
  "website": null
}

This endpoint updates a client that has a created status.

Upload certificate of good standing

curl -H "Authorization: Token token=\"<PLATFORM_API_KEY>" -F "file=<FILENAME>.pdf;type=application/pdf" <ROTESSA_ENDPOINT>/v2/clients/<CLIENT_ID>/upload_certificate_of_good_standing

The above command returns JSON structured like this:

{
  "account_number": "11111111",
  "address": {
    "address_1": "123 Main Street",
    "address_2": "Unit 4",
    "city": "Toronto",
    "id": 12345,
    "postal_code": "M1B 0B7",
    "province_code": "ON"
  },
  "api_keys": [],
  "bank_account_type": null,
  "business_incorporation_number": "123123123",
  "business_name": "Condo Corp 1000",
  "business_type": "Partnership",
  "country_code": "CA",
  "id": 1234,
  "institution_number": "111",
  "operating_as": "Purple Sky Condos",
  "owners": [],
  "routing_number": null,
  "status": "Created",
  "transit_number": "11001",
  "veriff_session_url": "<VERIFF_SESSION_URL>",
  "veriff_submission_status": "<VERIFF_SESSION_SUBMISSION_STATUS>",
  "veriff_decision_status:": "<VERIFF_SESSION_DECISION_STATUS>",
  "website": null
}

This endpoint uploads a certificate of good standing which is for US businesses.

Upload settlement account document

curl -H "Authorization: Token token=\"<PLATFORM_API_KEY>" -F "file=<FILENAME>.pdf;type=application/pdf" <ROTESSA_ENDPOINT>/v2/clients/<CLIENT_ID>/upload_settlement_account_document

The above command returns JSON structured like this:

{
  "account_number": "11111111",
  "address": {
    "address_1": "123 Main Street",
    "address_2": "Unit 4",
    "city": "Toronto",
    "id": 12345,
    "postal_code": "M1B 0B7",
    "province_code": "ON"
  },
  "api_keys": [],
  "bank_account_type": null,
  "business_incorporation_number": "123123123",
  "business_name": "Condo Corp 1000",
  "business_type": "Partnership",
  "country_code": "CA",
  "id": 1234,
  "institution_number": "111",
  "operating_as": "Purple Sky Condos",
  "owners": [],
  "routing_number": null,
  "status": "Created",
  "transit_number": "11001",
  "veriff_session_url": "<VERIFF_SESSION_URL>",
  "veriff_submission_status": "<VERIFF_SESSION_SUBMISSION_STATUS>",
  "veriff_decision_status:": "<VERIFF_SESSION_DECISION_STATUS>",
  "website": null
}

This endpoint uploads a settlement account document, typically a void cheque or account authorization.

Upload miscellaneous document

curl -H "Authorization: Token token=\"<PLATFORM_API_KEY>" -F "file=<FILENAME>.pdf;type=application/pdf" -F "file_type=<FILE_TYPE>" <ROTESSA_ENDPOINT>/v2/clients/<CLIENT_ID>/upload_document

The above command returns JSON structured like this:

{
  "account_number": "11111111",
  "address": {
    "address_1": "123 Main Street",
    "address_2": "Unit 4",
    "city": "Toronto",
    "id": 12345,
    "postal_code": "M1B 0B7",
    "province_code": "ON"
  },
  "api_keys": [],
  "bank_account_type": null,
  "business_incorporation_number": "123123123",
  "business_name": "Condo Corp 1000",
  "business_type": "Partnership",
  "country_code": "CA",
  "id": 1234,
  "institution_number": "111",
  "operating_as": "Purple Sky Condos",
  "owners": [],
  "routing_number": null,
  "status": "Created",
  "transit_number": "11001",
  "veriff_session_url": "<VERIFF_SESSION_URL>",
  "veriff_submission_status": "<VERIFF_SESSION_SUBMISSION_STATUS>",
  "veriff_decision_status:": "<VERIFF_SESSION_DECISION_STATUS>",
  "website": null
}

This endpoint uploads a document. Typically used to upload additional documents required for verification.

Parameter Required Description
file TRUE File to upload
file_type TRUE Type of file, such as "Void cheque"

Retrieve a specific client

curl "<ROTESSA_ENDPOINT>/v2/clients/<CLIENT_ID>" -H "Authorization: Token token=\"<PLATFORM_API_KEY>"

The above command returns JSON structured like this:

{
  "account_number": "11111111",
  "address": {
    "address_1": "123 Main Street",
    "address_2": "Unit 4",
    "city": "Toronto",
    "id": 12345,
    "postal_code": "M1B 0B7",
    "province_code": "ON"
  },
  "api_keys": [
    {
      "key": "<API_KEY>"
    }
  ],
  "bank_account_type": null,
  "business_incorporation_number": "123123123",
  "business_name": "test api",
  "business_type": "Partnership",
  "country_code": "CA",
  "id": 1234,
  "institution_number": "111",
  "operating_as": "operating as name",
  "owners": [
    {
      "completion_status": "Complete",
      "date_of_birth": "2020-06-01",
      "id": 2350,
      "name": "test name",
      "position": "test position"
    },
    {
      "completion_status": "Complete",
      "date_of_birth": "2020-03-01",
      "id": 2351,
      "name": "test name 2",
      "position": "test position 2"
    }
  ],
  "routing_number": null,
  "status": "Pending",
  "transit_number": "11001",
  "veriff_session_url": "<VERIFF_SESSION_URL>",
  "veriff_submission_status": "<VERIFF_SESSION_SUBMISSION_STATUS>",
  "veriff_decision_status:": "<VERIFF_SESSION_DECISION_STATUS>",
  "website": null
}

This endpoint retrieves a specific client.

Parameter Required Description
id TRUE ID of client

Retrieve all clients

curl "<ROTESSA_ENDPOINT>/v2/clients" -H "Authorization: Token token=\"<PLATFORM_API_KEY>"

The above command returns JSON structured like this:

[
  {
    "account_number": "11111111",
    "address": {
      "address_1": "123 Main Street",
      "address_2": "Unit 4",
      "city": "Toronto",
      "id": 12345,
      "postal_code": "M1B 0B7",
      "province_code": "ON"
    },
    "api_keys": [
      {
        "key": "<API_KEY>"
      }
    ],
    "bank_account_type": null,
    "business_incorporation_number": "123123123",
    "business_name": "test api",
    "business_type": "Partnership",
    "country_code": "CA",
    "id": 1234,
    "institution_number": "111",
    "operating_as": "operating as name",
    "owners": [
      {
        "completion_status": "Complete",
        "date_of_birth": "2020-06-01",
        "id": 2350,
        "name": "test name",
        "position": "test position"
      },
      {
        "completion_status": "Complete",
        "date_of_birth": "2020-03-01",
        "id": 2351,
        "name": "test name 2",
        "position": "test position 2"
      }
    ],
    "routing_number": null,
    "status": "Pending",
    "transit_number": "11001",
    "veriff_session_url": "<VERIFF_SESSION_URL>",
    "veriff_submission_status": "<VERIFF_SESSION_SUBMISSION_STATUS>",
    "veriff_decision_status:": "<VERIFF_SESSION_DECISION_STATUS>",
    "website": null
  }
]

This endpoint retrieves all clients.

Approve client in sandbox

curl -X POST "<ROTESSA_ENDPOINT>/v2/clients/<CLIENT_ID>/approve_test_client" -H "Authorization: Token token=\"<PLATFORM_API_KEY>"

The above command returns JSON structured like this:

{
  "account_number": "11111111",
  "address": {
    "address_1": "123 Main Street",
    "address_2": "Unit 4",
    "city": "Toronto",
    "id": 12345,
    "postal_code": "M1B 0B7",
    "province_code": "ON"
  },
  "api_keys": [
    {
      "key": "<API_KEY>"
    }
  ],
  "bank_account_type": null,
  "business_incorporation_number": "123123123",
  "business_name": "test api",
  "business_type": "Partnership",
  "country_code": "CA",
  "id": 1234,
  "institution_number": "111",
  "operating_as": "operating as name",
  "owners": [
    {
      "completion_status": "Complete",
      "date_of_birth": "2020-06-01",
      "id": 2350,
      "name": "test name",
      "position": "test position"
    },
    {
      "completion_status": "Complete",
      "date_of_birth": "2020-03-01",
      "id": 2351,
      "name": "test name 2",
      "position": "test position 2"
    }
  ],
  "routing_number": null,
  "status": "Pending",
  "transit_number": "11001",
  "veriff_session_url": "<VERIFF_SESSION_URL>",
  "veriff_submission_status": "<VERIFF_SESSION_SUBMISSION_STATUS>",
  "veriff_decision_status:": "<VERIFF_SESSION_DECISION_STATUS>",
  "website": null
}

This endpoint sets the specified client as approved for testing.

Create new Veriff session

curl -X POST "<ROTESSA_ENDPOINT>/v2/clients/<CLIENT_ID>/new_veriff_session" -H "Authorization: Token token=\"<PLATFORM_API_KEY>"

The above command returns JSON structured like this:

{
  "account_number": "11111111",
  "address": {
    "address_1": "123 Main Street",
    "address_2": "Unit 4",
    "city": "Toronto",
    "id": 12345,
    "postal_code": "M1B 0B7",
    "province_code": "ON"
  },
  "api_keys": [
    {
      "key": "<API_KEY>"
    }
  ],
  "bank_account_type": null,
  "business_incorporation_number": "123123123",
  "business_name": "test api",
  "business_type": "Partnership",
  "country_code": "CA",
  "id": 1234,
  "institution_number": "111",
  "operating_as": "operating as name",
  "owners": [
    {
      "completion_status": "Complete",
      "date_of_birth": "2020-06-01",
      "id": 2350,
      "name": "test name",
      "position": "test position"
    },
    {
      "completion_status": "Complete",
      "date_of_birth": "2020-03-01",
      "id": 2351,
      "name": "test name 2",
      "position": "test position 2"
    }
  ],
  "routing_number": null,
  "status": "Pending",
  "transit_number": "11001",
  "veriff_session_url": "<VERIFF_SESSION_URL>",
  "veriff_submission_status": "<VERIFF_SESSION_SUBMISSION_STATUS>",
  "veriff_decision_status:": "<VERIFF_SESSION_DECISION_STATUS>",
  "website": null
}

This endpoint creates a new Veriff session for verifying the identity of the business owner. Attributes and statuses for the most recent Veriff session are stored on the client, under the following attributes:

Attribute Description
veriff_session_url The URL linking to the generated Veriff session
veriff_submission_status The submission status for the Veriff session. One of: NULL, created, submitted
veriff_decision_status The decision status for the Veriff session. One of: NULL, approved, declined, resubmission_requested, abandoned, expired

Note: In the Sandbox environment the decision status must be manually set using "Set Veriff decision status of test client".

For more details regarding Veriff statuses, please refer to the Veriff documentation.

Set Veriff decision status of test client

curl -X POST "<ROTESSA_ENDPOINT>/v2/clients/<CLIENT_ID>/set_test_client_verification" -H "Authorization: Token token=\"<PLATFORM_API_KEY>" -d '{"owner_id": "<OWNER_ID>", "status": "<VERIFF_DECISION_STATUS>"}'

The above command returns JSON structured like this:

{
  "account_number": "11111111",
  "address": {
    "address_1": "123 Main Street",
    "address_2": "Unit 4",
    "city": "Toronto",
    "id": 12345,
    "postal_code": "M1B 0B7",
    "province_code": "ON"
  },
  "api_keys": [
    {
      "key": "<API_KEY>"
    }
  ],
  "bank_account_type": null,
  "business_incorporation_number": "123123123",
  "business_name": "test api",
  "business_type": "Partnership",
  "country_code": "CA",
  "id": 1234,
  "institution_number": "111",
  "operating_as": "operating as name",
  "owners": [
    {
      "completion_status": "Complete",
      "date_of_birth": "2020-06-01",
      "id": 2350,
      "name": "test name",
      "position": "test position"
    },
    {
      "completion_status": "Complete",
      "date_of_birth": "2020-03-01",
      "id": 2351,
      "name": "test name 2",
      "position": "test position 2"
    }
  ],
  "routing_number": null,
  "status": "Pending",
  "transit_number": "11001",
  "veriff_session_url": "<VERIFF_SESSION_URL>",
  "veriff_submission_status": "<VERIFF_SESSION_SUBMISSION_STATUS>",
  "veriff_decision_status:": "<VERIFF_DECISION_STATUS>",
  "website": null
}

This endpoint allows the Veriff decision status to be manually set in the Sandbox environment for a test client. Available statuses are detailed below.

Parameter Description
owner_id The id of the owner that would be completing the test client's Veriff session
status The desired status for the test client's Veriff session
Available Veriff decision statuses
approved
declined
resubmission_requested
expired
abandoned


For more details regarding Veriff statuses, please refer to the Veriff documentation.

Client Validations

Here are the requirements for clients.

Note: -- indicates it applies to all clients, regardless of country

Parameter Country Requirements
business_name -- present
phone -- 10 digits
account_number -- 5..18 digits
transit_number CA 5 digits
institution_number CA 3 digits
routing_number US 9 digits & legitimate routing number
bank_account_type US "Checking" or "Savings"
owners -- at least one with all parameters
address -- present

Address

When adding an address it must meet these requirements.

Parameter Requirments
address_1 present
city present
province_code present, 2 letter state or province abbreviation
postal_code present

Owner

When adding an address it must meet these requirements.

Parameter Requirments
name present
date_of_birth present
position present
address present

Customers

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

Create a customer

curl -X POST -H 'Content-Type: application/json' -H "Authorization: Token token=\"<PLATFORM_API_KEY>\"" -d '{"custom_identifier": "MikeSmith", "email": "[email protected]", "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>/v2/clients/<CLIENT_ID>/customers

The above command returns JSON structured like this:

{
  "account_number": "11111111",
  "active": true,
  "address": {
    "address_1": "123 Main Street",
    "address_2": "Unit 4",
    "city": "Toronto",
    "id": 242317,
    "postal_code": "M1B 0B7",
    "province_code": "ON"
  },
  "authorization_type": null,
  "bank_account_type": null,
  "bank_name": "Scotiabank",
  "created_at": "2020-10-22T13:27:34.000-05:00",
  "custom_identifier": "MikeSmith",
  "customer_type": "Personal",
  "email": "[email protected]",
  "financial_transactions": [],
  "home_phone": null,
  "id": 174527,
  "identifier": "MIKESMIT0007",
  "institution_number": "111",
  "name": "Mike Smith",
  "phone": null,
  "routing_number": null,
  "transaction_schedules": [],
  "transit_number": "11111",
  "updated_at": "2020-10-22T13:27:35.000-05:00"
}

This endpoint creates a new customer.

Parameter Required Description
custom_identifier FALSE Your own unique customer identifier
name TRUE Full name of customer
email FALSE Customer email address
customer_type FALSE Personal or Business
home_phone FALSE Home phone number
phone FALSE Phone number
bank_name FALSE Bank name
institution_number FALSE Bank institution number for Canadian customers
transit_number FALSE Bank transit number for Canadian customers
bank_account_type FALSE "Savings" or "Checking" for American customers
authorization_type FALSE "In Person" or "Online"
routing_number FALSE Bank routing number for American customers
account_number FALSE Bank account number
address FALSE Customer address

Update a customer

curl -X PATCH -H 'Content-Type: application/json' -H "Authorization: Token token=\"<PLATFORM_API_KEY>\"" -d '{"custom_identifier": "MikeS", "email": "[email protected]", "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>/v2/clients/<CLIENT_ID>/customers/<CUSTOMER_ID>

The above command returns JSON structured like this:

{
  "account_number": "23123132",
  "active": true,
  "address": {
    "address_1": "123 Main Street",
    "address_2": "Unit 4",
    "city": "Toronto",
    "id": 242317,
    "postal_code": "M1B 0B7",
    "province_code": "QC"
  },
  "authorization_type": null,
  "bank_account_type": null,
  "bank_name": "Scotiabank",
  "created_at": "2020-10-22T13:27:34.000-05:00",
  "custom_identifier": "MikeS",
  "customer_type": "Personal",
  "email": "[email protected]",
  "financial_transactions": [],
  "home_phone": null,
  "id": 174527,
  "identifier": "MIKESMIT0007",
  "institution_number": "333",
  "name": "Mike Smith",
  "phone": null,
  "routing_number": null,
  "transaction_schedules": [],
  "transit_number": "11111",
  "updated_at": "2020-10-22T13:28:42.000-05:00"
}

This endpoint updates a customer.

Parameter Required Description
custom_identifier FALSE Your own unique customer identifier
name FALSE Full name of customer
email FALSE Customer email address
customer_type FALSE Personal or Business
home_phone FALSE Home phone number
phone FALSE Phone number
bank_name FALSE Bank name
institution_number FALSE Bank institution number for Canadian customers
transit_number FALSE Bank transit number for Canadian customers
bank_account_type FALSE "Savings" or "Checking" for American customers
authorization_type FALSE "In Person" or "Online"
routing_number FALSE Bank routing number for American customers
account_number FALSE Bank account number
address FALSE Customer address

Update a customer via post

curl -X POST -H 'Content-Type: application/json' -H "Authorization: Token token=\"<PLATFORM_API_KEY>\"" -d '{"id": "174527", "custom_identifier": "MikeS", "email": "[email protected]", "name": "Mike Smith", "bank_name": "Scotiabank", "transit_number": "22222", "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>/v2/clients/<CLIENT_ID>/customers/update_via_post

The above command returns JSON structured like this:

{
  "account_number": "23123132",
  "active": true,
  "address": {
    "address_1": "123 Main Street",
    "address_2": "Unit 4",
    "city": "Toronto",
    "id": 242317,
    "postal_code": "M1B 0B7",
    "province_code": "QC"
  },
  "authorization_type": null,
  "bank_account_type": null,
  "bank_name": "Scotiabank",
  "created_at": "2020-10-22T13:27:34.000-05:00",
  "custom_identifier": "MikeS",
  "customer_type": "Personal",
  "email": "[email protected]",
  "financial_transactions": [],
  "home_phone": null,
  "id": 174527,
  "identifier": "MIKESMIT0007",
  "institution_number": "333",
  "name": "Mike Smith",
  "phone": null,
  "routing_number": null,
  "transaction_schedules": [],
  "transit_number": "22222",
  "updated_at": "2020-10-22T13:28:42.000-05:00"
}

This endpoint updates a customer.

Parameter Required Description
custom_identifier FALSE Your own unique customer identifier
name FALSE Full name of customer
email FALSE Customer email address
customer_type FALSE Personal or Business
home_phone FALSE Home phone number
phone FALSE Phone number
bank_name FALSE Bank name
institution_number FALSE Bank institution number for Canadian customers
transit_number FALSE Bank transit number for Canadian customers
bank_account_type FALSE "Savings" or "Checking" for American customers
authorization_type FALSE "In Person" or "Online"
routing_number FALSE Bank routing number for American customers
account_number FALSE Bank account number
address FALSE Customer address

Update a customer with custom_identifier

curl -X POST -H 'Content-Type: application/json' -H "Authorization: Token token=\"<PLATFORM_API_KEY>\"" -d '{ "custom_identifier": "MikeS", "email": "[email protected]", "name": "Mike Smith", "bank_name": "Scotiabank", "transit_number": "22222", "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>/v2/clients/<CLIENT_ID>/customers/update_with_custom_identifier

The above command returns JSON structured like this:

{
  "account_number": "23123132",
  "active": true,
  "address": {
    "address_1": "123 Main Street",
    "address_2": "Unit 4",
    "city": "Toronto",
    "id": 242317,
    "postal_code": "M1B 0B7",
    "province_code": "QC"
  },
  "authorization_type": null,
  "bank_account_type": null,
  "bank_name": "Scotiabank",
  "created_at": "2020-10-22T13:27:34.000-05:00",
  "custom_identifier": "MikeS",
  "customer_type": "Personal",
  "email": "[email protected]",
  "financial_transactions": [],
  "home_phone": null,
  "id": 174527,
  "identifier": "MIKESMIT0007",
  "institution_number": "333",
  "name": "Mike Smith",
  "phone": null,
  "routing_number": null,
  "transaction_schedules": [],
  "transit_number": "22222",
  "updated_at": "2020-10-22T13:28:42.000-05:00"
}

This endpoint updates a customer.

Parameter Required Description
custom_identifier TRUE Your own unique customer identifier
name FALSE Full name of customer
email FALSE Customer email address
customer_type FALSE Personal or Business
home_phone FALSE Home phone number
phone FALSE Phone number
bank_name FALSE Bank name
institution_number FALSE Bank institution number for Canadian customers
transit_number FALSE Bank transit number for Canadian customers
bank_account_type FALSE "Savings" or "Checking" for American customers
authorization_type FALSE "In Person" or "Online"
routing_number FALSE Bank routing number for American customers
account_number FALSE Bank account number
address FALSE Customer address

Retrieve a specific customer

curl "<ROTESSA_ENDPOINT>/v2/clients/<CLIENT_ID>/customers/<CUSTOMER_ID>" -H "Authorization: Token token=\"<PLATFORM_API_KEY>"

The above command returns JSON structured like this:

{
  "account_number": "23123132",
  "active": true,
  "address": {
    "address_1": "123 Main Street",
    "address_2": "Unit 4",
    "city": "Toronto",
    "id": 242317,
    "postal_code": "M1B 0B7",
    "province_code": "QC"
  },
  "authorization_type": null,
  "bank_account_type": null,
  "bank_name": "Scotiabank",
  "created_at": "2020-10-22T13:27:34.000-05:00",
  "custom_identifier": "MikeS",
  "customer_type": "Personal",
  "email": "[email protected]",
  "financial_transactions": [],
  "home_phone": null,
  "id": 174527,
  "identifier": "MIKESMIT0007",
  "institution_number": "333",
  "name": "Mike Smith",
  "phone": null,
  "routing_number": null,
  "transaction_schedules": [],
  "transit_number": "11111",
  "updated_at": "2020-10-22T13:28:42.000-05:00"
}

This endpoint retrieves a specific customer for a client.

Retrieve a specific customer by custom_identifier

curl "<ROTESSA_ENDPOINT>/v2/clients/<CLIENT_ID>/customers/show_by_custom_identifier" -H 'Content-Type: application/json' -H "Authorization: Token token=\"<PLATFORM_API_KEY>" -d '{"custom_identifier": "MikeS"}'

The above command returns JSON structured like this:

{
  "account_number": "23123132",
  "active": true,
  "address": {
    "address_1": "123 Main Street",
    "address_2": "Unit 4",
    "city": "Toronto",
    "id": 242317,
    "postal_code": "M1B 0B7",
    "province_code": "QC"
  },
  "authorization_type": null,
  "bank_account_type": null,
  "bank_name": "Scotiabank",
  "created_at": "2020-10-22T13:27:34.000-05:00",
  "custom_identifier": "MikeS",
  "customer_type": "Personal",
  "email": "[email protected]",
  "financial_transactions": [],
  "home_phone": null,
  "id": 174527,
  "identifier": "MIKESMIT0007",
  "institution_number": "333",
  "name": "Mike Smith",
  "phone": null,
  "routing_number": null,
  "transaction_schedules": [],
  "transit_number": "11111",
  "updated_at": "2020-10-22T13:28:42.000-05:00"
}

This endpoint retrieves a specific customer for a client.

Get all customers for a specific client

curl "<ROTESSA_ENDPOINT>/v2/clients/<CLIENT_ID>/customers" -H "Authorization: Token token=\"<PLATFORM_API_KEY>"

The above command returns JSON structured like this:

[
  {
    "account_number": "23123132",
    "active": true,
    "address": {
      "address_1": "123 Main Street",
      "address_2": "Unit 4",
      "city": "Toronto",
      "id": 242317,
      "postal_code": "M1B 0B7",
      "province_code": "QC"
    },
    "authorization_type": null,
    "bank_account_type": null,
    "bank_name": "Scotiabank",
    "created_at": "2020-10-22T13:27:34.000-05:00",
    "custom_identifier": "MikeS",
    "customer_type": "Personal",
    "email": "[email protected]",
    "financial_transactions": [
      {
        "account_number": "****32",
        "amount": "100.00",
        "comment": "Monthly Fees",
        "created_at": "2021-03-26T16:02:05.338-05:00",
        "custom_identifier": "16472",
        "customer_id": 174527,
        "earliest_approval_date": "2021-04-02",
        "id": 12341234,
        "institution_number": "*33",
        "process_date": "2021-03-27",
        "settlement_date": "2021-04-05",
        "status": "Approved",
        "status_reason": null,
        "transaction_number": "INV1234123",
        "transaction_schedule_id": 1234321,
        "transit_number": "***11",
        "updated_at": "2021-04-05T11:02:20.222-05:00",
        "zapier_identifier": null
      }
    ],
    "home_phone": null,
    "id": 174527,
    "identifier": "MIKESMIT0007",
    "institution_number": "333",
    "name": "Mike Smith",
    "phone": null,
    "routing_number": null,
    "transaction_schedules": [
      {
        "active": true,
        "amount": "100.00",
        "comment": "Monthly Fees",
        "created_at": "2021-03-26T10:00:01.117-05:00",
        "frequency": "Monthly",
        "id": 1234321,
        "installments": 5,
        "next_process_date": "2021-04-27",
        "process_date": "2021-03-27",
        "updated_at": "2021-03-26T16:03:08.725-05:00"
      }
    ],
    "transit_number": "11111",
    "updated_at": "2020-10-22T13:28:42.000-05:00"
  }
]

This endpoint retrieves all customers for a client.

Customer Validations

Here are the requirements for customers.

Note: -- indicates it applies to all customers, regardless of country

Parameter Country Requirments
name -- present, [a-zA-Z0-9 _'@.&-]
email -- valid email format
custom_identifier -- unique for client, [a-zA-Z0-9 _'@.&-]
phone -- 10 digits
account_number -- 5..18 digits
transit_number CA 5 digits
institution_number CA 3 digits
routing_number US 9 digits & legitimate routing number
bank_account_type US "Checking" or "Savings"
authorization_type US "In Person" or "Online"

Address

When adding an address it must meet these requirements.

Parameter Country Requirments
address_1 -- present
city -- present
province_code -- present, 2 letter state or province abbreviation
postal_code -- present

Transaction Schedules

Transaction schedules are the method by which recurring or one time payments are scheduled in Rotessa for a customer.

Create a transaction schedule

curl -X POST -H 'Content-Type: application/json' -H "Authorization: Token token=\"<PLATFORM_API_KEY>\""  -d '{"customer_id":<CUSTOMER_ID>, "custom_identifier": "TS1234", "amount": 100, "frequency": "Monthly", "process_date": "November 24, 2020", "comment": "Membership fees", "platform_payout_amount": 1}' <ROTESSA_ENDPOINT>/v2/clients/<CLIENT_ID>/transaction_schedules

The above command returns JSON structured like this:

{
  "active": true,
  "amount": "100.00",
  "comment": "Membership fees (Created with API)",
  "created_at": "2020-10-22T13:37:34.000-05:00",
  "custom_identifier": "TS1234",
  "financial_transactions": [],
  "frequency": "Monthly",
  "id": 781754,
  "installments": null,
  "next_process_date": "2020-11-24",
  "platform_payout_amount": "1.00",
  "process_date": "2020-11-24",
  "updated_at": "2020-10-22T13:37:34.000-05:00"
}

This endpoint creates a transaction schedule for a customer.

Parameter Required Description
customer_id TRUE The id of the customer.
process_date TRUE The initial date to begin withdrawing funds. (e.g. November 20, 2022)
custom_identifier FALSE Your own unique transaction identifier
amount TRUE The amount of funds to be withdrawn from the customer.
installments FALSE The number of installments. Leave blank to continue withdrawing funds indefinitely.
frequency TRUE "Once", "Twice", "Weekly", "Every Other Week", "Every Four Weeks", "Monthly", "Every Other Month", "Quaterly", "Semi-Annually" or "Yearly"
comment FALSE A place to enter notes for the transaction schedule.
platform_payout_amount FALSE The amount of funds will be withdrawn to be settled to the platform.

Create a transaction schedule with a customer custom_identifier

curl -X POST -H 'Content-Type: application/json' -H "Authorization: Token token=\"<PLATFORM_API_KEY>\""  -d '{"customer_custom_identifier": "MikeSmith", "custom_identifier": "TS1234", "amount": 100, "frequency": "Monthly", "process_date": "November 24, 2020", "comment": "Membership fees", "platform_payout_amount": 1}' <ROTESSA_ENDPOINT>/v2/clients/<CLIENT_ID>/transaction_schedules/create_with_customer_custom_identifier

The above command returns JSON structured like this:

{
  "active": true,
  "amount": "100.00",
  "comment": "Membership fees (Created with API)",
  "created_at": "2020-10-22T13:37:34.000-05:00",
  "custom_identifier": "TS1234",
  "financial_transactions": [],
  "frequency": "Monthly",
  "id": 781754,
  "installments": null,
  "next_process_date": "2020-11-24",
  "platform_payout_amount": "1.00",
  "process_date": "2020-11-24",
  "updated_at": "2020-10-22T13:37:34.000-05:00"
}

This endpoint creates a transaction schedule for a customer.

Parameter Required Description
customer_custom_identifier TRUE The custom identifier of the customer.
process_date TRUE The initial date to begin withdrawing funds. (e.g. November 20, 2022)
custom_identifier FALSE Your own unique transaction identifier
amount TRUE The amount of funds to be withdrawn from the customer.
installments FALSE The number of installments. Leave blank to continue withdrawing funds indefinitely.
frequency TRUE "Once", "Twice", "Weekly", "Every Other Week", "Every Four Weeks", "Monthly", "Every Other Month", "Quaterly", "Semi-Annually" or "Yearly"
comment FALSE A place to enter notes for the transaction schedule.
platform_payout_amount FALSE The amount of funds will be withdrawn to be settled to the platform.

Update a transaction schedule

curl -X PATCH -H 'Content-Type: application/json' -H "Authorization: Token token=\"<PLATFORM_API_KEY>\"" -d '{"amount": 150, "comment": "New Membership fees", "platform_payout_amount": 2}' <ROTESSA_ENDPOINT>/v2/clients/<CLIENT_ID>/transaction_schedules/<TRANSACTION_SCHEDULE_ID>

The above command returns JSON structured like this:

{
  "amount": "150.00",
  "comment": "Membership fees (Created with API)",
  "created_at": "2020-10-22T13:37:34.000-05:00",
  "custom_identifier": "TS1234",
  "financial_transactions": [],
  "frequency": "Monthly",
  "id": 781754,
  "installments": null,
  "next_process_date": "2020-11-24",
  "platform_payout_amount": "2.00",
  "process_date": "2020-11-24",
  "updated_at": "2020-10-22T13:37:34.000-05:00"
}

This endpoint updates a transaction schedule for a customer.

Parameter Required Description
amount FALSE The amount of funds to be withdrawn from the customer.
comment FALSE A place to enter notes for the transaction schedule.
platform_payout_amount FALSE The amount of funds will be withdrawn to be settled to the platform.

Update a transaction schedule via post

curl -X POST -H 'Content-Type: application/json' -H "Authorization: Token token=\"<PLATFORM_API_KEY>\"" -d '{"id": 781754, "amount": 150, "comment": "New Membership fees", "platform_payout_amount": 2}' <ROTESSA_ENDPOINT>/v2/clients/<CLIENT_ID>/transaction_schedules/update_via_post

The above command returns JSON structured like this:

{
  "amount": "150.00",
  "comment": "Membership fees (Created with API)",
  "created_at": "2020-10-22T13:37:34.000-05:00",
  "custom_identifier": "TS1234",
  "financial_transactions": [],
  "frequency": "Monthly",
  "id": 781754,
  "installments": null,
  "next_process_date": "2020-11-24",
  "platform_payout_amount": "2.00",
  "process_date": "2020-11-24",
  "updated_at": "2020-10-22T13:37:34.000-05:00"
}

This endpoint updates a transaction schedule for a customer.

Parameter Required Description
id TRUE The id of a transaction schedule.
amount FALSE The amount of funds to be withdrawn from the customer.
comment FALSE A place to enter notes for the transaction schedule.
platform_payout_amount FALSE The amount of funds will be withdrawn to be settled to the platform.

Update a transaction schedule with custom identifier

curl -X POST -H 'Content-Type: application/json' -H "Authorization: Token token=\"<PLATFORM_API_KEY>\"" -d '{"custom_identifier": "TS1234", "amount": 150, "comment": "New Membership fees", "platform_payout_amount": 2}' <ROTESSA_ENDPOINT>/v2/clients/<CLIENT_ID>/transaction_schedules/update_with_custom_identifier

The above command returns JSON structured like this:

{
  "amount": "150.00",
  "comment": "Membership fees (Created with API)",
  "created_at": "2020-10-22T13:37:34.000-05:00",
  "custom_identifier": "TS1234",
  "financial_transactions": [],
  "frequency": "Monthly",
  "id": 781754,
  "installments": null,
  "next_process_date": "2020-11-24",
  "platform_payout_amount": "2.00",
  "process_date": "2020-11-24",
  "updated_at": "2020-10-22T13:37:34.000-05:00"
}

This endpoint updates a transaction schedule by custom identifier.

Parameter Required Description
custom_identifier TRUE The custom identifier of a transaction schedule.
amount FALSE The amount of funds to be withdrawn from the customer.
comment FALSE A place to enter notes for the transaction schedule.
platform_payout_amount FALSE The amount of funds will be withdrawn to be settled to the platform.

Create or update a transaction schedule

curl -X POST -H 'Content-Type: application/json' -H "Authorization: Token token=\"<PLATFORM_API_KEY>\""  -d '{"custom_identifier": "custom_transaction_id_321", customer_id":<CUSTOMER_ID>, "amount": 100, "frequency": "Monthly", "process_date": "November 24, 2020", "comment": "Membership fees (Created with API)", "platform_payout_amount": 1}' <ROTESSA_ENDPOINT>/v2/clients/<CLIENT_ID>/transaction_schedules/create_or_update

The above command returns JSON structured like this:

{
  "amount": "100.00",
  "comment": "Membership fees (Created with API)",
  "created_at": "2020-10-22T13:37:34.000-05:00",
  "custom_identifier": "custom_transaction_id_321",
  "financial_transactions": [],
  "frequency": "Monthly",
  "id": 781754,
  "installments": null,
  "next_process_date": "2020-11-24",
  "platform_payout_amount": "1.00",
  "process_date": "2020-11-24",
  "updated_at": "2020-10-22T13:37:34.000-05:00"
}

This endpoint creates or updates a transaction schedule based on "custom_identifier" value. If a transaction schedule with the provided value exists, we will update the transaction schedule with provided data, otherwise a new transaction schedule will be created.

Parameter Required Description
custom_identifier TRUE A custom identifier for a transaction schedule.
customer_id TRUE The id of the customer.
process_date TRUE The initial date to begin withdrawing funds. (e.g. November 20, 2022)
amount TRUE The amount of funds to be withdrawn from the customer.
installments FALSE The number of installments. Leave blank to continue withdrawing funds indefinitely.
frequency TRUE "Once", "Twice", "Weekly", "Every Other Week", "Every Four Weeks", "Monthly", "Every Other Month", "Quaterly", "Semi-Annually" or "Yearly"
comment FALSE A place to enter notes for the transaction schedule.
platform_payout_amount FALSE The amount of funds will be withdrawn to be settled to the platform.

Delete a transaction schedule

curl -X DELETE -H "Authorization: Token token=\"<PLATFORM_API_KEY>\"" <ROTESSA_ENDPOINT>/v2/clients/<CLIENT_ID>/transaction_schedules/<TRANSACTION_SCHEDULE_ID>

This endpoint deletes a transaction schedule for a customer. A successfully deleted transaction schedule will return no errors.

Delete a transaction schedule via post

curl -X POST -H 'Content-Type: application/json' -H "Authorization: Token token=\"<PLATFORM_API_KEY>\"" -d '{"id": "1234"}' <ROTESSA_ENDPOINT>/v2/clients/<CLIENT_ID>/transaction_schedules/destroy_via_post

This endpoint deletes a transaction schedule for a customer. A successfully deleted transaction schedule will return no errors.

Delete a transaction schedule with custom identifier

curl -X POST -H 'Content-Type: application/json' -H "Authorization: Token token=\"<PLATFORM_API_KEY>\"" -d '{"custom_identifier": "custom_transaction_id_321"}' <ROTESSA_ENDPOINT>/v2/clients/<CLIENT_ID>/transaction_schedules/destroy_with_custom_identifier

This endpoint deletes a transaction schedule for a customer. A successfully deleted transaction schedule will return no errors.

Get a transaction schedule

curl "<ROTESSA_ENDPOINT>/v2/clients/<CLIENT_ID>/transaction_schedules/<TRANSACTION_SCHEDULE_ID>" -H "Authorization: Token token=\"<PLATFORM_API_KEY>\""

The above command returns JSON structured like this:

{
  "amount": "100.00",
  "comment": "Membership fees (Created with API)",
  "created_at": "2020-10-22T13:37:34.000-05:00",
  "custom_identifier": "TS1234",
  "financial_transactions": [],
  "frequency": "Monthly",
  "id": 781754,
  "installments": null,
  "next_process_date": "2020-11-24",
  "platform_payout_amount": "1.00",
  "process_date": "2020-11-24",
  "updated_at": "2020-10-22T13:37:34.000-05:00"
}

This endpoint retrieves a transaction schedule for a customer.

Get a transaction schedule by custom identifier

curl "<ROTESSA_ENDPOINT>/v2/clients/<CLIENT_ID>/transaction_schedules/show_by_custom_identifier" -H 'Content-Type: application/json' -H "Authorization: Token token=\"<PLATFORM_API_KEY>\"" -d '{"custom_identifier": "TS1234"}'

The above command returns JSON structured like this:

{
  "amount": "100.00",
  "comment": "Membership fees (Created with API)",
  "created_at": "2020-10-22T13:37:34.000-05:00",
  "custom_identifier": "TS1234",
  "financial_transactions": [],
  "frequency": "Monthly",
  "id": 781754,
  "installments": null,
  "next_process_date": "2020-11-24",
  "platform_payout_amount": "1.00",
  "process_date": "2020-11-24",
  "updated_at": "2020-10-22T13:37:34.000-05:00"
}

This endpoint retrieves a transaction schedule for a customer.

Validations

Here are the requirements for transactions.

Parameter Requirments
process_date present, today or in the future
amount present, greater than or equal to 1 and less than or equal to account limit
frequency present
installments nil or number

The frequency must be one of the following:

Frequency
Once
Twice
Weekly
Every Other Week
Every Four Weeks
Monthly
Every Other Month
Quarterly
Semi-Annually
Yearly

Financial Transactions

Financial transactions 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 transaction
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
Chargeback The financial transaction was declined or reversed after being settled

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

Get a financial transaction

curl "<ROTESSA_ENDPOINT>/v2/clients/<CLIENT_ID>/financial_transactions/<FINANCIAL_TRANSACTION_ID>" -H "Authorization: Token token=\"<PLATFORM_API_KEY>\""

The above command returns JSON structured like this:

{
  "id": 1950625,
  "customer_id": 182374,
  "custom_identifier": null,
  "amount": "100.00",
  "process_date": "2020-12-04",
  "status": "Declined",
  "status_reason": "Edit Reject",
  "transaction_schedule_id": 781754,
  "institution_number": "*23",
  "transit_number": "***45",
  "account_number": "*******23",
  "created_at": "2020-12-04T16:03:21.000-06:00",
  "updated_at": "2020-12-08T10:42:49.000-06:00",
  "earliest_approval_date": "2020-12-08",
  "transaction_number": "INV1980184",
  "settlement_date": "2020-12-08",
  "comment": "",
  "zapier_identifier": null
}

This endpoint gets a financial transaction.

Get all financial transactions for a client

curl "<ROTESSA_ENDPOINT>/v2/clients/<CLIENT_ID>/financial_transactions" -H "Authorization: Token token=\"<PLATFORM_API_KEY>\""

The above command returns JSON structured like this:

[
  {
    "id": 1950625,
    "customer_id": 182374,
    "custom_identifier": null,
    "amount": "100.00",
    "process_date": "2020-12-04",
    "status": "Declined",
    "status_reason": "Edit Reject",
    "transaction_schedule_id": 781754,
    "institution_number": "*23",
    "transit_number": "***45",
    "account_number": "*******23",
    "created_at": "2020-12-04T16:03:21.000-06:00",
    "updated_at": "2020-12-08T10:42:49.000-06:00",
    "earliest_approval_date": "2020-12-08",
    "transaction_number": "INV1980184",
    "settlement_date": "2020-12-08",
    "comment": "",
    "zapier_identifier": null
  },
  {
    "id": 1950626,
    "customer_id": 182376,
    "custom_identifier": null,
    "amount": "70.00",
    "process_date": "2020-12-04",
    "status": "Approved",
    "status_reason": null,
    "transaction_schedule_id": 781754,
    "institution_number": "*23",
    "transit_number": "***45",
    "account_number": "*******23",
    "created_at": "2020-12-04T16:03:21.000-06:00",
    "updated_at": "2020-12-08T10:42:49.000-06:00",
    "earliest_approval_date": "2020-12-08",
    "transaction_number": "INV1980190",
    "settlement_date": "2020-12-08",
    "comment": "",
    "zapier_identifier": null
  }
]

This endpoint gets all financial transactions for a client.

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 future and is paginated, showing up to 1000 transactions per page.

Show a transaction report for all clients

curl -X GET -H 'Content-Type: application/json' -H "Authorization: Token token=\"<PLATFORM_API_KEY>\"" -d '{"start_date":"2018-09-12", "end_date":"2019-03-12", "status":"All", "page":1}' <ROTESSA_ENDPOINT>v2/transaction_report

The above command returns JSON structured like this:

[
  {
    "account_number": 111111,
    "amount": "100.00",
    "client_id": 4321,
    "created_at": "2019-01-29T15:46:03.000-05:00",
    "comment": "May Fees",
    "custom_identifier": "MIKEY",
    "customer_id": 1,
    "decline_date": null,
    "earliest_approval_date": null,
    "id": 1233,
    "institution_number": null,
    "process_date": "2019-02-28",
    "settlement_date": "2019-03-7",
    "status": "Future",
    "status_reason": null,
    "transaction_custom_identifieer": "TS1234",
    "transaction_number": null,
    "transaction_schedule_id": 330374,
    "transit_number": null,
    "updated_at": null
  },
  {
    "account_number": 121212,
    "amount": "100.00",
    "client_id": 4325,
    "created_at": "2019-02-29T14:55:16.000-05:00",
    "comment": null,
    "custom_identifier": "MIKEY",
    "customer_id": 1,
    "decline_date": null,
    "earliest_approval_date": null,
    "id": 1234,
    "institution_number": null,
    "process_date": "2019-03-07",
    "settlement_date": "2019-03-14",
    "status": "Future",
    "status_reason": null,
    "transaction_custom_identifieer": null,
    "transaction_number": null,
    "transaction_schedule_id": 330374,
    "transit_number": null,
    "updated_at": null
  }
]

Show a transaction report for a client

curl -X GET -H 'Content-Type: application/json' -H "Authorization: Token token=\"<PLATFORM_API_KEY>\"" -d '{"start_date":"2018-09-12", "end_date":"2019-03-12", "status":"All", "page":1}' <ROTESSA_ENDPOINT>v2/clients/<CLIENT_ID>/transaction_report

The above command returns JSON structured like this:

[
  {
    "account_number": 111111,
    "amount": "100.00",
    "client_id": <CLIENT_ID>,
    "created_at": "2019-01-29T15:46:03.000-05:00",
    "comment": "May Fees",
    "custom_identifier": "MIKEY",
    "customer_id": 1,
    "decline_date": null,
    "earliest_approval_date": null,
    "id": 1233,
    "institution_number": null,
    "process_date": "2019-02-28",
    "settlement_date": "2019-03-7",
    "status": "Future",
    "status_reason": null,
    "transaction_custom_identifieer": "TS1234",
    "transaction_number": null,
    "transaction_schedule_id": 330374,
    "transit_number": null,
    "updated_at": null
  },
  {
    "account_number": 121212,
    "amount": "100.00",
    "client_id": <CLIENT_ID>,
    "created_at": "2019-02-29T14:55:16.000-05:00",
    "comment": null,
    "custom_identifier": "MIKEY",
    "customer_id": 1,
    "decline_date": null,
    "earliest_approval_date": null,
    "id": 1234,
    "institution_number": null,
    "process_date": "2019-03-07",
    "settlement_date": "2019-03-14",
    "status": "Future",
    "status_reason": null,
    "transaction_custom_identifieer": null,
    "transaction_number": null,
    "transaction_schedule_id": 330374,
    "transit_number": null,
    "updated_at": null
  }
]

The endpoint provides four parameters which can be queried.

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

The status parameter can be one of the following values.

Parameter Description
'All' Return all 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

Transaction Decline Report

The transaction decline report endpoint is the main interface by which your system can determine the transactions that were declined or charged back on a given date. The transaction decline report is limited to transcations declined on the current date or in the past and is paginated, showing up to 1000 transactions per page.

The 'status' parameter will be one of the following values.

Parameter Description
'Declined' Declined transaction. This a failed transaction
'Chargeback' Chargeback transaction. This a failed transaction after it was settled

Show a transaction report

curl -X GET -H 'Content-Type: application/json' -H "Authorization: Token token=\"<PLATFORM_API_KEY>\"" -d '{"start_date":"2018-09-12", "end_date":"2019-03-12", "page":1}' <ROTESSA_ENDPOINT>v2/clients/<CLIENT_ID>/transaction_decline_report

The above command returns JSON structured like this:

[
  {
    "account_number": 111111,
    "amount": "100.00",
    "created_at": "2019-01-29T15:46:03.000-05:00",
    "comment": "May Fees",
    "custom_identifier": "MIKEY",
    "customer_id": 1,
    "decline_date": "2019-03-6",
    "earliest_approval_date": null,
    "id": 1233,
    "institution_number": null,
    "process_date": "2019-02-28",
    "settlement_date": "2019-03-7",
    "status": "Declined",
    "status_reason": "NSF",
    "transaction_custom_identifieer": "TS1234",
    "transaction_number": null,
    "transaction_schedule_id": 330374,
    "transit_number": null,
    "updated_at": null
  },
  {
    "account_number": 121212,
    "amount": "100.00",
    "created_at": "2019-02-29T14:55:16.000-05:00",
    "comment": null,
    "custom_identifier": "MIKEY",
    "customer_id": 1,
    "decline_date": "2019-03-20",
    "earliest_approval_date": null,
    "id": 1234,
    "institution_number": null,
    "process_date": "2019-03-07",
    "settlement_date": "2019-03-14",
    "status": "Chargeback",
    "status_reason": "NSF",
    "transaction_custom_identifieer": null,
    "transaction_number": null,
    "transaction_schedule_id": 330374,
    "transit_number": null,
    "updated_at": null
  }
]

The endpoint provides four parameters which can be queried.

Parameter Required Description
start_date TRUE The earliest decline date (YYYY-MM-DD) of the list of transactions
end_date FALSE The last decline date (YYYY-MM-DD) of the list of transactions. Optional
page FALSE Page selected based on 1000 transactions per page

Settlements

The settlements endpoint shows the settlement totals by settlement date.

Show settlements by settlement date

curl -X POST -H 'Content-Type: application/json' -H "Authorization: Token token=\"<PLATFORM_API_KEY>\"" -d '{"start_date":"2018-09-12", "end_date":"2019-03-12" }' <ROTESSA_ENDPOINT>v2/clients/<CLIENT_ID>/settlements/show_by_settlement_date

The above command returns JSON structured like this:

[
  {
    "number_approved": 2,
    "number_chargeback": 0,
    "number_declined": 0,
    "number_payout": 2,
    "settlement_date": "2018-09-12",
    "total_approved": "1037.48",
    "total_chargeback": "0.00",
    "total_declined": "0.00",
    "total_payout": "4.52"
  },
  {
    "number_approved": 1,
    "number_chargeback": 0,
    "number_declined": 0,
    "number_payout": 1,
    "settlement_date": "2019-03-10",
    "total_approved": "580.00",
    "total_chargeback": "0.00",
    "total_declined": "0.00",
    "total_payout": "2.26"
  }
]

The endpoint provides two parameters which can be queried.

Parameter Required Description
start_date TRUE The earliest settlement date (YYYY-MM-DD) of the list of settlements
end_date FALSE The last settlement date (YYYY-MM-DD) of the list of settlements. Optional (defaults to current date)

Payout Report

Get payout report

curl -X GET -H 'Content-Type: application/json' -H "Authorization: Token token=\"<PLATFORM_API_KEY>\"" -d '{"start_date":"2019-09-12", "end_date":"2020-12-12"}' <ROTESSA_ENDPOINT>/v2/payout_report

The above command returns JSON structured like this:

[
  {
    "amount": "1.0",
    "customer": {
      "account_number": "23123132",
      "active": true,
      "authorization_type": null,
      "bank_account_type": null,
      "bank_name": "Scotiabank",
      "created_at": "2020-10-22T13:27:34.000-05:00",
      "custom_identifier": "MikeSmith",
      "customer_type": "Personal",
      "email": "[email protected]",
      "home_phone": null,
      "id": 174527,
      "identifier": "MIKESMIT0007",
      "institution_number": "333",
      "name": "Mike Smith",
      "phone": "",
      "routing_number": null,
      "transit_number": "11111",
      "updated_at": "2020-10-22T13:35:29.000-05:00"
    },
    "financial_transaction": null,
    "id": null,
    "status": "Future",
    "transaction_amount": "100.00"
  }
]

This endpoint returns payouts between the specified dates.

Owners

Those who are owners in the company.

Field Description
id ID of the owner
address Owners address
completion_status All information present for owner if complete
date_of_birth Owners birth date
name Full name
position Position in the company

Get all owners for a client

curl "<ROTESSA_ENDPOINT>/v2/clients/<CLIENT_ID>/owners" -H "Authorization: Token token=\"<PLATFORM_API_KEY>\""

The above command returns JSON structured like this:

[
  {
    "address": {
      "address_1": "123 Main Street",
      "address_2": "Unit 4",
      "city": "Toronto",
      "id": 12345,
      "postal_code": "M1B 0B7",
      "province_code": "ON"
    },
    "completion_status": "Complete",
    "date_of_birth": "2020-06-01",
    "id": 2350,
    "name": "test name",
    "position": "test position"
  },
  {
    "address": {
      "address_1": "123 Unkown Street",
      "address_2": null,
      "city": "Vancovour",
      "id": 12346,
      "postal_code": "G2A 1R6",
      "province_code": "BC"
    },
    "completion_status": "Complete",
    "date_of_birth": "2020-03-01",
    "id": 2351,
    "name": "test name 2",
    "position": "test position 2"
  }
]

This endpoint gets all owners for a client.

Signup Terms

Get signup terms

curl -X GET -H 'Content-Type: application/json' -H "Authorization: Token token=\"<PLATFORM_API_KEY>\"" <ROTESSA_ENDPOINT>/v2/signup_terms

The above command returns JSON structured like this:

{
  "terms": "\u003ch1\u003eRotessa Connected Platform Client Agreement (Canada)\u003c/h1\u003e \u003cp\u003eThis agreement outlines the terms and conditions of using The Rotessa Connect Platform and explains how to enable Rotessa to start accepting bank payments through our Third Party Platform Partners.\u003c/p\u003e \u003cp\u003eYour integration and use of The Rotessa Connect Platform is subject to your acceptance of the terms and conditions of this agreement and the Rotessa Client Agreement which governs the general use of Rotessa. ..."
}

This endpoint returns the current signup terms for platforms.